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

概要

アドオンパートナー API により、Heroku とアドオンパートナーの間のアドオンリソースのプロビジョニング、設定、更新、プロビジョニング解除が容易になります。あるケースでは、リクエストが Heroku からアドオンパートナーに送信され、別のケースでは、リクエストがアドオンパートナーから発信されて Heroku に送信されます。Heroku を初めて使うか、または統合をさらに進めることに関心がある場合は、「パートナー向け Platform API​」を参照してください。これは、ガイド付き導入を提供し、追加のエンドポイントに関する情報を含んでいます。

認証と SSL

Heroku からサービスの base_url​ への呼び出しには Authorization​ ヘッダーが含まれ、アドオンマニフェスト​の id​ と api:password​ を使用して検証する必要があります。base_url​ は、有効な SSL 証明書を含む HTTPS URL である必要があります。たとえば、マニフェストに addon-slug​ の id​ と super-secret​ の api:password​ が含まれている場合、サービスへのリクエストにはヘッダー Authorization: Basic YWRkb24tc2x1ZzpzdXBlci1zZWNyZXQ=​ が含まれます。

サービスから Heroku API への呼び出しでは、OAuth access_token​ を使用する必要があります。access_token​ と refresh_token​ は、初期のプロビジョニング​リクエストに含まれている oauth_grant:code​ を交換することによって取得されます。

べき等性

リクエストは複数回送信される可能性があり (Heroku は少なくとも 1 回の配信のパターンに従う)、エンドポイントはべき等的に応答する必要があります。たとえば、リソースの作成の場合、同じパラメータを含む複数の POST では 1 つのリソースだけがプロビジョニングされる必要があります。重複したリクエストのあいまいさをなくすための方法として uuid​ を使用するようにしてください。このような重複が結果に影響を与える場合は、重複した作業から保護するために、Heroku から送信された uuid​ に対してデータベースレベルで一意性制約を有効にすることをお勧めします。以下の各対話の説明では、繰り返されるべき等リクエストの処理に関するより詳細な情報が追加されます。

検証

リクエスト本体には、現在ここに記載されていない追加の要素を含めることができ、このようなリクエストは有効として扱う必要があります。

タイムアウト

サービスは、500 ミリ秒以内に応答するべきです。現在は、20 秒以内に返す必要があり、そうしないとリクエストが失敗します。この上限は、当社の裁量によって時間の経過と共に、および当社の分析に基づいて短縮されます。

バージョン管理

アドオンパートナー API の現在のバージョンはバージョン 3 です。Heroku から​サービスへのリクエストは、Accept​ ヘッダーを使用してバージョン管理されます。v3 リクエストの場合、これは application/vnd.heroku-addons+json; version=3​ に設定されます。アドオンパートナー API の従来のバージョン​では、このヘッダーは設定されません。Platform API で Heroku へのリクエストを作成​する場合は、「Platform API リファレンス​」で指定されている Accept​ ヘッダーを使用するようにしてください。現在、これは application/vnd.heroku+json; version=3​ です。

応答本体

すべての応答本体に有効な JSON を含める必要があります。

例外

API でリクエストを満たすことができない場合、それが無効なリクエスト (存在しないプランなど) のためである場合は 4xx の範囲、または API で予期しないエラーが発生している場合は 5xx の範囲の適切な HTTP ステータスコードで応答するようにしてください。エラー応答本体には有効な JSON を含める必要があります。

プロビジョニングおよびプラン変更リクエストに対する 4xx および 5xx 応答の場合は、JSON 応答の message​ プロパティがユーザーに表示されます。その他のすべての応答の場合、および message​ プロパティが使用できない場合は、一般的なエラーメッセージが表示されます。

Platform API

アドオンリソースがプロビジョニングされたら、Platform API​ を使用してアドオンのインストールに関する情報に対してクエリを実行したり、アドオンの環境設定を更新したりすることができます。

アドオンのプロビジョニング

Heroku からアドオンサービスへのプロビジョニングリクエストです。

アドオンの同期プロビジョニングと非同期プロビジョニングの両方がサポートされています。プロビジョニングプロセスに数秒以上かかる場合は、非同期プロビジョニングを使用するようにしてください。これにより、バックグラウンドでアドオンリソースの設定を完了し、完了したら Heroku に通知することができます。 関連するポリシーの詳細な概要と説明については、「Getting Started with Asynchronous Provisioning​」(非同期プロビジョニングの概要) を参照してください。

プロビジョニングプロセスは、同期シナリオと非同期シナリオでは非常に似ています。後に記載されているように、一連のパラメータを使用してマニフェストに登録されているエンドポイントに POST を送信します。サービスは、各プロビジョニングリクエストで適切な HTTP 応答コードを返すことによって、同期、非同期、または失敗したプロビジョニングのいずれに対して応答するかを決定できます。

Heroku からパートナーに送信されるアドオンプロビジョニングリクエスト POST /heroku/resources​ は、べき等であることが期待されます。つまり、同じリクエストがパートナーに複数回送信される可能性がありますが、uuid​ あたり 1 つのリソースだけが作成されるべきであり、毎回同じ応答が返されるべきです。ただし、そのリソースがプロビジョニング解除されている場合は、もう一度作成されるべきではなく、410 が返されるべきです。パートナーによるデータの削除を容易にするために、プロビジョニングリクエストを再試行できる期間は 24 時間に制限されています。

アドオンサービスでサポートされていない要求されたプランのパラメータのためにプロビジョニングリクエストをサポートできない場合は、422​ ステータスコードを JSON でエンコードされた説明の message​ と共に返します。この message​ は、アドオンが要求されたときのコンテキストで顧客に表示されます。

非同期プロビジョニング

非同期プロビジョニングでは、Heroku からプロビジョニングリクエストを受信した場合、アドオンは次のことを行う必要があります。

• 202 Accepted​ ステータスコードと、顧客に表示される関連する message​ を含む応答を発行します。これにより、Heroku は、ユーザーが必要なリソースをプロビジョニングしている最中であることを認識できます。
• 将来のアドオンリクエスト (アップグレード/ダウングレード、プロビジョニング解除、SSO ダッシュボードへのサインインなど) を適切に満たすことができるように、Heroku のリクエストに含まれているメタデータを保存します。
• 必要なリソースをインフラストラクチャにプロビジョニングします。
• リソースにスコープ指定されたパートナー向け OAuth Platform API アクセスを可能にするために、プロビジョニングリクエストで送信された OAuth 許可トークンを交換​します。
• (オプション) 所有アプリの ENV に含まれる正しいアドオン設定値​で Heroku を更新します。
• アドオンリソースをプロビジョニング済みとマーク​します。リソースを provisioned​ とマークしないと、それはスタックしていると見なされ、約 12 時間後にプロビジョニング解除されます。

一部のアドオン (ログドレインを追加するだけのアドオンなど) はアプリの ENV に設定値が含まれている必要がない場合があり、アドオン設定の更新の手順をスキップできます。

アドオンリソースをプロビジョニング済みとマークすると、そのリソースを所有するアプリのリリース​が削除されます。アドオンリソースをそのようにマークする場合は、そのリソースがすぐに使用できることを確認してください。

請求ポリシーのより高レベルの概要と説明については、「Getting Started with Asynchronous Provisioning​」(非同期プロビジョニングの概要) を参照してください。

パラメータ

オプションパラメータ

リクエストの例

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

{
  "callback_url": "https://api.heroku.com/addons/01234567-89ab-cdef-0123-456789abcdef",
  "name": "acme-inc-primary-database",
  "oauth_grant": {
    "code": "01234567-89ab-cdef-0123-456789abcdef",
    "expires_at": "2016-03-03T18:01:31-0800",
    "type": "authorization_code"
  },
  "options": { "foo" : "bar", "baz" : "true" },
  "plan": "basic",
  "region": "amazon-web-services::us-east-1",
  "uuid": "01234567-89ab-cdef-0123-456789abcdef",
  "log_input_url": "https://token:t.01234567-89ab-cdef-0123-456789abcdef@1.us.logplex.io/logs",
  "log_drain_token": "d.01234567-89ab-cdef-0123-456789abcdef"
}

パラメータ

オプションパラメータ

応答の例

HTTP/1.1 202 Accepted

{
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "message": "Your add-on is being provisioned. It will be available shortly.",
  "log_drain_url": "https://1.1.1.1"
}

同期プロビジョニング

プロビジョニングプロセスがすばやく (たとえば、1 秒未満で) 完了する場合は同期プロビジョニングを使用できます。同期プロビジョニングでは、アドオンリソースを provisioned​ とマークする必要はありませんが、将来的にパートナー向け Platform API​ を使用できるように、引き続き許可コードを交換するようにしてください。

同期プロビジョニングでは、次のことを行う必要があります。

• プロビジョニングプロセスが完了したことを Heroku が認識できるように 200 OK​ ステータスコードで応答します。
• 正しい config​ 値を初期の JSON 応答に直接含めます。
• 上記の内容で応答した後に OAuth トークンを交換します。

次のことは行う必要がありません。

• アドオン環境設定で Heroku を更新する。これらはメインの応答で返します。
• リソースをプロビジョニング済みとマークする。これは 200 OK​ 応答で暗黙的に示されます。

リクエストパラメータ

リクエストは、非同期プロビジョニングの場合と同じです。

応答パラメータ

非同期プロビジョニングで記載されている id​ パラメータに加えて、config​ パラメータを、選択した他のオプションパラメータと共に含める必要があります。

応答の例

HTTP/1.1 200 OK

{
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "message": "Resource has been created and is available!",
  "config": { "MYADDON_URL": "http://myaddon.com/52e82f5d73" }
}

許可コードの交換

アドオンパートナーとして Platform API​ を操作するには、プロビジョニング​リクエストの oauth_grant:code​ を access_token​ と refresh_token​ に交換する必要があります。これらはそれぞれ、リクエストの認証と、新しい access_token​ の取得のために使用されます。access_token​ は、それが作成されたアドオンリソースに関するデータを要求するためにしか使用できないことに注意してください。Platform API でアドオンリソースのデータへのアクセスを取得するには、それぞれの access_token​ を使用する必要があります。応答はすべて、access_token​ が作成されたアドオンリソースにスコープ指定されます。

oauth_grant:code​ が交換されたら、access_token​ と refresh_token​ を手元に保存します。

パラメータ

リクエストの例

POST /oauth/token HTTP/1.1
Host: id.heroku.com:443
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=01234567-89ab-cdef-0123-456789abcdef&client_secret=01234567-89ab-cdef-0123-456789abcdef

パラメータ

応答の例

HTTP/1.1 200 OK

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

アクセストークンの更新

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

パラメータ

リクエストの例

POST /oauth/token HTTP/1.1
Host: id.heroku.com:443
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=95a242fe-4c4a-4059-bc06-512de9672619&client_secret=f6a36ee4-3736-455e-9787-bb91ca679706

パラメータ

応答の例

HTTP/1.1 200 OK

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

アドオン設定の更新

プロビジョニングリクエストのアドオンリソース uuid​ を使用して、アドオンの設定を更新できます。詳細は、Platform API の「アドオン設定の更新​」のドキュメントを参照してください。

アドオン設定は、アプリがアドオンと通信したり、アドオンを利用したりするために必要なデータです。たとえば、データベースの場合は、DATABASE_URL=postgres://user3123:passkja83kd8@ec2-117-21-174-214.compute-1.amazonaws.com:6212/db982398​ などの設定項目が設定されます。この値を設定してもアタッチされたアプリがリリースされることはないため、プロビジョニング中に多くの設定を 1 つずつ更新したい場合は、そうすることができます。アドオンが使用可能な場合は、それをプロビジョニング済みとマークする​必要があります。それにより、アタッチされたアプリが再起動され、そのアドオンを使用できるようになります。

オプションパラメータ

リクエストの例

PATCH /addons/01234567-89ab-cdef-0123-456789abcdef/config HTTP/1.1
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"
    }
  ]
}

応答の例

HTTP/1.1 200 OK
Accept-Ranges: name
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 2400

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

アドオンアクションの作成 - プロビジョニング

アドオンを使用のためにプロビジョニング済みとマークします。

このエンドポイントは、「Platform API リファレンス​」にも記載されています。 プロビジョニングリクエスト中に返されたリソース UUID を ID として使用するようにしてください。

リクエストの例

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

応答の例

HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 2400

{
  "actions": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "label": "Example",
    "action": "example",
    "url": "http://example.com?resource_id=:resource_id",
    "requires_owner": true
  },
  "addon_service": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "heroku-postgresql"
  },
  "app": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "config_vars": [
    "FOO",
    "BAZ"
  ],
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "acme-inc-primary-database",
  "plan": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "heroku-postgresql:dev"
  },
  "provider_id": "abcd1234",
  "state": "provisioned",
  "updated_at": "2012-01-01T12:00:00Z",
  "web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef"
}

アドオンプランの変更

ユーザーがインストールされているアドオンのプラン変更を要求すると、Heroku は API に PUT​ リクエストを送信します。

プラン変更をサポートできない場合は、「例外」で説明されているように​、ステータスコード 422​ または 503​ で応答し、ユーザーに表示するメッセージを返します。たとえば、ユーザーの現在のプランと要求されたプランの間で変更を行うことができない場合は、説明の message​ を含む 422​ ステータスコードが適切です。ただし、プラン変更が内部の原因で失敗し、ユーザーが後で再試行する必要がある場合は、503​ の方がより適切であることがあります。

リクエスト URI (:resource_uuid​) 内の UUID は、操作するアドオンを識別するために使用する必要があります。これは、プロビジョニングリクエスト本体で Heroku によって提供されたものと同じ UUID です。

Heroku からパートナーに送信されるプラン変更リクエスト PUT /heroku/resources/:resource_uuid​ は、べき等であることが期待されます。つまり、同じリクエストがパートナーに複数回送信される可能性がありますが、毎回同じ応答が返されるべきです。ただし、そのリソースがプロビジョニング解除されている場合は、もう一度更新されるべきではなく、410 が返されるべきです。パートナーによるデータの削除を容易にするために、変更リクエストを再試行できる期間は 24 時間に制限されています。この期間が経過したら、404 または 410 のどちらかを返すことができます。

パラメータ

リクエストの例

PUT /heroku/resources/:resource_uuid HTTP/1.1
Host: addon-slug.herokuapp.com:443
Authorization: Basic YWRkb24tc2x1ZzpzdXBlci1zZWNyZXQ=
Content-Type: application/json
Accept: application/vnd.heroku-addons+json; version=3

{
  "plan": "basic"
}

オプションパラメータ

応答の例

HTTP/1.1 200 OK

{
  "message": "Resource has been updated and is available!"
}

アドオンのプロビジョニング解除

アドオンがユーザーのアカウントから削除されたら、Heroku は API への DELETE​ リクエストを作成します。 リクエスト URI (:resource_uuid​) 内の UUID は、操作するアドオンを識別するために使用する必要があります。これは、プロビジョニングリクエスト本体で Heroku によって提供されたものと同じ UUID です。

プロビジョニング解除リクエストは、複数回送信される可能性があります。以降のリクエストには、2xx または 410 で応答する必要があります。パートナーによるデータの削除を容易にするために、プロビジョニング解除リクエストを再試行できる期間は 24 時間に制限されています。この期間が経過したら、404 または 410 のどちらかを返すことができます。

リクエストの例

DELETE /heroku/resources/:resource_uuid HTTP/1.1
Host: addon-slug.herokuapp.com:443
Authorization: Basic YWRkb24tc2x1ZzpzdXBlci1zZWNyZXQ=
Content-Type: application/json
Accept: application/vnd.heroku-addons+json; version=3

応答の例

HTTP/1.1 204 No Content

アドオンの情報

パートナー向け Platform API​ を使用すると、サービスによって所有されているアドオンに関する情報を要求できます。 パートナー向け Platform API​ を使用して、アプリ、共同作業者、リージョン、ドメイン、パイプラインなどの情報も要求できます。

リクエストの例

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

応答の例

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 2400

{
  "actions": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "label": "Example",
    "action": "example",
    "url": "http://example.com?resource_id=:resource_id",
    "requires_owner": true
  },
  "addon_service": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "heroku-postgresql"
  },
  "app": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "config_vars": [
    "FOO",
    "BAZ"
  ],
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "acme-inc-primary-database",
  "plan": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "heroku-postgresql:dev"
  },
  "provider_id": "abcd1234",
  "state": "provisioned",
  "updated_at": "2012-01-01T12:00:00Z",
  "web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef"
}

アドオンのシングルサインオン

アドオンのユーザーは、サービスを使用して作成したリソースのパーソナライズされたダッシュボードにシームレスにサインインできます。ナビゲーションバーの統合を含むより詳細な情報は、「Add-on Single Sign-on​」(アドオンのシングルサインオン) で見つけることができます。

パラメータ

オプションパラメータ

リクエストの例

POST /heroku/sso HTTP/1.1
Host: addon-slug.herokuapp.com:443
Content-Type: application/x-www-form-urlencoded

resource_id=01234567-89ab-cdef-0123-456789abcdef&resource_token=fcafa20c7ac7675276ea92ed04bc929674b711a5&timestamp=1267597772&nav-data=eyJhZGRvbiI6IllvdXIgQWRkb24iLCJhcHBuYW1lIjoibXlhcHAiLCJhZGRvbnMiOlt7InNsdWciOiJjcm9uIiwibmFtZSI6IkNyb24ifSx7InNsdWciOiJjdXN0b21fZG9tYWlucyt3aWxkY2FyZCIsIm5hbWUiOiJDdXN0b20gRG9tYWlucyArIFdpbGRjYXJkIn0seyJzbHVnIjoieW91cmFkZG9uIiwibmFtZSI6IllvdXIgQWRkb24iLCJjdXJyZW50Ijp0cnVlfV19&email=user%40example.com&foo=bar

応答の例

HTTP/1.1 302 Found
Location: https://addon-slug.herokuapp.com/dashboard