アドオンパートナー API リファレンス
最終更新日 2022年10月03日(月)
Table of Contents
概要
アドオンパートナー API により、Heroku とアドオンパートナーの間のアドオンリソースのプロビジョニング、設定、更新、プロビジョニング解除が容易になります。あるケースでは、リクエストが Heroku からアドオンパートナーに送信され、別のケースでは、リクエストがアドオンパートナーから発信されて Heroku に送信されます。Heroku を初めて使うか、または統合をさらに進めることに関心がある場合は、「パートナー向け Platform API」を参照してください。これは、ガイド付き導入を提供し、追加のエンドポイントに関する情報を含んでいます。
この記事では、アドオンパートナー API の v3 (現在のバージョン) について説明します。2018 年 5 月以降にアドオンをビルドした場合、アドオンでは v3 を使用している可能性があります。従来のアドオンパートナー API v1 は非推奨であり、2023 年 7 月 3 日のサポート終了 (EOL) が予定されています。v1 のサポート終了についての詳細は、FAQ の記事を参照してください。
認証と 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
プロパティが使用できない場合は、一般的なエラーメッセージが表示されます。
一般的なタイプのエラーの場合は、API で、エラーのタイプを識別する短いキーワードを含む id
プロパティをエラーペイロードに追加することをお勧めします。例については、Heroku がそれをどのように行っているかを「Platform API リファレンス」で確認してください。将来的には、このような識別子が分析のためのメトリクスやツールでパートナーに公開される可能性があります。
失敗したプロビジョニングやプロビジョニング解除などの試行は、パートナーポータルで表示できます。この一覧は顧客で発生している問題への可視性を提供するため、これを監視することをお勧めします。
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」(非同期プロビジョニングの概要) を参照してください。
パラメータ
名前 | 型 | 説明 | 例 |
---|---|---|---|
callback_url | 文字列 | アドオンと、それを所有するアプリに関する更新された情報を取得するために使用される URL | https://api.heroku.com/addons/01234567-89ab-cdef-0123-456789abcdef |
name | 文字列 | プロビジョニングされるリソースの論理名 | acme-inc-primary-database |
oauth_grant | null 許容オブジェクト | OAuth オブジェクトの詳細 | null |
oauth_grant:code | UUID | Platform API で使用するためにプロビジョニングされるリソースにスコープ指定された access_token に交換できます。 |
01234567-89ab-cdef-0123-456789abcdef |
oauth_grant:expires_at | 日時 | 許可が期限切れになる時刻 (この時刻までにコードを交換している必要がある) デフォルト値は今から 5 分後 |
2016-03-03T18:01:31-0800 |
oauth_grant:type | 文字列 | OAuth 許可のタイプ | authorization_code |
options | オブジェクト | heroku addons:create コマンドに渡される追加のコマンドラインオプション |
{ "foo" : "bar", "baz" : "true" } |
plan | 文字列 | プロビジョニングするプランの名前 | basic |
region | 文字列 | アドオンのプロビジョニング先のアプリの地理的なリージョンを指定します。Common Runtime の場合は、amazon-web-services::us-east-1 または amazon-web-services::eu-west-1 のどちらかを指定できます。Private Spaces の場合のリージョン値は次のとおりです。
|
amazon-web-services::us-east-1 |
uuid | 文字列 | Heroku がインストールされているアドオンに使用する一意識別子。これは、Heroku Platform API の id フィールドに対応します。 |
01234567-89ab-cdef-0123-456789abcdef |
オプションパラメータ
名前 | 型 | 説明 | 例 |
---|---|---|---|
log_input_url | 文字列 | ログをアプリのログストリームに送信できるように指定されます。このフィールドは、requires フィールドに log_input を追加することによって、マニフェストで設定されている場合にのみ存在します。詳細は、Logplex 入力について説明している記事を参照してください。 |
https://token:t.01234567-89ab-cdef-0123-456789abcdef@1.us.logplex.io/logs |
log_drain_token | 文字列 | アプリのログをパートナーによって指定された log_drain_url に送信できるように指定されます。このフィールドは、requires フィールドに syslog_drain を追加することによって、マニフェストで設定されている場合にのみ存在します。詳細は、アプリケーションログへのアクセスについて説明している記事を参照してください。 |
d.01234567-89ab-cdef-0123-456789abcdef |
リクエストの例
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"
}
パラメータ
名前 | 型 | 説明 | 例 |
---|---|---|---|
id | 文字列 | 文字列 (UUID など) または整数値を指定できます。これは、リソースをアドレス指定するために使用できる不変の値である必要があります。リクエスト内の uuid フィールドの値を使用することを選択できます。 |
01234567-89ab-cdef-0123-456789abcdef |
オプションパラメータ
名前 | 型 | 説明 | 例 |
---|---|---|---|
message | 文字列 | アドオンを作成した後のユーザーへのさらに詳細な説明 | Your add-on is being provisioned. It will be available shortly. |
log_drain_url | 文字列 | アタッチされたアプリケーションから Logplex ドレイン形式のログを受信できる URL | https://1.1.1.1 |
応答の例
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
パラメータを、選択した他のオプションパラメータと共に含める必要があります。
名前 | 型 | 説明 | 例 |
---|---|---|---|
config | オブジェクト | このアドオンリソースを使用するすべてのアプリケーションで環境変数として設定される環境設定。送信するすべての環境変数に同じプレフィックス (大文字にしたアドオンの名前) を付ける必要があります。ただし、Heroku アプリのコンテキスト内では、さまざまな理由によりプレフィックスが異なることがあります。たとえば、アドオンが fast-db という名前であり、FAST_DB_URL を設定している場合、アプリケーションでの変数名はデフォルトで FAST_DB_URL になりますが、ユーザーがそのアドオンをプレフィックス PRIMARY_DB で追加した場合は PRIMARY_DB_URL になります。 |
{ "MYADDON_URL": "http://myaddon.com/52e82f5d73" } |
応答の例
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
を手元に保存します。
永続的なストレージに書き込む場合は、access_token
と refresh_token
の値や client_secret
を必ず暗号化してください。これらの秘密鍵を保存時にプレーンテキストにしたり、それらの復号化キーを簡単に見つけやすくしたりするべきではありません。Ruby で Sequel を使用している場合は、attr_vault gem の評価を検討してください。
パラメータ
名前 | 型 | 説明 | 例 |
---|---|---|---|
grant_type | フォームでエンコードされた文字列 | 渡されるコードのタイプを指定します。 | authorization_code |
code | フォームでエンコードされた文字列 | プロビジョニングリクエストで指定された oauth_grant:code 。 |
01234567-89ab-cdef-0123-456789abcdef |
client_secret | フォームでエンコードされた文字列 | ほとんどの OAuth 対話に使用される秘密鍵。client_secret はアドオンパートナーポータルの OAuth Credentials ページで見つけることができ、暗号化して保存する必要があります。 |
01234567-89ab-cdef-0123-456789abcdef |
リクエストの例
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
パラメータ
名前 | 型 | 説明 | 例 |
---|---|---|---|
access_token | 文字列 | 1 つのアドオンリソースにスコープ指定された Platform API にアクセスするために使用されます。通常は、8 時間ごとに期限切れになりますが、特定の状況 (資格情報のローテーションなど) では早く期限切れになることがあります。 | 2af695e0-93e3-4821-ac2e-95f68435f128 |
refresh_token | 文字列 | アドオンの有効期間中は有効であり、有効な OAuth client_secret を使用して、必要に応じて何回でも新しい access_token に交換できます。 |
95a242fe-4c4a-4059-bc06-512de9672619 |
expires_in | 整数 | access_token が有効な秒数。refresh_token は、新しい access_token を取得するために使用されます。 |
28800 |
token_type | 文字列 | トークンのタイプは、Heroku API へのリクエストの Authorization ヘッダーで使用されます。 |
Bearer |
応答の例
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
に交換できます。
パラメータ
名前 | 型 | 説明 | 例 |
---|---|---|---|
grant_type | フォームでエンコードされた文字列 | 渡されるコードのタイプを指定します。 | refresh_token |
refresh_token | フォームでエンコードされた文字列 | 許可コードの交換で指定された refresh_token 。 |
95a242fe-4c4a-4059-bc06-512de9672619 |
client_secret | フォームでエンコードされた文字列 | ほとんどの OAuth 対話に使用される秘密鍵。client_secret はアドオンパートナーポータルの OAuth Credentials ページで見つけることができ、暗号化して保存する必要があります。 |
01234567-89ab-cdef-0123-456789abcdef |
リクエストの例
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
パラメータ
名前 | 型 | 説明 | 例 |
---|---|---|---|
access_token | 文字列 | 1 つのアドオンリソースにスコープ指定された Platform API にアクセスするために使用されます。通常は、8 時間ごとに期限切れになりますが、特定の状況 (資格情報のローテーションなど) では早く期限切れになることがあります。 | 2af695e0-93e3-4821-ac2e-95f68435f128 |
refresh_token | 文字列 | アドオンの有効期間中は有効であり、有効な OAuth client_secret を使用して、必要に応じて何回でも新しい access_token に交換できます。 |
95a242fe-4c4a-4059-bc06-512de9672619 |
expires_in | 整数 | access_token が有効な秒数。refresh_token は、新しい access_token を取得するために使用されます。 |
28800 |
token_type | 文字列 | トークンのタイプは、Heroku API へのリクエストの Authorization ヘッダーで使用されます。 |
Bearer |
応答の例
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 つずつ更新したい場合は、そうすることができます。アドオンが使用可能な場合は、それをプロビジョニング済みとマークする必要があります。それにより、アタッチされたアプリが再起動され、そのアドオンを使用できるようになります。
一部のアドオンでは、アプリケーションで設定されている実際の環境変数がキーとは異なることがあります。送信するすべての環境変数に同じプレフィックス (大文字にしたアドオンの名前) を付ける必要があります。ただし、Heroku アプリのコンテキスト内では、さまざまな理由によりプレフィックスが異なることがあります。
たとえば、アドオンが fast-db
という名前であり、FAST_DB_URL
を設定している場合、アプリケーションでの変数名はデフォルトで FAST_DB_URL
になりますが、ユーザーがそのアドオンをプレフィックス PRIMARY_DB
で追加した場合は PRIMARY_DB_URL
になります。
オプションパラメータ
名前 | 型 | 説明 | 例 |
---|---|---|---|
config | 配列 | [{"name":"FOO","value":"bar"}] |
リクエストの例
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"
}
]
アドオンアクションの作成 - プロビジョニング
アドオンを使用のためにプロビジョニング済みとマークします。
この手順がプロビジョニングリクエストから 12 時間以内に実行されない場合は、プロビジョニングが失敗したと見なされ、そのアドオンは削除されます。
このエンドポイントは、「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 のどちらかを返すことができます。
パラメータ
名前 | 型 | 説明 | 例 |
---|---|---|---|
plan | 文字列 | 変更先のプランの名前 | basic |
リクエストの例
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"
}
オプションパラメータ
名前 | 型 | 説明 | 例 |
---|---|---|---|
message | 文字列 | プランを変更した後のユーザーへのさらに詳細な説明 | Resource has been updated and is available! |
応答の例
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」(アドオンのシングルサインオン) で見つけることができます。
パラメータ
名前 | 型 | 説明 | 例 |
---|---|---|---|
resource_id | フォームでエンコードされた文字列 | プロビジョニングの呼び出しで Heroku によって提供された UUID。 | 01234567-89ab-cdef-0123-456789abcdef |
resource_token | フォームでエンコードされた文字列 | SHA1 でエンコードされた resource_id:salt:timestamp 。サービスへの SSO リクエストを認証するために使用されます。 |
fcafa20c7ac7675276ea92ed04bc929674b711a5 |
timestamp | フォームでエンコードされた文字列 | リクエスト SSO のリクエストが開始された時刻。 | 1267597772 |
nav-data | フォームでエンコードされた文字列 | Heroku レイアウトで現在のアプリの適切なビューを構築できるように、現在のアプリ名やインストールされているアドオンなどの情報が含まれています。 | eyJhZGRvbiI6IllvdXIgQWRkb24iLCJhcHBuYW1lIjoibXlhcHAiLCJhZGRvbnMiOlt7InNsdWciOiJjcm9uIiwibmFtZSI6IkNyb24ifSx7InNsdWciOiJjdXN0b21fZG9tYWlucyt3aWxkY2FyZCIsIm5hbWUiOiJDdXN0b20gRG9tYWlucyArIFdpbGRjYXJkIn0seyJzbHVnIjoieW91cmFkZG9uIiwibmFtZSI6IllvdXIgQWRkb24iLCJjdXJyZW50Ijp0cnVlfV19 |
メール | フォームでエンコードされた文字列 | 認証されたユーザーのメール。 | user@example.com |
オプションパラメータ
名前 | 型 | 説明 | 例 |
---|---|---|---|
foo | フォームでエンコードされた文字列 | SSO URL には、追加のクエリ文字列パラメータを含めることができます。これらのパラメータは、POST 本体でアプリケーションに転送されます。SSO についての詳細は、「What is an Add-on」(アドオンの概要) を参照してください。 |
bar |
リクエストの例
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×tamp=1267597772&nav-data=eyJhZGRvbiI6IllvdXIgQWRkb24iLCJhcHBuYW1lIjoibXlhcHAiLCJhZGRvbnMiOlt7InNsdWciOiJjcm9uIiwibmFtZSI6IkNyb24ifSx7InNsdWciOiJjdXN0b21fZG9tYWlucyt3aWxkY2FyZCIsIm5hbWUiOiJDdXN0b20gRG9tYWlucyArIFdpbGRjYXJkIn0seyJzbHVnIjoieW91cmFkZG9uIiwibmFtZSI6IllvdXIgQWRkb24iLCJjdXJyZW50Ijp0cnVlfV19&email=user%40example.com&foo=bar
応答の例
HTTP/1.1 302 Found
Location: https://addon-slug.herokuapp.com/dashboard