"[レガシー] Add-on Partner API リファレンス"

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

概要

Add-on Partner API は、Heroku がアドオンサービスを呼び出すときに使用されます。これらの例では、Heroku がリクエストを発行し、アドオンが応答を提供します。

この記事では、Add-on Partner API の v1 について説明します。アドオンが 2018 年 4 月より前に作成された場合は、これが必要とするドキュメントである可能性が最も高くなります。 アドオンで使用している API のバージョンは、パートナーポータル​の 「Settings」 (設定) -> 「Provisioning API」 (プロビジョニング API) で確認できます。V3 統合では、現在の Add-on Partner API リファレンス​を使用する必要があります。

一般的なガイドライン

アドオンサービスは、このドキュメントに一覧表示されているすべての呼び出しを実装する必要があります。処理できないリクエストでは、ユーザーへの情報量の多いメッセージを含む 422 応答を返す​べきです。

認証

アドオンマニフェスト​で指定されているアドオン id​ (多くの場合は、アドオン識別子または slug と呼ばれる) と password​ を使用して、すべての呼び出しを HTTP 基本認証で保護するべきです。

べき等性

リクエストは複数回送信される可能性があり (Heroku は少なくとも 1 回の配信のパターンに従う)、エンドポイントはべき等的に応答する必要があります。たとえば、リソースの作成の場合、同じパラメータを含む複数の POST では 1 つのリソースだけがプロビジョニングされる必要があります。

検証

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

タイムアウト

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

応答するためにさらに長い時間が必要な場合は、非同期パートナー API​ を使用します。古い代替手段は、プロビジョニングが実行されることを示す受信確認として 202 Accepted​ を返し、準備ができたら Platform API​ を使用して必要なすべての環境設定を設定することでした。ただし、この代替手段は非推奨であり、将来は、すべての 202 応答で非同期プロセスがトリガーされます。

バージョン管理

この API の現在のバージョンはバージョン 3​ です。このドキュメントでは、従来のバージョンについて説明します。

応答本体

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

例外

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

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

一般的なタイプのエラーの場合は、API で、エラーのタイプを識別する短いキーワードを含む id​ プロパティをエラーペイロードに追加することをお勧めします。例については、Heroku がそれをどのように行っているかを「Platform API リファレンス​」で確認してください。将来的には、このような識別子が分析のためのメトリクスやツールでパートナーに公開される可能性があります。 失敗したプロビジョニングやプロビジョニング解除などの試行は、パートナーポータル​で表示できます。この一覧は顧客で発生している問題への可視性を提供するため、これを監視することをお勧めします。

Platform API

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

プロビジョニング

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

パラメータ

名前 型 説明 例
callback_url​ 文字列​ アドオンと、それを所有するアプリに関する更新された情報を取得するために使用される URL https://api.heroku.com/vendor/apps/app1234@heroku.com​
heroku_id​ 文字列​ プロビジョニングされるアドオンを所有するアプリケーション​の識別子。これにより、アドオン自体が一意に識別されるわけではありません。 app1234@heroku.com​
oauth_grant​ null 許容オブジェクト​ OAuth オブジェクトの詳細 null​
oauth_grant:code​ uuid​ Platform API​ で使用するためにプロビジョニングされるリソースにスコープ指定された access_token に交換できます。 01234567-89ab-cdef-0123-456789abcdef​
oauth_grant:expires_at​ 日時​ 許可が期限切れになる時刻 (この時刻までにトークンに交換している必要がある) 2016-03-03T18:01:31-0800​
oauth_grant:type​ 文字列​ OAuth 許可のタイプ authorization_code​
options​ オブジェクト​ heroku addons:create​ コマンドに渡される追加のコマンドラインオプション​ { "foo" : "bar", "baz" : "true" }​
plan​ 文字列​ プロビジョニングするプランの名前 basic​
region​ 文字列​ アドオンのプロビジョニング先のアプリの地理的なリージョンを指定します。現時点では、amazon-web-services::us-east-1​ または amazon-web-services::eu-west-1​ のどちらかを指定できます。これを使用してアプリに地理的に近い場所でリソースをプロビジョニングするか、これを無視するか (アドオンのレイテンシー感度が高くない場合)、または指定されたリージョン内のアプリをアドオンがサポートしていない場合はエラーで応答します。 amazon-web-services::us-east-1​

オプションパラメータ

名前 型 説明 例
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
Authorization: Basic YWRkb24tc2x1ZzpzdXBlci1zZWNyZXQ=
Content-Type: application/json
Accept: application/json

{
  "callback_url": "https://api.heroku.com/vendor/apps/app1234@heroku.com",
  "heroku_id": "app1234@heroku.com",
  "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",
  "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 など) または整数値を指定できます。これは、リソースをアドレス指定するために使用できる不変の値である必要があります。 01234567-89ab-cdef-0123-456789abcdef​

オプションパラメータ

名前 型 説明 例
message​ 文字列​ アドオンを作成した後のユーザーへのさらに詳細な説明 Resource has been created and is available!​
config​ オブジェクト​ このアドオンを使用するすべてのアプリケーションで設定される環境変数。送信するすべての環境変数に同じプレフィックス (大文字にしたアドオンの名前) を付ける必要があります。ただし、Heroku アプリのコンテキスト内では、さまざまな理由によりプレフィックスが異なることがあります。たとえば、アドオンが fast-db​ という名前であり、FAST_DB_URL​ を設定している場合、アプリケーションでの変数名はデフォルトで FAST_DB_URL​ になりますが、ユーザーがそのアドオンをプレフィックス PRIMARY_DB​ で追加した場合は PRIMARY_DB_URL​ になります。 { "MYADDON_URL": "http://myaddon.com/52e82f5d73" }​

応答の例

HTTP/1.1 202 Accepted

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

プラン変更

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

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

パラメータ

名前 型 説明 例
heroku_id​ 文字列​ heroku_id​ フィールドには、アドオンを所有するアプリケーションの識別子が含まれています。heroku_id​ は一意であることが保証されないため、操作するアドオンを識別するには、リクエスト URI 内の ID (:provider_id​) を使用する必要があります。 app1234@heroku.com​
plan​ 文字列​ 変更先のプランの名前 basic​

リクエストの例

PUT /heroku/resources/:provider_id HTTP/1.1
Host: addon-slug.herokuapp.com
Authorization: Basic YWRkb24tc2x1ZzpzdXBlci1zZWNyZXQ=
Content-Type: application/json
Accept: application/json

{
  "heroku_id": "app1234@heroku.com",
  "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​ リクエストを作成します。

リクエストの例

DELETE /heroku/resources/:provider_id HTTP/1.1
Host: addon-slug.herokuapp.com
Authorization: Basic YWRkb24tc2x1ZzpzdXBlci1zZWNyZXQ=
Content-Type: application/json
Accept: application/json

応答の例

HTTP/1.1 204 No Content
Heroku logo

Heroku Update
Starting November 28th, 2022, free Heroku Dynos, free Heroku Postgres, and free Heroku Data for Redis® will no longer be available. If you have apps using any of these resources, you must upgrade to paid plans by this date to ensure your apps continue to run and to retain your data.

Eligible students can apply for platform credits starting October 3rd, 2022 through our new Heroku for GitHub Students program.

Learn More