"[レガシー] アドオンパートナーのアプリ情報 API"
この記事の英語版に更新があります。ご覧の翻訳には含まれていない変更点があるかもしれません。
最終更新日 2020年12月22日(火)
Table of Contents
この API は非推奨になる予定であり、代わりに新しいバージョンが推奨されています。現在の API については、アドオンパートナー API を確認してください。
これは、アドオンのインストールに関する情報に対してクエリを実行するために使用できる API 呼び出しのための参照ドキュメントです。これらの例では、ユーザーがリクエストを発行し、Heroku が応答を提供します。すべての呼び出しで HTTP 基本認証を使用する必要があります。ここでユーザー名はアドオンマニフェストの id
(slug ともいいます)、パスワードはアドオンマニフェストで指定されているものに設定する必要があります。
すべてのアプリの取得
アドオンをインストールしているアプリの一覧を取得します。resource.uuid
値は、プロビジョニングリクエスト中に送信される uuid
フィールドに対応しています。
GET https://<manifest_id>:<manifest_password>@api.heroku.com/vendor/apps
応答の例
[
{
"callback_url": "https://api.heroku.com/vendor/apps/01234567-89ab-cdef-0123-456789abcdef",
"heroku_id": "app123@heroku.com",
"plan": "test",
"provider_id": "1",
"resource": {
"uuid": "01234567-89ab-cdef-0123-456789abcdef",
"name": "addon-fluffy-6756"
}
},
{
"callback_url": "https://api.heroku.com/vendor/apps/abcdef12-3456-7890-abcd-ef1234567890",
"heroku_id": "app456@heroku.com",
"plan": "premium",
"provider_id": "3",
"resource": {
"uuid": "abcdef12-3456-7890-abcd-ef1234567890",
"name": "addon-vertical-9873"
}
}
]
アプリ情報 API エンドポイントで返される callback_url
および heroku_id
属性は、互換性のみを目的としています。パートナーには、これらを使用しないことをお勧めします。代わりに、アプリ情報の取得エンドポイントと provider_id
属性を使用してください。
結果のページ分割
4000 より大きい結果はページ分割されます。ページ分割の情報は、Link
HTTP ヘッダー経由で渡されます。ページ分割をクライアントコードで構成するのではなく、これらの URI を使用して移動します。
例
Link: <https://api.heroku.com/vendor/apps?offset=100>; rel="prev", <https://api.heroku.com/vendor/apps?offset=1000>; rel="next"
そのヘッダー内の指定できる rel
値は次のとおりです。
next
: 結果の直後のページの URL を示します。prev
: 結果の直前のページの URL を示します。
アプリ情報の取得
いずれかのアドオンインスタンスに関する詳細 (アプリの名前、プラン、所有者のメールを含む) を取得します。これは、顧客との通信のためのアプリ名を見つけるために使用されるエンドポイントです (heroku_id
は顧客によって認識されないため、使用しないこと)。
このエンドポイントは、プロビジョニングが完了すると 200 応答のみを返します。プロビジョニングリクエスト中にアプリ情報にアクセスしようとすると、404 応答が返されます。一部のフィールドはアドオンマニフェストに依存しており、省略される可能性があります。
GET https://<manifest_id>:<manifest_password>@api.heroku.com/vendor/apps/<app_identifier>
ここで、使用される app_identifier
は次のいずれかである必要があります (設定の降順に示す)。
provider_id
resource.uuid
heroku_id
- 注意、共有可能なアドオンの機能との将来の互換性のために、この識別子の使用を停止することをお勧めします。
応答の例
{
"id": "app123@heroku.com",
"callback_url": "https://api.heroku.com/vendor/apps/01234567-89ab-cdef-0123-456789abcdef",
"config": {
"MYADDON_URL": "http://myaddon.com/52e82f5d73"
},
"domains": [ "www.the-consumer.com", "the-consumer.com" ],
"log_input_url": "https://token:t.abcdef12-3456-7890-abcd-ef1234567890@1.us.logplex.io/logs"
"name": "myapp",
"plan": "test",
"owner_email": "glenn@heroku.com",
"owner": {
"uuid": "31e71f4d-b0f6-4250-8c1a-f914b99adba2",
"email": "glenn@heroku.com"
},
"region": "amazon-web-services::us-east-1",
"resource": {
"uuid": "01234567-89ab-cdef-0123-456789abcdef",
"name": "addon-fluffy-6756"
}
}
環境設定の更新
プロビジョニング中にアプリケーションに対して以前に設定された環境設定を更新します。
アドオンマニフェストで宣言されている環境設定のみを更新できます。
本文は、1 つの config
キーのみがキーと値のペアのオブジェクトに設定されている、1 つのオブジェクトで構成される JSON 文字列である必要があります。各ペアには、割り当てる必要があるキーと新しい値としての環境設定名が必要です。
PUT https://<manifest_id>:<manifest_password>@api.heroku.com/vendor/apps/<provider_id>
curl の例
$ curl -n -X PUT https://$MANIFEST_ID:$MANIFEST_PASSWORD@api.heroku.com/vendor/apps/$PROVIDER_ID \
-H "Content-Type: application/json" \
-d '{
"config": {
"MYADDON_URL": "https://myaddon.com/ABC123",
"MYADDON_API_KEY": "0123456789abcdef"
}
}'
エラー応答
エラーの根本的原因に応じて、次の応答コードが返されます。
401
: 無効なユーザー名とパスワードの組み合わせが指定され、まだ正常に認証されていません。
404
: 要求されたアプリが存在しない (たとえば、削除されている) か、またはアドオンがこのアプリに対してプロビジョニング解除されています。
アドオンベータユーザーのカウント
アドオンが一般提供段階に進む前に、アドオンプロバイダにはアドオンをテストする最低 100 個の固有ベータユーザーが必要です。
ベータユーザーのカウントを取得するには、以下の手順に従います。
- アプリ情報の取得エンドポイントを使用して、アドオンが現在インストールされているすべてのアプリを取得し、
provider_id
のリストを作成します。 - アプリ情報の取得エンドポイントを、
provider_id
ごとに 1 回使用して、アプリ所有者メールのリスト (属性owner.email
) を作成します。 - 重複するアプリ所有者メールを削除し、一意のカウントを取得します。
実装例
これは、curl
および標準の *nix ツールを使用した Bash スクリプトの例です。
#!/bin/bash
MANIFEST_ID="<manifest_id>"
MANIFEST_PASSWORD="<manifest_password>"
function app_list {
curl -s -X GET https://${MANIFEST_ID}:${MANIFEST_PASSWORD}@api.heroku.com/vendor/apps
}
function extract_app_provider_id {
sed -n '/provider_id/! { d; }; /.*"provider_id":"\(.*\)"/ { s//\1/; p; }'
}
function app_info() {
curl -s -X GET https://${MANIFEST_ID}:${MANIFEST_PASSWORD}@api.heroku.com/vendor/apps/$1
}
function extract_owner_email {
sed -n '/owner_email/! { d; }; /.*\"owner_email\":"\(.*\)".*/ { s//\1/; p; }'
}
echo "Unique app owners for '${MANIFEST_ID}': $(for i in $(app_list | extract_app_provider_id); do app_info $i | extract_owner_email; done | sort -u | wc -l)"