Add-on Partner API の v3 への移行

この記事の英語版に更新があります。ご覧の翻訳には含まれていない変更点があるかもしれません。

最終更新日 2023年05月11日(木)

アドオン API 統合を V1 から V3 にアップグレードするための手順
最終的な移行プラン

2018 年 5 月 (Add-on Partner API V3 をデフォルトバージョンにした日付) より前にアドオンを構築し、まだ移行していない場合、アドオン統合では引き続き従来の Add-on Partner API V1 を使用します。V1 のサポートは、2023 年 7 月 3 日までに終了する予定です。このガイドに従ってアドオンを V3 に移行してください。非推奨タイムラインに変更がある場合は、この記事を更新し、それに応じて Heroku Changelog を通じて告知されます。Add-on Partner API V1 のサポート終了についての詳細は、FAQ の記事を参照してください。

アドオン API 統合を V1 から V3 にアップグレードするための手順

v1 から v3 へのアップグレードは、複数の手順で構成され、入念な計画が求められるプロセスです。このガイドでは、リスク、ダウンタイム、エンジニアリング工数を最小限に抑えるために役立つ移行プロセスについて説明します。

アドオンマニフェストファイルの最新のコピーを取得する

アドオンマニフェストは、Heroku とアドオンサービス実装の間のインターフェースを記述した標準の JSON ドキュメントです。最新バージョンのアドオンマニフェストファイルが手元にない場合は、次の手順に従って最新のコピーを取得します。

まだ実行していない場合は、Heroku CLI をインストールします。
addons-admin プラグインをインストールします。
```
$ heroku plugins:install addons-admin
```

パートナーポータルで、会社のアドオンにアクセスできるユーザーアカウントで Heroku CLI を使用してログインします。

$ heroku login
heroku: Press any key to open up the browser to login or q to exit:
Opening browser to https://cli-auth.heroku.com/auth/cli/browser/...
Logging in... done
Logged in as developer@logcapture.com

ログインに成功したら、アドオンマニフェストファイルのコピーを取得します。
```
$ heroku addons:admin:manifest:pull <addon-slug>
Fetching add-on manifest for logcapture... done
```

これにより、addon-manifest.json ファイルがダウンロードされ、現在のフォルダーに保存されます。

マニフェストファイルにはシークレットが含まれているため、パブリックに共有したり、ソース管理にチェックインしないでください。

マニフェストの例

{
  "id": "logcapture",
  "name": "Log Capture",
  "api": {
    "config_vars_prefix": "LOGCAPTURE",
    "config_vars": [
      "LOGCAPTURE_URL"
    ],
    "password": "20eea05fB9444c18fAe0189603e08baA",
    "sso_salt": "1BDe5132457C99b0E0533c8707C1173c",
    "regions": ["us"],
    "requires": [
      "syslog_drain",
      "log_input"
    ],
    "production": {
      "base_url": "https://logcapture.com/heroku/resources",
      "sso_url": "https://logcapture.com/sso/login"
    },
    "$base": 161253688712354
  }
}

移行が必要かどうかをチェックする

移行する必要があるかどうか確信がない場合は、マニフェストファイルを開き、api の下にある version フィールドを探します。そのキーのフィールドがないか、またはその値が “1” に設定されている場合、このアドオンは引き続き従来の Add-on Partner API V1 統合を使用しているため、移行する必要があります。

バージョンフィールドが “3” に設定されている場合でも、アドオンサービス実装に従来の Add-on Partner App Info API エンドポイントへの参照が含まれているかどうかをチェックすることが重要です。この API は Add-on Partner API V1 と同時に削除されるためです。従来のエンドポイントへの参照を現在の API へのリクエストに置き換える方法については、「パートナー向け Platform API への移行」を参照してください。

移行プロセスにアドオンのステージングバージョンを使用する

本番環境でアップグレードする前に、アドオンサービスのステージング環境を使用して V1 から V3 へのアップグレードプロセスをテストすることを強くお勧めします。アドオンサービスのステージングバージョンを作成したことがない場合は、次の手順に従います。

プロビジョニングインフラストラクチャのステージングインスタンスをデプロイします。
お気に入りのエディタで本番環境のアドオンマニフェストファイルのコピーを開き、id (slug)、password、sso_salt、環境設定、URL フィールドをステージングアドオンの API エンドポイントとインフラストラクチャに一致するように変更します。

Example manifest for staging add-on version
```
{
  "id": "logcapture-staging",
  "name": "Log Capture (staging)",
  "api": {
    "config_vars_prefix": "LOGCAPTURE_STAGING",
    "config_vars": [
      "LOGCAPTURE_STAGING_URL"
    ],
    "password": "6349E6585913eD9a1",
    "sso_salt": "bE27844db7eCf68ae",
    "regions": ["us"],
    "requires": [
      "syslog_drain",
      "log_input"
    ],
    "production": {
      "base_url": "https://logcapture-staging.herokuapp.com/heroku/resources",
      "sso_url": "https://logcapture-staging.herokuapp.com/sso/login"
    },
    "$base": 163008330730686
  }
}
```
id フィールドを正しく変更できなかった場合は、次の手順で本番環境のアドオンインフラストラクチャが中断される可能性があるため、正しく変更していることを確認してください。
ステージングアドオンのマニフェストファイルをプッシュして、そのアドオンのステージングバージョンをパートナーポータル内に作成します。
```
$ heroku addons:admin:manifest:push
```

マニフェストファイルをプッシュすると、パートナーポータルで新しいステージングアドオンを使用できるようになります。

パートナーポータルの [アドオン] ページ

ステージングアドオンのバージョンは、常にアルファ版のリリース段階に保持されるため、これ以上の設定は必要ありません。アルファ版アドオンには、無料のテストプランしかありません。これを使用すると、パートナーポータルの会社ユーザーは、ステージングアドオンを自分のアプリにプロビジョニングできます。

test プランには「Invite Only」 (招待のみ) の可用性があります。会社ユーザーではないユーザーにプロビジョニングアクセスを付与する必要がある場合は、https://addons-next.heroku.com/addons/your-addon-slug/plans に移動し、プランパスを作成します。

テストの場合は、一般的なアドオンプロビジョニングシナリオのセットを複製します。いくつかのテストアプリを作成し、ステージングアドオンをこれらのアプリにプロビジョニングすることができます。アプリがアタッチ可能である場合、いくつかのアタッチメントも作成できます。

ステージングアドオンを本番環境のアドオンと同等に設定する方法については、Heroku サポートにお問い合わせください。

プロビジョニング中に追加の属性の取得を開始する

プロビジョニングリクエストで Heroku から送信されるヘッダーとペイロードは、統合 API の従来のバージョンと新しいバージョンの間で非常によく似ています。ただし、保持する必要がある追加の属性と、非推奨になったためにもう依存するべきではない既存の属性がそれぞれいくつかあります。

従来の Add-on Partner API V1 統合でのプロビジョニングリクエストの例

POST /heroku/resources HTTP/1.1
Host: logcapture-staging.herokuapp.com
Authorization: Basic bG9nY2FwdHVyZS1zdGFnaW5nOjYzNDlFNjU4NTkxM2VEOWExCg==
Content-Type: application/json
Accept: application/json

{
  "callback_url": "https://api.heroku.com/vendor/apps/649251da-3453-495b-bad0-6749a18f7e31",
  "heroku_id": "app987654321@heroku.com",
  "plan": "test",
  "region": "amazon-web-services::us-east-1",
  "syslog_token": "d.93c3d476-baa7-4aa0-856d-93710516af11",
  "log_drain_token": "d.93c3d476-baa7-4aa0-856d-93710516af11",
  "logplex_token": "t.516c8640-5792-4274-9365-b2c26c0a427d",
  "log_input_url": "https://token:t.516c8640-5792-4274-9365-b2c26c0a427d@1.us.logplex.io/logs",
  "options": {
    "foo": "bar",
    "baz": "true"
  }
}

リクエストヘッダーは、Accept ヘッダーに割り当てられる値に関してのみ異なります。ここには、従来の API V1 の場合は application/json、現在の API の場合は application/vnd.heroku-addons+json; version=3 の MIME タイプが含まれます。

Add-on Partner API V3 では、受け入れて、すでに取得していた情報と共に保持する必要がある次の属性がペイロードに追加されています。

uuid (必須) - アドオンリソースを一意に識別するために、非推奨になった heroku_id および provider_id 値の代わりに使用する UUID。
name (オプション) - プロビジョニングされるリソースに割り当てられた論理名。より暗号的な UUID の代わりに、メッセージや通知で使用される顧客が目にする識別子として機能することを目的にしています。
oauth_grant:code と oauth_grant:type (必須) - リソーススコープの OAuth トークン (詳細は下記を参照) と交換するために使用されます。
oauth_grant:expires_at (必須) - 上記の oauth_grant:code がいつ期限切れになるかを定義するタイムスタンプ。グラントコードの交換は 5 分以内に行う必要があります。

Add-on Partner API V3 統合でのプロビジョニングリクエストの例

POST /heroku/resources HTTP/1.1
Host: logcapture-staging.herokuapp.com:443
Authorization: Basic bG9nY2FwdHVyZS1zdGFnaW5nOjYzNDlFNjU4NTkxM2VEOWExCg==
Content-Type: application/json
Accept: application/vnd.heroku-addons+json; version=3

{
  "callback_url": "https://api.heroku.com/addons/5b449238-b37d-4a6b-9ca1-28d7c864dd15",
  "uuid": "5b449238-b37d-4a6b-9ca1-28d7c864dd15",
  "name": "pouph-gps-filter",
  "plan": "test",
  "region": "amazon-web-services::us-east-1",
  "syslog_token": "d.93c3d476-baa7-4aa0-856d-93710516af11",
  "log_drain_token": "d.93c3d476-baa7-4aa0-856d-93710516af11",
  "oauth_grant": {
    "code": "2d7e4b11-f51a-413f-abb5-93f149b2742b",
    "expires_at": "2021-09-06T09:19:26.19-07:00",
    "type": "authorization_code"
  },
  "log_input_url": "https://token:t.516c8640-5792-4274-9365-b2c26c0a427d@1.us.logplex.io/logs",
  "options": {
    "foo": "bar",
    "baz": "true"
  }
}

Add-on Partner API V3 ではまた、heroku_id (uuid が優先される) と logplex_token (log_input_url で置き換えられる) の非推奨属性もすべてペイロードから削除されます。

OAuth トークン交換の実装

プロビジョニングリクエストで受信されたグラントコードを使用すると、パートナー向け Platform API を操作するために必要になる OAuth トークンを取得できます。グラントコード交換プロセスでは、リクエストを認証するためのベアラートークンとして使用される有効期限が設定できる access_token と、期限切れになった後に新しい access_token を取得するために必要な期限が長い refresh_token の 2 つのトークンが返されます。access_token では、それが作成された対象のアドオンリソースに関するデータを要求することしか承認されないことに注意してください。Platform API でアドオンリソースのデータへのアクセスを取得するには、それぞれの access_token を使用する必要があります。レスポンスはすべて、access_token が作成された対象のアドオンリソースにスコープ指定されます。

このプロセスでは、次のフォームエンコードされたパラメータ文字列を本文として使用して、https://id.heroku.com/oauth/token に POST リクエストを送信する必要があります。

grant_type: プロビジョニングリクエストからの oauth_grant:type。
code: プロビジョニングリクエストからの oauth_grant:code。
client_secret: アドオンの [Partner Portal] (パートナーポータル) ページの OAuth Credentials セクションの Settings タブにあります。

パートナーポータル内のクライアントシークレットの場所

curl を使用したグラント交換の対話の例

$ curl -X POST https://id.heroku.com/oauth/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=authorization_code&code=2d7e4b11-f51a-413f-abb5-93f149b2742b&client_secret=36f595fb-47a9-4b57-9e9e-18ca14ae65da"

{
  "access_token": "829571d6-7842-4868-8093-995a8d09a1a4",
  "expires_in": 28800,
  "refresh_token": "c37b53c0-221f-458a-b5e5-5054902004ec",
  "token_type": "Bearer",
  "user_id": "415dd4f9-ba7d-45db-a9ac-8aab248af5df",
  "session_nonce": null
}

グラント交換エンドポイントに正しい POST を送信すると、アドオンサービス実装のための次の目的とする属性を含む 200 - OK レスポンスが返されます。

access_token - 1 つのアドオンリソースにスコープ指定されたパートナー向け Platform API にアクセスするために使用されます。通常は、8 時間ごとに期限切れになりますが、特定の状況 (資格情報のローテーションなど) では早く期限切れになることがあります。Platform API へのリクエストで 401 - Unauthorized レスポンスが返された場合は、トークン更新プロセス (以下で説明) を使用して新しいトークンの取得を試みた後、リクエストを再試行する必要があります。
refresh_token: アドオンの有効期間中は有効であり、有効な OAuth client_secret を使用して、必要に応じて何回でも新しい access_token に交換できます。
expires_in: access_token が有効な秒数。
token_type: トークンのタイプは、パートナー向け Platform API へのリクエストの Authorization ヘッダーで使用されます。

このグラント交換プロセスは、追加のプロビジョニング属性を取得するときに、前の手順の一部として実装する可能性があります。OAuth グラントが交換されたら、access_token、refresh_token、有効期限を自分の側にあるアドオンのリソースレコードにただちに保存します。これらの情報を後で API から取得する方法はありません。アドオンリソースに関連付けられている更新トークンが失われた場合は、サポートチケットを作成することによって当社サポートまでご連絡ください。

access_token および refresh_token 値を永続ストレージに書き込むときは、client_secret と同様に、必ず暗号化してください。これらの秘密鍵を保存時にプレーンテキストにしたり、それらの復号化キーを簡単に見つけやすくしたりするべきではありません。

アクセストークンの更新を実装する

access_token は最大 8 時間 (28,800 秒) 有効ですが、特定の状況 (資格情報のローテーションなど) では早く期限切れになることがあります。refresh_token は不変で、アドオンリソースの有効期間中は有効であり、アドオンの OAuth client_secret を使用して、必要に応じて何回でも新しい access_token に交換できます。

グラント交換と同様に、更新プロセスでは、次のフォームエンコードされたパラメータ文字列を本文として使用して、https://id.heroku.com/oauth/token に POST リクエストを送信する必要があります。

grant_type: 渡されるコードのタイプ。この場合は、refresh_token に設定されている必要があります。
refresh_token: 特定のアドオンリソースのグラントコード交換プロセスを使用して受信された不変の refresh_token。
client_secret: アドオンの [Partner Portal] (パートナーポータル) ページの OAuth Credentials セクションの Settings タブにあります。

curl を使用したアクセストークン更新の対話の例

$ curl -X POST https://id.heroku.com/oauth/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=refresh_token&refresh_token=c37b53c0-221f-458a-b5e5-5054902004ec&client_secret=36f595fb-47a9-4b57-9e9e-18ca14ae65da"

{
  "access_token": "9ebed010-233d-4de3-9f2f-fdfeddddd9c7",
  "expires_in": 28800,
  "refresh_token": "c37b53c0-221f-458a-b5e5-5054902004ec",
  "token_type": "Bearer",
  "user_id": "415dd4f9-ba7d-45db-a9ac-8aab248af5df",
  "session_nonce": null
}

アクセストークン更新エンドポイントに正しい POST を送信すると、アドオンサービス実装のための次の目的とする属性を含む 200 - OK レスポンスが返されます。

access_token: パートナー向け Platform API に対して認証されるために必要な新しいアクセストークン。
expires_in: 新しい access_token が有効な秒数。

新しい access_token と有効期限を受信したら、アドオンのリソースレコードを更新することによって、これらの情報を自分の側に保持する必要があります。

リクエストを Platform API に送信するときのエラーを回避するために、期限切れになる前に access_token を更新する必要があります。access_token が期限切れになる前にリクエストへの 401 - Unauthorized レスポンスを受信した場合は、トークンを更新し、リクエストを再試行します。

アドオンリソースの `uuid` と `name` をバックフィルする

移行プロセス内のこの時点では、プロビジョニング中にアドオンサービス実装で追加の属性を取得できますが、そのリソース UUID、名前、または OAuth トークンが欠落している既存のアドオンリソースが存在します。

すべての欠落しているリソース UUID (オプションで、名前も) をバックフィルするには、従来の Add-on Partner App Info API のすべてのアプリの取得エンドポイントを使用して、https://api.heroku.com/vendor/apps に GET リクエストを送信します。この API では、資格情報がマニフェスト ID (アドオン slug) とパスワードである基本認証を使用します。レスポンスは、アドオンサービスがプロビジョニングされている各アプリの要素を持つ JSON 配列になります。各要素には、必要な uuid および name 属性を持つ resource オブジェクトが含まれます。

curl を使用してリソース UUID と名前を取得する例

$ curl https://logcapture-staging:6349E6585913eD9a1@api.heroku.com/vendor/apps

[
  {
    "callback_url": "https://api.heroku.com/vendor/apps/fc045862-3954-4869-80d3-0a69063f995f",
    "heroku_id": "app888888888@heroku.com",
    "name": "test-app-1",
    "resource": {
      "uuid": "fc045862-3954-4869-80d3-0a69063f995f",
      "name": "logcapture-staging-silhouetted-45667"
    },
    "plan": "test",
    "provider_id": "provider_id_12345"
  },
  {
    "callback_url": "https://api.heroku.com/vendor/apps/e5d0dc92-0e7d-4720-af67-0ec40198421f",
    "heroku_id": "app878787878@heroku.com",
    "name": "test-app-2",
    "resource": {
      "uuid": "e5d0dc92-0e7d-4720-af67-0ec40198421f",
      "name": "logcapture-staging-concave-99081"
    },
    "plan": "test",
    "provider_id": "provider_id_67890"
  }
]

アドオンサービスに 4,000 を超えるリソースがプロビジョニングされている場合、エンドポイントレスポンスはページ分割され、前のページと次のページを指す URL を含む HTTP Link ヘッダーがレスポンスに設定されます。

OAuth アクセストークンと更新トークンのバックフィル

アドオンを移行する前に作成されたアドオンリソースのアクセスおよび更新トークンと交換する OAuth グラントコードは存在しません。欠落している OAuth グラント情報は、エンドポイントを使用して取得できます。セキュリティ上の理由から、このエンドポイントはデフォルトでブロックされます。アクセスを要求するには、新しいサポートチケットを記録してください。このバックフィルプロセスをテストする予定がある場合は (これを強くお勧めします)、ステージングアドオンのインフラストラクチャ用に、このエンドポイントへのアクセスを要求する必要があります。

アドオンに対してエンドポイントを有効にしたチケットについての通信が終了したら、移行の前に作成されたアドオンリソースごとに、従来の Add-on Partner App Info API の OAuth グラントバックフィルエンドポイントにリクエストを送信します。このエンドポイントでは、プロビジョニングリクエストで送信されたものと同じ構造を持つ oauth_grant オブジェクトが含まれた JSON オブジェクトが返されます。必要な情報を保存し、前に説明したようにグラントコードの交換を実行してトークンを取得します。

返されたグラントコードは、5 分後に期限切れになります。この 5 分以内に access_token と refresh_token のコードを交換しないと、そのコードは期限切れになり、新しい OAuth グラントのためにもう一度リクエストを実行しなければならなくなります。交換に成功したら、それらのトークンをただちにアドオンリソースレコードに保持するようにしてください。OAuth グラントコードが有効で、期限切れになっていない場合でも、トークンがすでに交換されたアドオンリソースに対するリクエストを送信すると、このエンドポイントではエラーが返されます。

curl を使用した OAuth グラントコードのバックフィルの例

$ curl https://logcapture-staging:6349E6585913eD9a1@api.heroku.com/vendor/resources/fc045862-3954-4869-80d3-0a69063f995f/oauth-grant

{
  "oauth_grant": {
    "code": "7cb3faf1-42bd-442d-ac96-ce46333a0b10",
    "type": "authorization_code",
    "expires_at": "2021-09-06T09:19:26.19-07:01"
  }
}

従来の Add-on Partner App Info API の呼び出しを置き換える

アドオンサービスの従来の Add-on Partner App Info API のエンドポイントへのリクエストを新しいパートナー向け Platform API の呼び出しに置き換える方法についての詳細は、「パートナー向け Platform API への移行」を参照してください。

アドオンパートナーのイベント通知を置き換える

アドオンサービスマニフェストファイルの requires 配列に deploy_notify または attach_notify を含めることにより、アドオンでアドオンパートナーのイベント通知を利用している場合は、これを Add-on Partner API 統合の変更に沿った Webhook イベントの実装に置き換える必要があります。さらに、すべての個々のアドオンリソースで適切な Webhook イベント通知 (api:build または api:addon-attachment) を購読する必要があります。Webhook イベントの機能では、アドオンサービス実装で購読する可能性のある拡張されたイベントのセットと、購読や配信を管理するためのより優れた機能が提供されます。

Webhook イベントの購読は、パートナー向け Platform API を使用して作成され、有効なスコープ指定されたアクセストークンを必要とします。すべてのリソースに関する OAuth グラントのバックフィルが完了すると、イベント通知を購読できるようになります。アドオン統合では、プロビジョニングフローの一部として、新しいアドオンリソースでイベント通知を購読する必要があります。

非同期プロビジョニングを実装する (オプション)

完了まで数秒以上かかるプロビジョニングプロセスがある場合、非同期プロビジョニングを実装することをお勧めします。非同期プロビジョニングでは、次のことを行います。

関連するメタデータを保存しながら、プロビジョニングリクエストに 202 - Accepted レスポンスステータスコードを返します。
アドオンリソースをバックグラウンドでプロビジョニングします。
アドオンインスタンスの環境設定を適切な値で更新します。
アドオンを provisioned としてマークします。

最後の 2 つの手順は、パートナー向け Platform API を使用して実行されます。

アドオンでは、非同期プロビジョニングと同期プロビジョニングの両方を使用できます。それらを混在させるための前提条件を次に示します。

Add-on Partner API V3 統合がすでに実装されていること。
レスポンスステータスコードが次のとおりであること。
- 200 - OK は、アドオンインスタンスがすぐに利用可能であることを意味し、応答で環境設定を送信する必要があります。
- 202 - Accepted は、非同期でプロビジョニングしており、別のリクエストで環境設定を更新することを意味します。アドオンを provisioned としてマークして使用可能にするために、別のリクエストも送信します。

最終的な移行プラン

移行の早い時期にサポートチケットを開くことをお勧めします。これにより、Heroku エコシステムエンジニアリングチームとの対話が開始されると共に、当社の共有されている顧客へのサービス中断のないスムーズな移行が保証されます。ご連絡をいただくと、当社では次のことが可能になります。

お客様の環境に、テストの準備ができていて、本番環境のアドオンと同等のステージングアドオン統合が存在することを確認できます。
次のように、各移行手順の作業を調整できます。
- 新しいリソースがプロビジョニングされたときに、アドオンサービスで OAuth グラントを受信できるようにします。
- OAuth グラントバックフィルエンドポイントを有効にします。
- 非同期プロビジョニングを有効にします。
- アドオンサービスの API バージョンを更新します。

ステージングアドオン統合環境で移行戦略を徹底的にテストしたら、当社のエンジニアリングチームの支援により、V3 API との統合を本番環境レベルでロールアウトする準備ができます。

次に示すのは、ダウンタイムを最小限にする移行戦略の一例です。

移行期間中は、503 - Service Unavailable ステータスコードを使用して、プロビジョニング、プロビジョニング解除、プラン変更のリクエストをすべて拒否します。必要なリクエストは最大 12 時間にわたって再試行され、適切なエラーメッセージが顧客に表示されます。
追加のメタデータを保存するために、必要なデータベースの変更を適用します。
策定したバックフィル戦略を実行して、v1 リソース用の UUID、OAuth トークン、その他のメタデータをバックフィルします。
アドオンにイベント通知が必要な場合は、オプションで、リソースごとの Webhook イベントの購読を作成します。
アドオンマニフェストをバージョン 3 に変更して公開します。新しいバージョンでマニフェストをプッシュすることは、v3 API の使用準備ができたことを Heroku に知らせるトリガーです。
バックグラウンドジョブの実行基盤で、必要に応じて非同期プロビジョニングのためにジョブをディスパッチしていることを確認します。
有効にした 503 - Service Unavailable 応答ゲートウェイを削除して、応答の受け付けを開始します。
プロビジョニング、プロビジョニング解除、プラン変更が正しく機能していることをテストします。

ダウンタイムが発生しない別の移行戦略は、次のようになります。

引き続き V1 リクエストを受け付けながら、V3 リクエスト (Accept: ヘッダーで識別される) を受け付けるコードをデプロイします。
追加のメタデータを保存するために、必要なデータベースの変更を適用します。
v3 環境下で送信される新しいリソースの OAuth トークンの取得を開始します。
策定したバックフィル戦略を実行して、v1 リソース用の UUID、OAuth トークン、その他のメタデータをバックフィルします。
アドオンサービスにイベント通知が必要な場合は、オプションで、リソースごとの Webhook イベントの購読を作成します。
アドオンマニフェストをバージョン 3 に変更して公開します。新しいバージョンでマニフェストをプッシュすることは、v3 API の使用準備ができたことを Heroku に知らせるトリガーです。
Heroku の統合 API が v3 リクエストの送信を開始した後に、パートナーの統合 API から v1 固有のコードを削除します。
プロビジョニング、プロビジョニング解除、プラン変更が正しく機能していることをテストします。

Categories

Add-on Partner API の v3 への移行

Table of Contents

アドオン API 統合を V1 から V3 にアップグレードするための手順

アドオンマニフェストファイルの最新のコピーを取得する

マニフェストの例

移行が必要かどうかをチェックする

移行プロセスにアドオンのステージングバージョンを使用する

Example manifest for staging add-on version

プロビジョニング中に追加の属性の取得を開始する

従来の Add-on Partner API V1 統合でのプロビジョニングリクエストの例

Add-on Partner API V3 統合でのプロビジョニングリクエストの例

OAuth トークン交換の実装

パートナーポータル内のクライアントシークレットの場所

curl を使用したグラント交換の対話の例

アクセストークンの更新を実装する

curl を使用したアクセストークン更新の対話の例

アドオンリソースの `uuid` と `name` をバックフィルする

curl を使用してリソース UUID と名前を取得する例

OAuth アクセストークンと更新トークンのバックフィル

curl を使用した OAuth グラントコードのバックフィルの例

従来の Add-on Partner App Info API の呼び出しを置き換える

アドオンパートナーのイベント通知を置き換える

非同期プロビジョニングを実装する (オプション)

最終的な移行プラン

関連カテゴリー

Categories

Add-on Partner API の v3 への移行

Table of Contents

アドオン API 統合を V1 から V3 にアップグレードするための手順

アドオンマニフェストファイルの最新のコピーを取得する

マニフェストの例

移行が必要かどうかをチェックする

移行プロセスにアドオンのステージングバージョンを使用する

Example manifest for staging add-on version

プロビジョニング中に追加の属性の取得を開始する

従来の Add-on Partner API V1 統合でのプロビジョニングリクエストの例

Add-on Partner API V3 統合でのプロビジョニングリクエストの例

OAuth トークン交換の実装

パートナーポータル内のクライアントシークレットの場所

curl を使用したグラント交換の対話の例

アクセストークンの更新を実装する

curl を使用したアクセストークン更新の対話の例

アドオンリソースの uuid と name をバックフィルする

curl を使用してリソース UUID と名前を取得する例

OAuth アクセストークンと更新トークンのバックフィル

curl を使用した OAuth グラントコードのバックフィルの例

従来の Add-on Partner App Info API の呼び出しを置き換える

アドオンパートナーのイベント通知を置き換える

非同期プロビジョニングを実装する (オプション)

最終的な移行プラン

関連カテゴリー

アドオンリソースの `uuid` と `name` をバックフィルする