パートナー向け Platform API

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

最終更新日 2023年03月08日(水)

アドオンパートナーは、OAuth 経由で Heroku Platform API のサブセットにアクセスできます。このサブセットは、パートナー向け Platform API​ と呼ばれます。パートナー向け Platform API は、従来の App Info API​ と同じ機能に加えて、以下の重要な利点を提供します。

  • パートナー向け Platform API では、App Info API でサポートされていない多くの公式エンドポイントが提供されます。これらのエンドポイントを使用して、セキュリティ設定の検査、同じアドオンの他の顧客インスタンスの検出などを実行できます。
  • パートナー向け Platform API のエンドポイントは、一貫性と “可搬性” が向上しています。これらのエンドポイントは Heroku 内部で使用されており、顧客も直接使用します。

2022 年 9 月の時点で、addons.heroku.com API V3 /apps​ エンドポイントを使用して、アドオンがインストールされているアプリの完全な一覧を取得できます。詳細は、このドキュメント​の Apps​ (アプリ) セクションを確認してください。

アドオンで利用可能なエンドポイントの完全なリストは、標準 Platform API エンドポイントのリスト​を参照してください。

プロビジョニングされたアドオンは、アドオンパートナーにとって、アドオンリソースとその関連付けについての適切なレコードに Platform API を介してアクセスするための承認ステップとして機能します。

プロビジョニング中に作成されたトークンは、その後、多数の Platform API エンドポイントへのリクエストを認証するために使用できます。Platform API​ は、スキーマのドキュメントが十分に整備されており、すべての顧客向けツールからすでに利用可能です。

導入される新しい概念のうちアドオンに関連するのは、OAuth クライアントシークレット、いくつかの OAuth 承認、プロビジョニングされたアドオンごとに 1 つのトークンです。OAuth クライアントシークレットは、スコープ付きトークンの作成リクエストの認証のみに使用されます。Platform API に対する他のリクエストの認証には使用されません。

チュートリアル

すべての新しいアドオンは、デフォルトで Platform API にアクセスできます。v3 API を使用するすべてのアドオンでも Platform API が標準です。2017 年 5 月 15 日よりも前に作成されたアドオンに関しては、Heroku 側でのフラグ設定が必要になります。フラグを有効化するには、新しいサポートチケットを開いて​ください。

このチュートリアルは、既存の Partner API 統合向けにアドオンを実装済みであることが前提です。「アドオンの構築​」チュートリアルに従い、アドオンのリファレンス実装​を参考にすることで、短時間でこの段階に到達できます。

前提条件として、provision​、planchange​、deprovision​ の Add-on Partner API​ 呼び出しをアドオンで実装済みである必要があります。

v1 アドオンでフラグが有効になると (または v3 を使用している場合)、そのアドオンリソースをスコープにしたアクセストークンと交換できるグラントコードがプロビジョニングリクエストに含まれます。以下でそのプロセスを説明します。

クライアントシークレットの取得

Heroku とのほとんどの OAuth 対話には client_secret​ が必要になります。アドオンの client_secret​ は、アドオンパートナーポータル​の 「OAuth Credentials」 (OAuth 資格情報) ページで確認できます。

新しいアドオンインストールのトークンの取得

グラントコードの受け取り

プロビジョニングリクエストがアドオンに POST されるとき、リクエストには OAuth グラントが含まれています (一部のフィールドを省略しています)。

{
  "options": {},
  "oauth_grant": {
    "code": "01234567-89ab-cdef-0123-456789abcdef",
    "type": "authorization_code",
    "expires_at": "2016-03-03T18:01:31-0800"
  },
  "plan": "basic",
  "region": "amazon-web-services::us-east-1",
  "uuid": "01234567-89ab-cdef-0123-456789abcdef"
}

必ず、応答成功コードでプロビジョニングリクエストに応答してください。サービスで通常よりも長い時間がプロビジョニングに必要な場合は、非同期プロビジョニング​に関するドキュメントを参照してください。

提供されたグラントコードは、Heroku の認証サービスである id.heroku.com​ を使用して、5 分以内にアクセストークンおよび更新トークンに交換できます。

グラントコードの交換

最初のプロビジョニングリクエストに応答成功コードで応答した後、グラントコードを交換します。

最初のプロビジョニングリクエストに成功の応答をしないと、グラントコードは有効になりません。成功以外の応答をした場合、プロビジョニングリクエストは永久に失敗したとみなされてグラントコードは無効になります。

グラントコードを交換するには、Content-Type: application/x-www-form-urlencoded​ のようにグラントコードとクライアントシークレットを含めて https://id.heroku.com/oauth/token​ に POST します。たとえば、curl​ でリクエストを実行する方法は次のとおりです。

$ curl -X POST https://id.heroku.com/oauth/token \
-d "grant_type=authorization_code&code=01234567-89ab-cdef-0123-456789abcdef&client_secret=01234567-89ab-cdef-0123-456789abcdef"

これにより、目的のトークンを含むペイロードが返されます (一部のフィールドを省略しています)。

{
  "access_token": "4594b794-0c94-416b-a374-bb33a025411f",
  "refresh_token": "95a242fe-4c4a-4059-bc06-512de9672619",
  "expires_in": 2592000,
  "token_type": "Bearer"
}

アクセストークンと更新トークンをローカルに保存します。

access_token および refresh_token の値を永続ストレージに書き込むときは、client_secret と同様に必ず暗号化してください​。これらのシークレットをプレーンテキストのまま扱わないでください。また、それらの復号化キーは簡単に見つからない場所に保管してください。Ruby で Sequel を使用している場合は、attr_vault gem​ を評価することを検討してください。

実行するすべての Platform API​ 呼び出しで、そのアドオン用のアクセストークンを認証に使用してください。このトークンは、作成時に対象とされたアドオンリソースに関するデータのリクエストにしか使用できないことに注意してください。各アドオンリソースのデータに Platform API でアクセスするには、リソース別のアクセストークンを使用する必要があります。すべての応答は、アクセストークンの作成時に対象とされたアドオンリソースのスコープになります。

既存のアドオンインストール用のトークンの取得

パートナー向け Platform API の提供開始よりも前から Heroku アドオンパートナーであった場合、既存のアドオンインストールの多くについて OAuth グラントを受け取ったことがないと考えられます。

これらのインストールにアクセストークンと更新トークンを後付けできるよう、OAuth グラントを取得できるエンドポイントを用意しました。セキュリティ上の理由から、このエンドポイントはデフォルトでブロックされており、個別のアドオンパートナーに手動で開放する必要があります。新しいサポートチケットを開いて​、このエンドポイントの利用に関心があることをお知らせください。

前述したように、access_token​、refresh_token​、client_secret​ の値を永続ストレージに書き込むときは、常に暗号化してください。

アクセストークンと更新トークンを後付けする前に、テストアドオンで新規インストールの OAuth フローをテストすることもお勧めします。新規インストール用のフローをテストすることで、OAuth グラントをトークンと交換する機能を構築できます。

エンドポイントが開放されたことの確認を Heroku から受け取ったら、OAuth グラントの取得を開始できます。このエンドポイントは App Info API​ にあるため、この API 用のユーザー名とパスワードを取得する必要があります。

GET https://<username>:<password>@api.heroku.com/vendor/resources/:resource_uuid/oauth-grant
Content-Type: application/json

{
  "oauth_grant": {
    "code": "01234567-89ab-cdef-0123-456789abcdef",
    "type": "authorization_code",
    "expires_at": "2016-03-03T18:01:31-0800"
  }
}

以前に発行された OAuth グラントコードの有効期限がまだ切れていない場合、このエンドポイントは既存の OAuth グラントをべき等に返します。コードがすでに有効期限切れの場合、エンドポイントにより新しいコードが生成されます。以前にグラントコードをアクセストークンおよび更新トークンに交換したことがある場合、このエンドポイントはエラーになります。​この交換によって入手した更新トークンを紛失した場合は、お問い合わせください。

応答内の OAuth グラントコードは 5 分以内に期限が切れます。すでに説明したフローに従って、アクセストークンと更新トークンにグラントコードを交換​する必要があります。

アクセストークンを使用した API へのアクセス

アクセストークンを使用して API にアクセスするには、他の OAuth トークンを Platform API で使用するときと同じように、Authorization​ ヘッダーでトークンを API に渡します。たとえば、アドオンの詳細を取得するには、次のようにします。

GET /addons/01234567-89ab-cdef-0123-456789abcdef
Host: api.heroku.com:443
Content-Type: application/json
Accept: application/vnd.heroku+json; version=3
Authorization: Bearer 4594b794-0c94-416b-a374-bb33a025411f

トークンの更新

アクセストークンは最大 8 時間有効ですが、資格情報のローテーションなど、特定の状況によって期限切れが早まる場合があります。更新トークンはアドオンが存続する限り有効であり、必要に応じて何度でも、有効な OAuth クライアントシークレットを使用して新しいアクセストークンと交換できます。

新しいアクセストークンを取得するには、Heroku 認証サービス (id.heroku.com) で同じエンドポイントをもう一度使用します。今回渡す grant_type は “refresh_​token” になります。

$ curl -X POST https://id.heroku.com/oauth/token \
-d "grant_type=refresh_token&refresh_token=95a242fe-4c4a-4059-bc06-512de9672619&client_secret=f6a36ee4-3736-455e-9787-bb91ca679706"

これにより、新しいアクセストークンを含むペイロードが返されます (一部のフィールドを省略しています)。

{
  "access_token": "2af695e0-93e3-4821-ac2e-95f68435f128",
  "refresh_token": "95a242fe-4c4a-4059-bc06-512de9672619",
  "expires_in": 2592000,
  "token_type": "Bearer"
}

前述したように、access_token​、refresh_token​、client_secret​ の値を永続ストレージに書き込むときは、常に暗号化してください。

Platform API を使用した環境設定

新しい統合には、既存の Add-on Partner App Info API​ ではなく Platform API を使用して環境設定を更新する機能が含まれています。これを実行するには、まず、プロビジョニングリクエストに含まれるアドオンリソースの UUID と、そのアドオンリソースのアクセストークンを用意します。

このアドオンリソースの既存の設定は、エンドポイントの GET フォームを使用して表示できます。

GET /addons/01234567-89ab-cdef-0123-456789abcdef/config
Host: api.heroku.com:443
Content-Type: application/json
Accept: application/vnd.heroku+json; version=3
Authorization: Bearer 2af695e0-93e3-4821-ac2e-95f68435f128

また、PATCH フォームを使用して更新できます。

PATCH /addons/01234567-89ab-cdef-0123-456789abcdef/config
Host: api.heroku.com:443
Content-Type: application/json
Accept: application/vnd.heroku+json; version=3
Authorization: Bearer 2af695e0-93e3-4821-ac2e-95f68435f128

{
  "config": [
    {
      "name": "MY_ADDON",
      "value": "bar"
    }
  ]
}

詳細は、Platform API の「Add-on Config Update​」(アドオン設定の更新) ドキュメントを参照してください。

Platform API を使用したアプリの詳細へのアクセス

Platform API では、アドオンリソースにアタッチされたアプリに関する情報をリクエストできます。通常は、アプリの UUID または名前のどちらかを渡すと、エンドポイントからアプリが返されます。アタッチされたアプリを取得するには、まず /addons/:resource_uuid​ または /addons/:resource_uuid/addon-attachments​ をリクエストする必要があります。前者ではプライマリアプリが app​ オブジェクトで返され、後者ではすべてのアタッチされたアプリがアタッチメントのリストで返されます。

アプリの情報を使用するにあたり、Platform API へのリクエストには UUID を優先的に使用し、ユーザーにはアプリの名前を表示してください。リクエストはアプリの名前でも実行できます。

たとえば、所有するアドオンリソースに対して /addons/:resource_uuid​ エンドポイントをリクエストし、次が返されたとします (一部のフィールドを省略しています): json { "app": { "id": "01234567-89ab-cdef-0123-456789abcdef", "name": "example" }, ... }

アドオンリソースが作成されたアプリの ID が 01234567-89ab-cdef-0123-456789abcdef​ であることがわかります。この UUID を使用して、アプリに関する情報を他のエンドポイントからリクエストできます。たとえば、アプリドメイン​またはアプリ共同作業者​のエンドポイントでこのアプリ UUID を使用できます。

ログドレイン

アドオンでアプリのログドレインの設定機能にアクセスできる場合、アドオンは Platform API でログドレインのエンドポイントにアクセスできます。これらのエンドポイントはすべて、アドオンリソースの UUID を識別子として受け取ります。詳細は、ログドレインのエンドポイント​に関するドキュメントを参照してください。

標準の Platform API エンドポイントのリスト

以下のエンドポイントには、Platform API と統合されたすべてのアドオンからアクセスできます。

アドオンから見えるのは、これらのエンドポイントからの同じアドオンサービスのインスタンスだけになります。アドオンから見えるのは、これらのエンドポイントからアドオンがアタッチされたアプリのインスタンスだけになります。

アドオンリソース

アドオンアタッチメント

アドオン設定

アプリ情報

アプリ共同作業者

ドメイン

ログドレイン

パイプライン

チームメンバー

その他

ユースケースにおいて正当な理由がある場合、Heroku では上記以外のエンドポイントをパートナーごとに有効化できます。アプリのフォーメーション​、リリース​、またはビルド​を確認したい場合などが該当します。皆様が実現しようとしていることに関してご意見をお聞かせください。

ベストプラクティス

可能であればジャストインタイムでデータを取得し、保存するのはアドオンリソースの UUID、自分自身の ID、アドオンのアクセストークンと更新トークンの組み合わせだけにしてください。所有者のメールアドレスやアプリ名を含め、Heroku 上の多くのフィールドは変更の可能性があるため、必要になる直前に取得することをお勧めします。

Heroku アドオンリソースおよび Heroku アプリの識別子としては UUID のみを使用してください。(紛らわしい “app123@heroku.com” 識別子のような) 以前の識別子は一切 Platform API では使用しないでください。

よくある質問

アクセストークンの期限が切れそうで Heroku API がダウンしている場合、どうすればよいですか?

アドオンパートナーに付与される更新トークンは長期間有効です。アクセストークンの有効期限が切れた場合でも使用できます。Heroku API が復旧したら、更新トークンを新しいアクセストークンと交換してください。

アクセストークンが公開されてしまった場合はどうすればよいですか?

OAuth クライアントシークレットが公開されておらず、Heroku API への接続が侵害されていない場合は、更新トークンを使用して新しいアクセストークンを取得してください。これにより、古いアクセストークンは期限切れになります。

OAuth クライアントシークレットが侵害された場合は、次の質問を参照してください。

OAuth 更新トークンが侵害された場合は、お問い合わせください​。

OAuth クライアントシークレットが公開されてしまった場合はどうすればよいですか?

資格情報のローテーションをすぐに実行してください。

資格情報のローテーションを実行するにはどうすればよいですか?

ご自身の Heroku アカウントを使用してアドオンパートナーポータルにログインし、「OAuth Credentials」 (OAuth 資格情報) をクリックしてから Reset​ (リセット) ボタンを押します。

新しい OAuth クライアントシークレットが一時的に画面に表示されます。既存のすべてのアクセストークンはただちに無効になり、新しい OAuth クライアントシークレットを使用して更新する必要があります。

攻撃者が資格情報をリセットして新しい資格情報を取得するのを防ぐために、必ず、すべてのアドオン管理者の Heroku アカウントで 2 要素認証を有効にしてください。

アクセス可能な API エンドポイントはどのようにして確認できますか?

今のところ、これを動的に表示する方法はありません。アドオンの権限不足でエンドポイントにアクセスできない場合、承認エラーが返されます。

すべてのアドオンがアクセスできるエンドポイントの共通基本セットは、今後拡張される可能性があります。アドオンで特定のニーズがある場合は、Heroku のパートナーチームとエンジニアの協力のもと、アドオンの権限と API アクセスの拡張についてケースバイケースで許可を得ることができます。

Platform API の使用時に速度制限はどのように機能しますか?

リソースがスコープのトークンを使用してアクセスしたときに、リソースごとの独自の速度制限が発動します。したがって、1 つのリソースに呼び出しが集中しても、アドオンが所有する他のリソースの API 呼び出しの実行能力は影響を受けません。どの応答でも、RateLimit-Remaining​ 応答ヘッダーを使用すれば現在のトークン数を確認できます。Platform API の速度制限​のカウントおよびドキュメントの内容が適用されます。

使用方法についてもっと具体的な説明が欲しい