Add-on Partner API の v3 への移行

最終更新日 2020年07月13日(月)

アドオンを構築したのが (Add-on Partner API v3​ がデフォルトのバージョンになった) 2018 年 5 月より前である場合、Add-on Partner API の v1​ については理解しているはずです。Add-on Partner API の v3 では、v1 に固有の多くの問題が修正され、より優れた非同期パターンが導入されています。

この記事では、v1 と v3 の違いについて説明し、考えられる将来の方向性を提示します。

v1 と v3 の相違点の概要

Add-on Partner API​ の v3 の特徴は以下のとおりです。

  • アドオンの非同期プロビジョニング​をサポートすることをパートナーに奨励しています。
  • パートナー向け Platform API​ がデフォルトで使用できます。
  • Accept​ ヘッダーでリクエストのバージョンが指定されます (こちらの説明​を参照)。
  • あいまいな heroku_id​ をプロビジョニング、プラン変更、その他のリクエストに使用しません。
  • プロビジョニングリクエストでは、uuid​ を使用してアドオンのリソースを明確に識別します。
  • プロビジョニングリクエスト内の callback_url​ は、従来の /vendor​ 名前空間ではなく、パートナー向け Platform API​ 用の URL です。
  • SSO 統合では、アドオンパートナーによって作成された provider_id​ の代わりに、別のトークンと新しい uuid​ を使用します。

以上の変更の理由

すべての変更は、明確さとセキュリティを向上させ、より新しい分散コンピューティングパターンを実装することに重点を置いています。 これらの変更が重要であると考えた理由、また実際にいくつかの変更を行った理由について、以下でわかりやすく説明します。

非同期プロビジョニング

一部のアドオンパートナーのプロビジョニングプロセスでは、調整が完了するまで数秒以上かかる場合がありますが、非同期プロビジョニングはそのような状況に適しています。

新しい v3 API には、入念に定義された高度な機能として、アドオンの非同期プロビジョニング​が含まれています。 将来の API リリースでは、非同期プランの変更とプロビジョニング解除も実装される可能性があります。

従来の v1 API にあった何種類かのアドホック非同期プロビジョニングパターンも、当面は引き続きサポートされます。

パートナー向け Platform API

パートナー向け Platform API​ とスコープ付き OAuth トークンを使用して、アドオンからメインの Platform API のサブセットにアクセスできます。これによりアドオンパートナーは、Heroku のエコシステムとより深く安全に統合し、従来の App Info API​ を置き換えることができます。 これは、アドオンの環境設定を更新したり、アプリ、共同作業者、アタッチメント、その他のアドオンリソースに固有のメタデータを取得したりするための推奨される方法です。

パートナー向け Platform API​ は従来の v1 統合下で使用できます。v3 への移行を開始する前に、パートナー向け Platform API を介して OAuth トークンやその他のメタデータをバックフィルすることを検討してください。

HTTP ヘッダーでのリクエストのバージョン指定

ここで説明しているように​ HTTP ヘッダーでリクエストのバージョンを指定すると、Add-on Partner API の動作が他のパブリック Heroku API と一致するようになり、一貫性が向上します。

新しい Accept: application/vnd.heroku-addons+json; version=3​ HTTP ヘッダーを含めるか除外するかによって、統合 API エンドポイントに対する v1 リクエストか v3 リクエストかを区別できます。

heroku_id、provider_id の非推奨化と UUID の導入

従来の v1 API では、リソースを一意に識別する方法に関してアドオンパートナーが判断に迷うことが頻繁にありました。heroku_id​ か、provider_id​ か、それとも他の何か、というものです。

さらに、アドオンで many_per_app​ をサポートする場合や、アプリケーションに複数のリソースがある場合に、heroku_id​ 識別子ではあいまいさの排除ができません。

v3 では、リソースごとに付与され、プロビジョニング中に送信​される uuid​ を使用して、リソースを一意に識別することを明確にしました。今後は、このリソース固有の uuid​ が、後続のすべてのアドオンリクエストパスおよび JSON ペイロードに含まれることになります。

新しい UUID を使用するように SSO を再設計

v3 では、従来の provider_id​ の代わりに新しい uuid​ を使用するようにシングルサインオン​の実装を更新しました。

v1 から v3 にアップグレードする手順

v1 から v3 へのアップグレードは、複数の手順で構成され、入念な計画が求められるプロセスです。リスク、ダウンタイム、エンジニアリング工数を最小化する方法を以下で提案します。

アドオンのステージングバージョンの作成

v1 から v3 へのアップグレードプロセスはかなり複雑になる可能性があるため、アドオン統合エンドポイントの <your add-on slug>-staging​ バージョンを別個に作成してこのプロセスをテストすることをお勧めします。手順は次のとおりです。

  1. プロビジョニングインフラストラクチャのステージングインスタンスをデプロイします。

  2. addons-admin CLI プラグイン​を使用して、既存のアドオンマニフェストファイル​をコピーします。

    $ cp addon-manifest.json <add-on slug>-staging/
$ cd <add-on slug>-staging/
$ # Open `addon-manifest.json` in your favorite editor and modify id (the slug), the password,
$ # the sso_salt, and URLs match your staging add-on API endpoints and infrastructure.
$ # It's important to change the "id" attribute or you could interrupt your
$ # existing add-on infrastructure.
$ # Finally, use the addons-admin CLI plugin to push your manifest.
$ heroku addons:admin:manifest:push

  3. 一般的なアドオンプロビジョニングシナリオのセットを複製します。いくつかのテストアプリを作成し、ステージングアドオンをこれらのアプリにプロビジョニングすることができます。アプリがアタッチ可能である場合、いくつかのアタッチメントも作成できます。Heroku CLI または直接の Platform API​ 呼び出しは、このテスト環境の作成をスクリプト化するのに役立つことがあります。

本番環境のアドオンと同等になるようにステージングアドオンを設定する作業について支援が必要な場合は、エコシステムサポートにお問い合わせください​。

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

いくつかの新しい属性がプロビジョニング中に​ POST されるため、プラン、リージョンなどに加えてこれらの属性を取得する必要があります。特に重要な v3 固有の属性には、次のものがあります。

  • uuid​ - 非推奨になった heroku_id​ および provider_id​ 値に代わって、アドオンリソースを一意に識別するために使用する UUID。
  • oauth_grant:code​ - リソーススコープの OAuth トークン (詳細は後述) と交換するために使用されます。
  • oauth_grant:expires_at​ - 上記の oauth_grant:code​ の期限切れ日時を定義するタイムスタンプ。グラントコードの交換は 5 分以内に行う必要があります。

アドオンリソースの uuid のバックフィル

これは、少なくとも 2 つの方法で実行できます。

  1. JSON ペイロード内の resource​.​uuid​ 値を使用して従来の Get All Apps​ API を呼び出します。
  2. OAuth アクセストークンをバックフィルしてから、パートナー向け Platform API のアドオンリソース関連エンドポイント​を使用します。

OAuth トークン交換の実装

パートナー向け Platform API の利用を開始するには、グラントコードの交換​を実装する必要があります。 これは、追加のプロビジョニング属性の取得の一環として実装できます。

非同期プロビジョニングを使用する場合はパートナー向け Platform API を使用する必要があり、そのためには OAuth トークン交換を実装する必要があります。

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

アドオンリソースごとにアクセストークンと更新トークンをバックフィル​して、パートナー向け Platform API の使用を開始できるようにします。そのためには、Heroku がパートナーのためにバックフィルエンドポイントを一時的にオープンできるよう、チケットを送信していただく必要があります。

App Info API の呼び出しの置き換え

従来の Add-on Partner App Info API​ の呼び出しを、交換した OAuth トークンを介しての新しいパートナー向け Platform API の呼び出しに置き換えます。 アドオンとその環境に関する追加情報のための呼び出しは、アドオン自体のコンテキストをスコープにしたトークンを使用しているため、より安全になります。

非同期プロビジョニングの実装

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

  1. 関連するメタデータを保存する一方で、プロビジョニングリクエストに 202 Accepted​ 応答ステータスコードを返します
  2. アドオンリソースをバックグラウンドでプロビジョニングします
  3. アドオンインスタンスの環境設定を適切な値で更新します
  4. アドオンを provisioned​ とマークします

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

非同期プロビジョニングと同期プロビジョニングは混在させることができます。決定要因は次のとおりです。

  1. v3 統合を使用していること
  2. 応答ステータスコード
    • 200 OK​ は、アドオンインスタンスがすぐに利用可能であることを意味し、応答で環境設定を送信する必要があります。
    • 202 Accepted​ は、非同期でプロビジョニングしており、別のリクエストで環境設定を更新することを意味します。アドオンを provisioned​ としてマークして使用可能にするために、別のリクエストも送信します。

最終的な移行プラン

ステージングのアドオン統合環境で移行戦略を徹底的にテストしたら、v3 API を使用して統合を顧客に提供する準備は完了です。

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

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

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

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

移行作業中は、遠慮なくエコシステムサポートにお問い合わせください​。