パートナー向け Platform API への移行

最終更新日 2022年10月03日(月)

Get All Apps エンドポイント要求
Get App Info エンドポイントの置き換え
Update Config Vars (環境設定の更新) エンドポイントの置き換え

アドオンで従来の Add-on Partner App Info API が使用されている場合、このガイドに従って、従来の API へのすべての呼び出しを、Platform API for Partners への呼び出しに置き換えます。2023 年 7 月 3 日で従来の API のサポートが終了します。非推奨タイムラインに変更がある場合は、この記事を更新し、それに応じて Heroku Changelog を通じて告知されます。Add-on Partner App Info API のサポート終了についての詳細は、FAQ 記事を参照してください。

従来の App Info API への呼び出しを、現在の Platform API への呼び出しに置き換える前に、アドオンで Add-on Partner API V3 が実装されている必要があります。2018 年 5 月より前にアドオンを構築し、以前移行していない場合、ご使用のアドオン統合では従来の Add-on Partner API V1 がまだ使用されています。ここに記載されているエンドポイントの置換を試行する前に、このガイドに従って、ご使用のアドオンを現在の統合 API に移行する必要があります。

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

従来の App Info API では、アドオンプロバイダーが関心を寄せる 3 つのエンドポイントが提供されています。

Get All Apps (すべてのアプリの取得)
Get App Info.(アプリ情報の取得)
Update Config Vars (環境設定の更新)

Get All Apps エンドポイント要求

従来の Get All Apps エンドポイントでは、アドオンをインストールしているアプリの一覧を取得できます。

置換される従来の Get All Apps 要求の例

$ 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"
  }
]

パートナー向け Platform API は、アドオンがインストールされているアプリケーションのリストを取得できるエンドポイントを提供できません。これは、認証がトークンベースで、トークンは、許可された特定のリソースにスコープが指定されているためです。この制限を克服するために、この目的で使用できる Add-ons API v3 に新しい Apps エンドポイントを追加しました。

Add-ons API v3 は、パートナーポータル内での企業ユーザーのやり取りを強化するだけでなく、アドオンプロバイダーがプログラムでその情報にアクセスして更新することを可能にするパブリック API です。

Apps エンドポイントを使用するために、いずれかの登録済み企業ユーザーに属している認証トークンを使用して、Add-ons API v3 に認証する必要があります。Heroku ユーザーは、ダッシュボード (ユーザーメニュー → Account Settings (アカウント設定) → Applications (アプリケーション) → Authorizations (許可)) または Heroku CLI ツールを使用して、一時的または永続的な認証を生成できます。

永続的な認証の作成の例

$ heroku authorizations:create -d "Add-ons API v3 access token"
Creating OAuth Authorization... done
Client:      <none>
ID:          e844f998-4852-4176-bd35-9d5b74e18f46
Description: Add-ons API v3 access token
Scope:       global
Token:       0b6cbe5f-9d1e-4277-b842-dd1361b60909

Add-ons API v3 に要求するときは、生成されたアクセストークンを Bearer トークンとして Authorization ヘッダーで使用します。

Add-ons API V3 への Apps 要求の例

$ curl https://addons.heroku.com/api/v3/addons/logcapture-staging/apps \
-H "Authorization: Bearer 0b6cbe5f-9d1e-4277-b842-dd1361b60909" \
-H "Accept: application/json"

[
  {
    "callback_url": "https://api.heroku.com/addons/fc045862-3954-4869-80d3-0a69063f995f",
    "id": "95c71f9b-9068-4829-b3b3-6e0472db7a04",
    "name": "test-app-1",
    "resource": {
      "uuid": "fc045862-3954-4869-80d3-0a69063f995f",
      "name": "logcapture-staging-silhouetted-45667"
    },
    "plan": "test",
    "provider_id": "fc045862-3954-4869-80d3-0a69063f995f"
  },
  {
    "callback_url": "https://api.heroku.com/addons/e5d0dc92-0e7d-4720-af67-0ec40198421f",
    "id": "72657576-cfa5-4130-9d99-92e440549168",
    "name": "test-app-2",
    "resource": {
      "uuid": "e5d0dc92-0e7d-4720-af67-0ec40198421f",
      "name": "logcapture-staging-concave-99081"
    },
    "plan": "test",
    "provider_id": "provider_id_67890"
  }
]

従来の API と Add-ons API V3 からの応答では同じパターンが使用されていますが、考慮すべきいくつかの根本的な違いがあります。

heroku_id は従来のアプリ識別子で、現在は非推奨となり廃止され、現在の id が使用されています。新しい識別子は、次のセクションで説明するような詳細なアプリ情報を取得するために使用できます。
callback_url は互換性のために保持されていますが、URI は従来の API ではなく、Platform API の Add-on Info エンドポイントを指しています。これは、初期のプロビジョニング要求で送信されたのと同じ値です。
provider_id は、アドオンプロバイダーの参照として保持されていますが、Add-on Partner API 統合エンドポイントに行われる要求の識別子として使用されません。これは、初期プロビジョニング要求の応答で設定した id 属性に関連付けられた値です。

結果のページ分割

4000 より大きい結果はページ分割されます。ページ分割の情報は、Link HTTP ヘッダー経由で渡されます。ページ分割をクライアントコードで構成するのではなく、これらの URI を使用して移動します。

ページ分割ヘッダーの例

Link: <https://addons.heroku.com/api/v3/addons/logcapture-staging/apps?offset=0>; rel="prev", <https://addons.heroku.com/api/v3/addons/logcapture-staging/apps?offset=8000>; rel="next"

そのヘッダー内の指定できる rel 値は次のとおりです。

next: 結果の直後のページの URL を示します。
prev: 結果の直前のページの URL を示します。

Get App Info エンドポイントの置き換え

アドオンサービス実装で、従来の Add-on Partner App Info API を使用して、Get App Info エンドポイントによってアプリに関する詳細な情報を取得する場合、これらの呼び出しを、Platform API からの App Info エンドポイントへの要求で置き換えます。

置換される従来の Get App Info 要求の例

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

{
  "callback_url": "https://api.heroku.com/vendor/apps/fc045862-3954-4869-80d3-0a69063f995f",
  "config": {
    "LOGCAPTURE_STAGING_API_KEY": "BiB5GNfw+g3P0IUR8bJr1fKY",
    "LOGCAPTURE_STAGING_URL": "https://logcapture-staging.herokuapp.com/kR2Qvn8gELmdZwZU"
  },
  "domains": [
    "test-app-1.herokuapp.com"
  ],
  "id": "app888888888@heroku.com",
  "name": "test-app-1",
  "owner_email": "developer@logcapture.com",
  "owner": {
    "uuid": "a3bcc594-cd28-4517-ac3a-ab23aa9b6841",
    "email": "developer@logcapture.com"
  },
  "region": "amazon-web-services::us-east-1",
  "resource": {
    "uuid": "fc045862-3954-4869-80d3-0a69063f995f",
    "name": "logcapture-staging-silhouetted-45667"
  },
  "plan": "test",
  "logplex_token": "t.61ebeb54-deba-438e-90a6-16ce6784c338"
}

従来の App Info エンドポイントを、Platform API からの App Info エンドポイントで置き換えた場合、情報を取得する特定のエンドポイントがあるため、リソースや環境変数などの関連するエンティティが JSON 応答に含まれなくなります。パートナー向け Platform API の記事で、使用可能なエンドポイントの一覧を確認できます。

Platform API からのアプリ情報要求の例

$ curl https://api.heroku.com/apps/95c71f9b-9068-4829-b3b3-6e0472db7a04 \
-H "Authorization: Bearer 9ebed010-233d-4de3-9f2f-fdfeddddd9c7" \
-H "Accept: application/vnd.heroku+json; version=3"

[
  {
    "acm": false,
    "archived_at": null,
    "buildpack_provided_description": null,
    "build_stack": {
      "id": "3bcd644c-3108-4c40-8969-2aa29947d1c6",
      "name": "heroku-18"
    },
    "created_at": "2020-06-11T17:23:00Z",
    "id": "95c71f9b-9068-4829-b3b3-6e0472db7a04",
    "git_url": "https://git.heroku.com/test-app-1.git",
    "maintenance": false,
    "name": "test-app-1",
    "owner": {
      "uuid": "a3bcc594-cd28-4517-ac3a-ab23aa9b6841",
      "email": "developer@logcapture.com"
    },
    "region": {
      "id": "8271a929-df76-4021-855f-feb83fee000e",
      "name": "us"
    },
    "organization": null,
    "team": null,
    "space": null,
    "internal_routing": null,
    "released_at": "2020-11-10T20:53:00Z",
    "repo_size": null,
    "slug_size": null,
    "stack": {
      "id": "3bcd644c-3108-4c40-8969-2aa29947d1c6",
      "name": "heroku-18"
    },
    "updated_at": "2021-09-07T06:11:28Z",
    "web_url": "https://test-app-1.herokuapp.com/"
  }
]

Update Config Vars (環境設定の更新) エンドポイントの置き換え

従来の Add-on Partner App Info API からの Update Config Vars エンドポイントは、アドオンサービスによって制御されている環境変数の値を設定または削除できます。そのエンドポイントに送信される要求は、パートナー向け Platform API から Add-on Config Update エンドポイントへの呼び出しによって置き換える必要があります。

置換される従来の Update Config Vars 要求の例

$ curl -X PUT https://logcapture-staging:6349E6585913eD9a1@api.heroku.com/vendor/apps/95c71f9b-9068-4829-b3b3-6e0472db7a04 \
-H 'Content-Type: application/json'
-d '{"config":{"LOGCAPTURE_STAGING_URL":"https://logcapture-staging.herokuapp.com/Hgp35ph6YLeaGnPz"}}'

古いエンドポイント用の JSON ペイロードは、単一の config キーを含むオブジェクトとオブジェクト値で構成されており、キーは更新する環境変数の名前で、値には割り当て対象のリテラル値が含まれています。新しいエンドポイントでは、JSON ペイロードは単一の config キーを持つオブジェクトで同様に構成されています。ただし、その値はオブジェクトの配列で、そのそれぞれが、更新する単一の環境変数を示し、name と value の 2 つのキーが含まれています。これらの値は、更新する環境変数の名前と、それぞれ設定される新しい値です。

Add-on Config Update 要求の例

$ curl -X PATCH https://api.heroku.com/addons/fc045862-3954-4869-80d3-0a69063f995f/config \
-H "Authorization: Bearer 9ebed010-233d-4de3-9f2f-fdfeddddd9c7" \
-H "Content-Type: application/json"
-H "Accept: application/vnd.heroku+json; version=3"
-d '{"config":[{"name":"LOGCAPTURE_STAGING_URL","value":"https://logcapture-staging.herokuapp.com/Hgp35ph6YLeaGnPz"}]}'

[
  {
    "name": "API_KEY",
    "value": "BiB5GNfw+g3P0IUR8bJr1fKY",
  },
  {
    "name": "URL",
    "value": "https://logcapture-staging.herokuapp.com/Hgp35ph6YLeaGnPz"
  }
]

Categories