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

この記事の英語版に更新があります。ご覧の翻訳には含まれていない変更点があるかもしれません。

最終更新日 2024年05月08日(水)

セットアップの準備
アプリのセットアップの作成
セットアップステータスのポーリング
背後での作業
デプロイされたアプリ

この記事では、Platform API の app-setups リソースの使用方法について説明します。このリソースを、ソースコードに埋め込まれた app.json マニフェストファイルと共に使用して、プログラムでアプリをセットアップすることができます。

アプリのセットアップは、Heroku Button を強化するテクノロジです。保守するソースコードのセットアップを簡単にするために、README または関連するガイドおよびチュートリアルに Heroku Button を追加することを検討してください。

ここで示すいくつかのシナリオでは、保守するソースコードで app.json および app-setups が役立つ場合があります。

ステージングアプリでテストするために共同作業者が各自のソースコードをセットアップして Heroku にデプロイする作業を簡単にしたい
すぐにデプロイできるアプリまたはフレームワークを管理していて、他の人にもそれをすばやく Heroku にデプロイして試してもらいたい

app-setups リソースは、アプリケーションのソースコードの tar アーカイブを受け取り、app.json マニフェストファイルを探し、それを使用して、Heroku へのアプリケーションの初回セットアップを調整し、アプリケーションのデプロイとリリースを効率化します。

セットアップの準備

app-setups リソースを使用して単純なアプリケーションをデプロイしたいと考えていると仮定します。これは独自のアプリケーションかもしれませんし、興味のあるサンプルまたはテンプレートかもしれません。

ruby-rails-sample サンプルアプリケーションはそのような例です。ここでは例として Ruby を使用しているだけであり、どの言語で記述されたアプリでもこの API を使用できることに注意してください。

最初の手順では、app.json 設定ファイルをアプリに追加します。このアプリの設定には次のものが含まれます。

テンプレートをカスタマイズするためのランタイム環境内の環境設定
いくつかのアドオン
- ログ記録用の Papertrail
- データベース用の Heroku Postgres
データベースを準備するためにデプロイ後に実行されるコマンド。

API を呼び出すには、そのソース tarball の URL が必要です。この例では、この URL を使用します。API では、この設定情報を含む app.json ファイルが、ソースバンドルのディレクトリ構造のルートに存在していることを期待します。

パブリック GitHub リポジトリをソースコード用に使用している場合、各リポジトリに固有で、リポジトリの内容の tarball に解決する URL が GitHub によって提供されます。この URL は通常、次のようになります。https://github.com/<username>/<repo name>/tarball/master/

アプリのセットアップの作成

app.json を含むソース tarball を使用して https://api.heroku.com/app-setups エンドポイントを呼び出し、app.json に対応したアプリケーションを Heroku 上でセットアップします。アプリケーションのソースコードの tarball を指すソース URL がリクエストの本体に含まれている必要があります。

cURL を使用して app-setups エンドポイントを呼び出してみましょう。

$ 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/ruby-rails-sample/tarball/master/"} }'

必要に応じて、overrides セクションをリクエストに含めることで、app.json で指定された環境変数の値を提供する、デフォルト値を上書きする、または追加の環境変数を提供することができます。app.jsonのうち上書きできるのは env セクションの部分だけです。

$ 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/ruby-rails-sample/tarball/master/"},
"overrides": {"env": { "RAILS_ENV":"development" } } }'

Heroku では、生成されたアプリ名で Heroku アプリを作成することでアプリケーションのセットアップを開始し、すぐに応答を返します。この応答に含まれている ID を後のリクエストで使用できます。

{
    "id": "df1c2983-fbde-455b-8e7b-e17c16bdf757",
    "failure_message": null,
    "status": "pending",
    "app": {
        "id": "888ee9fb-c090-499b-a115-2f335a1f0ef5",
        "name": "pacific-peak-6986"
    },
    "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": "pacific-peak-6986"
  },
  "build": {
    "id": "06503167-f75e-4ad6-bd06-4d5da3825eb5",
    "status": "pending"
   },
   "resolved_success_url": null,
   ...
}

ステータスが pending から succeeded または failed に変わるまでポーリングを続けます。

セットアップ中に問題が発生した場合、応答でそれらのエラーが示されます。

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

セットアッププロセスのどこかで手順が失敗した場合、アプリは削除されますが、セットアップのステータスはいつでも確認できます。

ビルドステータスが succeeded または failed に更新されたら、ビルド ID を使用して Platform API を呼び出し、ビルドのより詳細なステータスを取得できます。詳細は、「Platform API を使用したビルドとリリース」を参照してください。ビルドステータスのリクエストを作成するには、セットアップ中のアプリの名前とビルド ID の両方が必要です。これらはどちらも、前出の応答に含まれています。

$ curl -n -X GET https://api.heroku.com/apps/pacific-peak-6986/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": "-----> Ruby app detected\n"
     },
     ...

デプロイ後スクリプトの出力は、全体的なセットアップステータスのポーリングリクエストへの応答内でインラインで提供されます。

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

ステータスが succeeded の場合、セットアップの完了時にユーザーをリダイレクトする先の完全修飾 URL が resolved_success_url に設定されます。この値は app.json マニフェストファイルの success_url 属性から決定されます。success_urlが絶対 URL の場合、そのまま返されます。相対 URL の場合、アプリの web_url のコンテキストで解決されます。

"resolved_success_url": "http://pacific-peak-6986.herokuapp.com/"

背後での作業

次に示すのは、app.json ファイル内のさまざまな要素に対して Heroku Platform API が実行する処理の概要です。app.jsonを使用してセットアップしたアプリは、通常、Git ベースのワークフローを使用してデプロイしたアプリと同じように動作します。app-setups では Build API を使用するため、ソース tarball が GitHub から取得された場合、それらのソース tarball には Git サブモジュールが復元されないことに注意してください。

この記事で説明するセットアップフローは API を通じて利用でき、Heroku Button を使用したアプリのセットアップを拡張するものです。

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

name、description、website、repository、logo の各フィールドは、アプリケーションに関する基本的な情報を提供します。これは、ユーザーが app.json の内容からアプリケーションの概要を把握するための情報にすぎず、アプリケーションのセットアップ中に API がこのセクションを使用するわけではありません。

"name": "Ruby on Rails",
"description": "A template for getting started with the popular Ruby framework.",
"website": "http://rubyonrails.org"

環境変数

env セクションは、一連の変数と、それらの変数に関する詳細情報で構成されます。変数ごとに、API によってアプリの環境設定が行われます。

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

変数には説明とデフォルト値を指定できます。前の例で示したように、Platform API のリクエストには、これらのデフォルト値を上書きする値を提供する overrides セクションが含まれる場合があります。

app.json で値が指定されている場合、API はそれを必須の変数として扱います。Platform API が呼び出されるときに、overrides セクションで変数の値が指定されている必要があります。指定されていないと、セットアップは失敗します。省略可能な変数は "required": false を使用して指定できます。

一部の変数には、アプリケーションのデプロイおよびセットアップ時に生成される値が必要です。これらの変数のジェネレーターを指定できます。現在サポートされている唯一のジェネレーターは、64 文字の 16 進文字列を生成する secret です。

アドオン

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

アプリの作成直後、またコードがビルドおよびリリースされる前に、API によってアドオンがプロビジョニングされます。app.jsonでは、アドオン名のみ、またはアドオン名と特定の層の組み合わせを指定できます。層を指定しない場合、Platform API は最下位層 (多くのアドオンでは無料層) をプロビジョニングします。

デプロイ後スクリプト

1 つのデプロイ後スクリプトを app.json ファイルで指定できます。このスクリプトは、アプリケーションがビルドおよびリリースされるとすぐ、Heroku によって One-off dyno で実行されます。このスクリプトはアプリケーションと同じ環境で実行され、その環境設定とアドオンにアクセスできます。

"scripts": {
  "postdeploy": "bundle exec rake db:migrate"
}

実行する複数のコマンドがある場合、それらをスクリプトに入れて、スクリプトをソースバンドルに追加し、そのスクリプトを実行するために使用するコマンドを postdeploy の値として指定します。アプリケーションと同じ言語でスクリプトを記述し、rails setup-script.rb などの適切なコマンドを指定することもできます。

デプロイされたアプリ

この例の Heroku アプリは、次の環境設定を使用してセットアップされています。

$ heroku config -a pacific-peak-6986

=== pacific-peak-6986 Config Vars
COOKIE_SECRET:              1e1867380b9365f2c212e31e9c43a87c17e82be0ce1a61406ea8274fac0680dc
DATABASE_URL:               postgres://bdlgvbfnitiwtf:DGuFLR87rMNFe7cr_y1HGwadMm@ec2-54-225-182-133.compute-1.amazonaws.com:5432/d8p7bm6d7onr10
HEROKU_POSTGRESQL_ONYX_URL: postgres://bdlgvbfnitiwtf:DGuFLR87rMNFe7cr_y1HGwadMm@ec2-54-225-182-133.compute-1.amazonaws.com:5432/d8p7bm6d7onr10
PAPERTRAIL_API_TOKEN:       VikcKA2wQf2H1ajww3s
RAILS_ENV:                  development
SETUP_BY:                   MyDeployerScript

次のアドオンがプロビジョニングされています。

$ heroku addons -a pacific-peak-6986

=== pacific-peak-6986 Configured Add-ons
heroku-postgresql:essential-0  HEROKU_POSTGRESQL_ONYX
papertrail:choklad

データベースが移行され、アプリケーションはトラフィックを処理する準備ができています。

Heroku アプリに関連付けられた Git リポジトリにソースコードが準備されています。アプリのコーディングを続行し、標準の git push デプロイで変更をプッシュするには、アプリを複製するだけです。

$ heroku git:clone pacific-peak-6986

Cloning from app 'pacific-peak-6986'...
Cloning into 'pacific-peak-6986'...
Initializing repository, done.
remote: Counting objects: 77, done.
remote: Compressing objects: 100% (69/69), done.
remote: Total 77 (delta 2), reused 0 (delta 0)
Receiving objects: 100% (77/77), 17.85 KiB | 0 bytes/s, done.
Resolving deltas: 100% (2/2), done.
Checking connectivity... done

Categories

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

Table of Contents

セットアップの準備

アプリのセットアップの作成

セットアップステータスのポーリング

背後での作業

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

環境変数

アドオン

デプロイ後スクリプト

デプロイされたアプリ

関連カテゴリー