Skip Navigation
Show nav
Heroku Dev Center
  • Get Started
  • ドキュメント
  • Changelog
  • Search
  • Get Started
    • Node.js
    • Ruby on Rails
    • Ruby
    • Python
    • Java
    • PHP
    • Go
    • Scala
    • Clojure
  • ドキュメント
  • Changelog
  • More
    Additional Resources
    • Home
    • Elements
    • Products
    • Pricing
    • Careers
    • Help
    • Status
    • Events
    • Podcasts
    • Compliance Center
    Heroku Blog

    Heroku Blog

    Find out what's new with Heroku on our blog.

    Visit Blog
  • Log inorSign up
View categories

Categories

  • Heroku のアーキテクチャ
    • Dyno (アプリコンテナ)
    • スタック (オペレーティングシステムイメージ)
    • ネットワーキングと DNS
    • プラットフォームポリシー
    • プラットフォームの原則
  • コマンドライン
  • デプロイ
    • Git を使用したデプロイ
    • Docker によるデプロイ
    • デプロイ統合
  • 継続的デリバリー
    • 継続的統合
  • 言語サポート
    • Node.js
    • Ruby
      • Bundler の使用
      • Rails のサポート
    • Python
      • Python でのバックグランドジョブ
      • Django の使用
    • Java
      • Maven の使用
      • Java でのデータベース操作
      • Java の高度なトピック
      • Spring Boot の使用
    • PHP
    • Go
      • Go の依存関係管理
    • Scala
    • Clojure
  • データベースとデータ管理
    • Heroku Postgres
      • Postgres の基礎
      • Postgres Getting Started
      • Postgres のパフォーマンス
      • Postgres のデータ転送と保持
      • Postgres の可用性
      • Postgres の特別なトピック
    • Heroku Redis
    • Apache Kafka on Heroku
    • その他のデータストア
  • モニタリングとメトリクス
    • ログ記録
  • アプリのパフォーマンス
  • アドオン
    • すべてのアドオン
  • 共同作業
  • セキュリティ
    • アプリのセキュリティ
    • ID と認証
    • コンプライアンス
  • Heroku Enterprise
    • Private Space
      • インフラストラクチャネットワーキング
    • Enterprise Accounts
    • Enterprise Team
    • Heroku Connect (Salesforce 同期)
      • Heroku Connect の管理
      • Heroku Connect のリファレンス
      • Heroku Connect のトラブルシューティング
    • シングルサインオン (SSO)
  • パターンとベストプラクティス
  • Heroku の拡張
    • Platform API
    • アプリの Webhook
    • Heroku Labs
    • アドオンのビルド
      • アドオン開発のタスク
      • アドオン API
      • アドオンのガイドラインと要件
    • CLI プラグインのビルド
    • 開発ビルドパック
    • Dev Center
  • アカウントと請求
  • トラブルシューティングとサポート
  • Integrating with Salesforce
  • Heroku の拡張
  • アドオンのビルド
  • アドオン API
  • アドオンパートナー API リファレンス

アドオンパートナー API リファレンス

日本語 — Switch to English

最終更新日 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-west-1​ (カリフォルニア)
  • ​
  • ​ amazon-web-services::eu-west-1​ (ダブリン)
  • ​
  • ​ amazon-web-services::eu-central-1​ (フランクフルト)
  • ​
  • ​ amazon-web-services::us-west-2​ (オレゴン)
  • ​
  • ​ amazon-web-services::ap-southeast-1​ (シンガポール)
  • ​
  • ​ amazon-web-services::ap-southeast-2​ (シドニー)
  • ​
  • ​ amazon-web-services::ap-northeast-1​ (東京)
  • ​
  • ​ amazon-web-services::us-east-1​ (バージニア)
  • ​
​ これを使用してアプリに地理的に近い場所でリソースをプロビジョニングするか、これを無視するか (アドオンのレイテンシー感度が高くない場合)、または指定されたリージョン内のアプリをアドオンがサポートしていない場合はエラーで応答します。
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&timestamp=1267597772&nav-data=eyJhZGRvbiI6IllvdXIgQWRkb24iLCJhcHBuYW1lIjoibXlhcHAiLCJhZGRvbnMiOlt7InNsdWciOiJjcm9uIiwibmFtZSI6IkNyb24ifSx7InNsdWciOiJjdXN0b21fZG9tYWlucyt3aWxkY2FyZCIsIm5hbWUiOiJDdXN0b20gRG9tYWlucyArIFdpbGRjYXJkIn0seyJzbHVnIjoieW91cmFkZG9uIiwibmFtZSI6IllvdXIgQWRkb24iLCJjdXJyZW50Ijp0cnVlfV19&email=user%40example.com&foo=bar

応答の例

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

関連カテゴリー

  • アドオン API
アドオンパートナーのイベント通知 Webhook の使用 (アドオンパートナー向け)

Information & Support

  • Getting Started
  • Documentation
  • Changelog
  • Compliance Center
  • Training & Education
  • Blog
  • Podcasts
  • Support Channels
  • Status

Language Reference

  • Node.js
  • Ruby
  • Java
  • PHP
  • Python
  • Go
  • Scala
  • Clojure

Other Resources

  • Careers
  • Elements
  • Products
  • Pricing

Subscribe to our monthly newsletter

Your email address:

  • RSS
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku Blog
    • Heroku News Blog
    • Heroku Engineering Blog
  • Heroku Podcasts
  • Twitter
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku
    • Heroku Status
  • Facebook
  • Instagram
  • Github
  • LinkedIn
  • YouTube
Heroku is acompany

 © Salesforce.com

  • heroku.com
  • Terms of Service
  • Privacy
  • Cookies
  • Cookie Preferences