Platform API を使用したアプリのセットアップ

Table of Contents [expand]

ユースケース
アプリの設定の仕組み
アプリを準備する
アプリの設定を作成する
設定ステータスを確認する
ビルドの詳細を取得する
設定中に行われること
展開後

最終更新日 2025年07月17日(木)

この記事では、Heroku Platform API の app-setups リソースを使用して、プログラムで Heroku アプリを設定する方法について説明します。app-setups リソースとソースコード内の app.json マニフェストファイルを組み合わせることで、アプリの構成と展開を自動化できます。

app-setups は Heroku Button を動作させます。Heroku Button を README やドキュメントに追加すると、他のユーザーがアプリを迅速に展開できるようになります。

app-setups は、Fir ではご利用いただけません。

ユースケース

app.json および app-setups を使用すると、次のことができます。

共同作業者がテストやステージングのためにアプリを Heroku にデプロイできるようになります。
すぐに展開可能なアプリまたはフレームワークを配布して、他のユーザーが Heroku で試せるようにします。

アプリの設定の仕組み

app-setups リソースは、アプリのソースコードの .tar アーカイブを受け入れます。これは app.json マニフェストを探し、それを使用して Heroku での初期設定を調整します。このプロセスにより、展開とリリースが効率化されます。

アプリを準備する

この例では、heroku/node-js-sample アプリを使用します。このプロセスはどの言語にも適用されますが、このガイドでは Node.js に焦点を当てます。

app.json ファイルをアプリのルートディレクトリに追加します。たとえば、以下を含めることができます。
- アプリをカスタマイズするための環境設定。
- ログ記録用の Papertrail やデータベース用の Heroku Postgres などのアドオン。
- データベースを準備するための postdeploy コマンド。
アプリの tarball URL を取得します。公開 GitHub リポジトリの場合は、以下を使用します。 https://github.com/<username>/<repo name>/tarball/master/ サンプルアプリの場合は、https://github.com/heroku/node-js-sample/tarball/master/ を使用します。

アプリの設定を作成する

ソースの tarball を指定して、https://api.heroku.com/app-setups エンドポイントを呼び出します。リクエストボディには tarball URL を含める必要があります。

たとえば、cURL を使用する場合は次のようにします。

curl -n -X POST https://api.heroku.com/app-setups \
  -H "Content-Type:application/json" \
  -H "Accept:application/vnd.heroku+json; version=3" \
  -d '{"source_blob": { "url":"https://github.com/heroku/node-js-sample/tarball/master/"}}'

app.json で定義された環境変数を上書きするには、overrides セクションを追加します。

curl -n -X POST https://api.heroku.com/app-setups \
  -H "Content-Type:application/json" \
  -H "Accept:application/vnd.heroku+json; version=3" \
  -d '{"source_blob": { "url":"https://github.com/heroku/node-js-sample/tarball/master/"}, "overrides": {"env": { "NODE_ENV":"development" }}}'

Heroku は設定を開始し、追跡用の ID を含む応答を返します。

{
  "id": "df1c2983-fbde-455b-8e7b-e17c16bdf757",
  "failure_message": null,
  "status": "pending",
  "app": {
    "id": "888ee9fb-c090-499b-a115-2f335a1f0ef5",
    "name": "example-app"
  },
  "build": {
    "id": null,
    "status": null
  },
  "manifest_errors": [],
  "postdeploy": {
    "output": null,
    "exit_code": null
  },
  "resolved_success_url": null,
  "created_at": "2014-05-09T18:41:35+00:00",
  "updated_at": "2014-05-09T18:41:35+00:00"
}

アプリの作成に失敗した場合は、詳細を含む応答が返されます。

{
  "id": "invalid_params",
  "message": "You've reached the limit of 5 apps for unverified accounts. Add a credit card to verify your account."
}

設定ステータスを確認する

返された ID を使用して API をポーリングし、最新のステータスを取得します。

curl -n https://api.heroku.com/app-setups/df1c2983-fbde-455b-8e7b-e17c16bdf757 \
  -H "Content-Type:application/json" \
  -H "Accept:application/vnd.heroku+json; version=3"

ビルドが開始されると、次のような応答が表示されます。

{
  "id": "df1c2983-fbde-455b-8e7b-e17c16bdf757",
  "failure_message": null,
  "status": "pending",
  "app": {
    "id": "888ee9fb-c090-499b-a115-2f335a1f0ef5",
    "name": "example-app"
  },
  "build": {
    "id": "06503167-f75e-4ad6-bd06-4d5da3825eb5",
    "status": "pending"
  },
  "resolved_success_url": null
  // ...
}

設定中に問題が発生した場合、応答にエラーが示されます。

{
  "id": "df1c2983-fbde-455b-8e7b-e17c16bdf757",
  "failure_message": "app.json not found",
  "status": "failed",
  "app": {
    "id": "888ee9fb-c090-499b-a115-2f335a1f0ef5",
    "name": "example-app"
  }
  // ...
}

設定に失敗した場合、Heroku はアプリを削除しますが、設定ステータスは引き続き確認できます。

ビルドの詳細を取得する

ビルドが完了したら、アプリ名とビルド ID を使用して詳細なビルド出力を取得します。

curl -n -X GET https://api.heroku.com/apps/example-app/builds/06503167-f75e-4ad6-bd06-4d5da3825eb5/result \
  -H "Content-Type:application/json" \
  -H "Accept:application/vnd.heroku+json; version=3"

これにより、ビルド出力のすべての行を含む詳細なビルド結果が返されます。

{
  "build": {
    "id": "06503167-f75e-4ad6-bd06-4d5da3825eb5",
    "status": "succeeded"
  },
  "exit_code": 0,
  "lines": [
    {
      "stream": "STDOUT",
      "line": "\n"
    },
    {
      "stream": "STDOUT",
      "line": "-----> Node.js app detected\n"
    }
    // ...
  ]
}

postdeploy スクリプトの出力は、全体的な設定ステータスのポーリングリクエストへの応答内でインラインで提供されます。

"postdeploy": {
  "output": "",
  "exit_code": 0
}

ステータスが succeeded の場合、設定後にユーザーをリダイレクトするための完全修飾 URL が resolved_success_url に設定されます。この値は app.json マニフェストファイルの success_url 属性から決定されます。

"resolved_success_url": "http://example-app.herokuapp.com/"

設定中に行われること

API アプリを作成した後、ビルドする前にアドオンをプロビジョニングします。
app.json の env セクションで環境設定を定義します。これは、API を呼び出すときに上書きできます。
scripts.postdeploy コマンドは、アプリがリリースされた後に One-off dyno で実行されます。

アプリケーションメタデータ

name、description、website、repository、logo などのフィールドはユーザーに情報を提供しますが、設定中には API では使用されません。

{
  "name": "Node.js Sample",
  "description": "A barebones Node.js app using Express 4.",
  "website": "https://nodejs.org"
}

環境変数

env セクションでアプリの環境設定を定義します。

{
  "env": {
    "NODE_ENV": "production",
    "COOKIE_SECRET": {
      "description": "This gets generated",
      "generator": "secret"
    },
    "SETUP_BY": {
      "description": "Who initiated this setup",
      "required": false
    }
  }
}

変数には説明とデフォルト値を指定できます。プラットフォーム API のリクエストには、これらのデフォルトを上書きする値を指定するための overrides セクションを含めることができます。必須の変数を指定する必要があり、指定しないと設定が失敗します。任意の変数は "required": false を使用して指定できます。secret ジェネレーターは 64 文字の 16 進文字列を作成します。

アドオン

API は、アプリを作成した後にアドオンをプロビジョニングします。

{
  "addons": ["heroku-postgresql:essential-0", "papertrail"]
}

階層が指定されていない場合は、無料の階層が使用されます。

デプロイ後スクリプト

postdeploy スクリプトは app.json で指定できます。これはアプリがビルドされリリースされた後に、One-off dyno で実行されます。

{
  "scripts": {
    "postdeploy": "npm run db:migrate"
  }
}

複数のコマンドを実行する場合は、スクリプトファイルを使用して、これを postdeploy で参照します。

展開後

アプリはトラフィックを処理する準備が整いました。アプリには、app.json で定義されたとおりに、環境設定とアドオンがプロビジョニングされています。

環境設定の例:

heroku config -a example-app

=== example-app Config Vars
COOKIE_SECRET:              1e1867380b9365f2c212e31e9c43a87c17e82be0ce1a61406ea8274fac0680dc
DATABASE_URL:               postgres://...
HEROKU_POSTGRESQL_ONYX_URL: postgres://...
PAPERTRAIL_API_TOKEN:       ...
NODE_ENV:                   development
SETUP_BY:                   MyDeployerScript

アドオンの例:

heroku addons -a example-app

=== example-app Configured Add-ons
heroku-postgresql:essential-0  HEROKU_POSTGRESQL_ONYX
papertrail:choklad

データベースが移行され、アプリはトラフィックを処理する準備が整いました。

Git リポジトリが設定されています。開発を続けるには、このアプリのリポジトリをコピーします。

heroku git:clone example-app

Categories