Platform API スターターガイド

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

最終更新日 2023年06月14日(水)

前提条件
サンプル
認証
API の呼び出し
代替
まとめ

これは、Heroku Platform API の使用開始を支援するための簡単なガイドです。詳細なリファレンスについては、「Platform API Reference」 (Platform API リファレンス) の記事を参照してください。

前提条件

curl のシェル
Heroku ユーザーアカウント。無料ですぐにサインアップできます。

サンプル

以下のサンプルでは、便宜上 curl を使用します。お好みのプログラミング言語と HTTP ライブラリを API で使用することをお勧めします。

または、以下のクライアントライブラリも使用できます。

認証

認証は、Bearer {token} に設定された値とともに Authorization ヘッダーで渡されます。

curl を使用していて、Heroku CLI でログインしている場合、curl -n を使用して自動でこのヘッダーを CLI と同じトークンに設定できます。このトークンは、heroku auth:token で取得することもできますが、有効期間はデフォルトで最大 1 年間です。

heroku authorizations:create を実行して、有効期限のないトークンを作成することができます。

$ heroku authorizations:create -d "getting started token"
Creating OAuth Authorization... done
Client:      <none>
ID:          a6e98151-f242-4592-b107-25fbac5ab410
Description: getting started token
Scope:       global
Token:       cf0e05d9-4eca-4948-a012-b91fe9704bab
Updated at:  Fri Jun 01 2018 13:26:56 GMT-0700 (PDT) (less than a minute ago)

フェデレーションユーザーへの注意

SSO を使用していて (ユーザーアカウントが ID プロバイダーに関連付けられていて)、有効期限のないトークンを作成しようとしている場合、次のエラーメッセージが表示されます。 "This account is a federated account. Federated accounts cannot issue OAuth authorizations."

API に接続する必要があり、有効期限のないトークンを使用してこれを行う必要がある場合、別のユーザーを作成し、そのユーザーを Heroku 組織に招待しますが、そのユーザーを ID プロバイダーに追加しないようにすることをお勧めします。そのユーザーは、組織によって使用されるトークンを生成して管理することができます。

API の呼び出し

netrc ファイルからのトークンを使用して、curl でアプリを作成する方法を以下に示します。

$ curl -nX POST https://api.heroku.com/apps \
-H "Accept: application/vnd.heroku+json; version=3"

heroku authorizations:create で作成され、HEROKU_API_KEY 環境変数に格納されている API キーでアプリを作成するには、以下のようにします。

$ curl -X POST https://api.heroku.com/apps \
-H "Accept: application/vnd.heroku+json; version=3" \
-H "Authorization: Bearer $HEROKU_API_KEY"

Windows では、以下のように定義されます。

> curl -X POST https://api.heroku.com/apps \
-H "Accept: application/vnd.heroku+json; version=3" \
-H "Authorization: Bearer %HEROKU_API_KEY%"

API は、新しく作成されたアプリの詳細を含む JASON を返します。

{
  "created_at":"2013-05-21T22:36:48-00:00",
  "id":"01234567-89ab-cdef-0123-456789abcdef",
  "git_url":"git@heroku.com:cryptic-ocean-8852.git",
  "name":"cryptic-ocean-8852",
  ...
}

以下のパスで ID を渡し、作成したアプリに関する情報について API にクエリを行うこともできます。

$ curl -nX GET https://api.heroku.com/apps/01234567-89ab-cdef-0123-456789abcdef \
-H "Accept: application/vnd.heroku+json; version=3"

ユーザーが所有する、または共同作業しているすべてのアプリを一覧にすることもできます。

$ curl -nX GET https://api.heroku.com/apps \
-H "Accept: application/vnd.heroku+json; version=3"

情報の取得で使用したものと同じパスに PATCH リクエストを行い、上記で作成したアプリの名前を更新します。

$ curl -nX PATCH https://api.heroku.com/apps/01234567-89ab-cdef-0123-456789abcdef \
-H "Accept: application/vnd.heroku+json; version=3" \
-H "Content-Type: application/json" \
-d "{\"name\":\"my-awesome-app\"}"

この名前を使用してアプリにクエリを行うこともできます。これは、より覚えやすい名前に変更した場合に便利です。

$ curl -n https://api.heroku.com/apps/my-awesome-app \
-H "Accept: application/vnd.heroku+json; version=3"

最後に、クリーンアップを行い、テストアプリを削除します。

$ curl -nX DELETE https://api.heroku.com/apps/01234567-89ab-cdef-0123-456789abcdef \
-H "Accept: application/vnd.heroku+json; version=3"

代替

Heroku API プラグインは、CLI に任意のコマンドを実行するのに使用できます。

$ heroku plugins:install api
$ heroku api POST /apps --body '{"name": "example-app"}'
POST api.heroku.com/apps... 201
{
  "name": "example-app",
  "region": {
    "id": "59accabd-516d-4f0e-83e6-6e3757701145",
    "name": "us"
  },
  "updated_at": "2018-06-01T21:00:41Z",
  "web_url": "https://example-app-1234567890ab.herokuapp.com/",
  ...
}

httpie は便利な cURL 代替であり、若干 cURL より使いやすくなっています。Httpie では netrc からの認証資格情報が自動的に使用され、デフォルトで JSON を POST しているものとみなされます。

$ http PATCH https://api.heroku.com/apps/example-app/config-vars \
"Accept:application/vnd.heroku+json; version=3" \
RAILS_ENV=production
HTTP/1.1 200 OK
Cache-Control: private, no-cache
Content-Encoding: gzip
Content-Length: 672
Content-Type: application/json
...
{
    "DATABASE_URL": "postgres://pg",
    "RAILS_ENV": "production"
}

まとめ

このチュートリアルでは curl を使用して Heroku Platform API を呼び出す方法について説明していますが、このアプローチは任意の言語および環境で使用することができます。このチュートリアルは、アプリの作成、更新、削除に重点を置いています。この API では、アドオン、環境設定、ドメインなど、さまざまなリソースを利用できます。これらはすべてアプリと同様に機能し、詳細情報は API リファレンスで確認できます。

Categories

Platform API スターターガイド

Table of Contents

前提条件

サンプル

認証

フェデレーションユーザーへの注意

API の呼び出し

代替

まとめ

関連カテゴリー