最終更新日 2024年02月06日(火)

この記事では、Heroku Elements Marketplace​ のアドオン​を開発するための基本的な手順について説明します。アドオンの開発に関するその他の高度なトピックについては、「高度な統合​」を参照してください。

アドオンはクラウドサービスであるため、希望するどのような言語またはフレームワークでも開発できます。アドオンは Heroku 上で実行する必要はありません​。

アドオンの主な技術要件は次のとおりです。

• HTTPS リクエストを受信できる必要があります。
• JSON を解析できる必要があります。

開始する前に: アドオンパートナーとして登録する

まだの場合は、addons-next.heroku.com​ にアクセスしてログインしてください。パートナー向けのサービス利用規約への同意を求められます。同意後、Heroku パートナーポータルに転送され、アドオンの開発を開始できます。

手順 1: アドオンマニフェストを生成する

すべてのアドオンには、アドオンのメタデータ、設定、資格情報が含まれる addon-manifest.json​ ファイルがあります。アドオンマニフェストは、Heroku の addons-admin CLI プラグイン​を使用して作成します。

まず、Heroku CLI​ がインストールされ、heroku login​ 経由でログインしていることを確認します。

次に、addons-admin プラグイン​をインストールします。

$ heroku plugins:install addons-admin

その後、次のコマンドを使用して、アドオンのルートディレクトリにマニフェストを生成できます。

$ heroku addons:admin:manifest:generate

addon-manifest.json​ ファイルが現在の作業ディレクトリに作成されます。マニフェストには秘密情報が含まれているため、ソース管理にチェックインしないでください。

生成されたマニフェストは、デフォルト値やプレースホルダー値を含むスケルトンです。機能するアドオンサービスを作成するには、マニフェスト内の一部の属性を変更する必要があります。

マニフェストのフィールドの詳しい説明は、アドオンマニフェストの形式 を参照してください。

手順 2: Add-on Partner API と統合する

(アドオンのプロビジョニングや現在のプランの変更など) アドオンに関連した特定の管理アクションを Heroku の顧客が実行すると、アドオンで必要なアクションを実行できるよう、POST​ リクエストが Heroku からアドオンに送信されます。これらのリクエストは Add-on Partner API​ の一部です。

Add-on Partner API のリクエストを適切に受信および処理するように、アドオンを設定する必要があります。SSL、べき等性、リクエスト本体の検証、バージョン管理ヘッダー、エラー処理に関するガイドラインは「Add-on Partner API​」を参照してください。

基本認証

Add-on Partner API では、すべての操作に基本認証を使用します。ユーザー名はマニフェストの id​ (以前に選択した識別子)、パスワードはマニフェストの password​ フィールドになります。

use Rack::Auth::Basic, "Heroku API" do |username, password|
  username == "<id from Manifest>" && password == "<password from Manifest>"
end

プロビジョニングリクエスト

アドオンのプロビジョニングを顧客がリクエストすると、JSON ペイロードを含む POST​ リクエストが Heroku からアドオンの /heroku/resources​ エンドポイントに送信されます。

Heroku からプロビジョニングリクエストを受信したアドオンでは、以下のすべてを実行する必要があります。

• 顧客に必要なリソースをプロビジョニングする
• 将来のアドオンリクエスト (アップグレード/ダウングレード、プロビジョニング解除、SSO ダッシュボードへのサインインなど) を許可するために、Heroku のリクエストに含まれるメタデータを永続化する
• 顧客固有の設定情報を Heroku に返す

リクエストの例

# POST /heroku/resources

{
  "plan": "test",
  "uuid": "4b922d1d-f1d2-4fa9-9e6a-95f8f1aa58fb",
  "region": "amazon-web-services::us-east-1",
  "options": {},
  ...
}

実装例 (Ruby)

post '/heroku/resources' do
  # Create an instance of your service for the app uuid in the request
  service = Service.create!(
    plan: json_params[:plan],
    region: json_params[:region],
    heroku_uuid: json_params[:uuid] # The :resource_uuid used in all related requests
  )

  response = {
    id: service.id, # Unique identifier from your system
    config: { "SERVICE_URL" => service.url },
    message: "Welcome to our service"
  }

  status 200
  response.to_json
end

応答の例

{
  "config": {
    "SERVICE_URL": "https://user:password@service.example.com/path-to-resource"
  },
  "id": "37136775-c6f6-4d29-aa6b-12d1dad4febb",
  "message": "Welcome to our service!"
}

プロビジョニング解除リクエスト

顧客がアドオンを削除すると、DELETE​ リクエストが Heroku からアドオンに送信されます。このリクエストには、プロビジョニングリクエストと同様に HTTP 基本認証が使用されます。

リクエストの例

# :id is the unique identifier from your system that you responded
# with at provision time.

DELETE /heroku/resources/:resource_uuid

実装例 (Ruby)

delete '/heroku/resources/:resource_uuid' do
  Service.find(params[:resource_uuid]).destroy
  status 200
  {status: "OK"}.to_json
end

応答の例

200 OK​ 応答のみを返します (本体は不要)。

プラン変更リクエスト (アップグレード/ダウングレード)

顧客が現在のアドオンプランを変更すると、PUT​ リクエストが Heroku からアドオンに送信されます。

プラン変更リクエストを受信したアドオンでは、以下を実行する必要があります。

• リクエストに応じて機能と設定をアップグレードまたはダウングレードする
• 必要な状態 (データベースの内容など) を自動的に移行するか、手動で移行する方法をドキュメントで顧客に通知する
• 新しいプランを使用するための新しい設定値で Heroku に応答する

リクエストの例

# :id is the unique identifier from your system that you responded
# with at provision time.

PUT /heroku/resources/:resource_uuid

{
  "plan": "another_plan",
  ...
}

実装例 (Ruby)

put '/heroku/resources/:resource_uuid' do
  service = Service.find(params[:resource_uuid])
  service.change_plan(json_params[:plan])

  result = {
    config: { "SERVICE_URL" => service.url },
    message: "Successfully changed from #{original_plan} to #{json_params[:plan]}"
  }

  result.to_json
end

応答の例

{
  "config": {
    "SERVICE_URL": "https://user:password@service.example.com/new-url"
  },
  "message": "Successfully changed from original_plan to another_plan"
}

シングルサインオン

シングルサインオン (SSO) 統合を実装すると、アドオンの顧客に Web UI コントロールパネルを提供できます。SSO 実装の詳しいガイドには、アドオンのシングルサインオンのチュートリアル​からアクセスできます。

手順 3: アドオンをデプロイする

パブリックアクセスが可能な場所にサービスをデプロイします。(もちろん可能ですが) 必ずしも Heroku にデプロイする必要はありません。

アドオンをデプロイしたら、addon-manifest.json​ ファイルで production​ 属性内の base_url​ と sso_url​ の値を変更して、デプロイされたアプリを指すようにします。

最後に、更新した addon-manifest.json​ ファイルを Heroku にプッシュしてアドオンを登録します。アドオンのパートナー向けサービス利用規約に同意したアカウントで Heroku CLI にログインしている必要があります。

$ heroku addons:admin:manifest:push

この時点では、アドオンはその公開者 (のみ) がプロビジョニングのためにアクセスできる状態です。公開者はパートナーポータルでアドオンの詳細を管理したり、Heroku Dashboard または CLI からアドオンをインストールしたりできます。

手順 4: アドオンのテスト/ステージングバージョンを作成する

SSO やその他のアドオン統合機能をテストするために、アドオンの <your slug>-staging​ バージョンを作成することをお勧めします。この <your slug>-staging​ アドオンは、統合インフラストラクチャのステージングバージョンを指すようにしてください。

アドオンのステージングバージョンは永久にアルファ版のままであり、プロビジョニングされたプランに対して料金を請求することはできません。

高度な統合

Heroku との統合により、他にも多くのことを実現できます。より高度な統合についての詳細は、以下の記事をご覧ください。

• 共有可能なアドオン
• パートナー向け Platform API
• アドオンのログ記録の統合
• CLI パラメータの処理

次の記事: ​アドオンのリリース