Admin API のスタートガイド

リージョン ID

REGION_ID は、アプリの作成時に選択したリージョンに基づいて Google が割り当てる省略形のコードです。一部のリージョン ID は、一般的に使用されている国や州のコードと類似しているように見える場合がありますが、このコードは国または州に対応するものではありません。2020 年 2 月以降に作成されたアプリの場合、REGION_ID.r は App Engine の URL に含まれています。この日付より前に作成されたアプリの場合、URL のリージョン ID は省略可能です。

詳しくは、リージョン ID をご覧ください。

このガイドでは、App Engine Admin API を使用して Python アプリケーションのサンプルを App Engine にデプロイする方法について説明します。すべての手順を実施することで、アプリをプログラムで管理およびデプロイするコードの作成方法について深く理解できます。

このガイドで使用されているサンプルは、「Hello, World!」というテキストを表示する単純な Hello World アプリであり、GitHub で入手できます。Google Cloud コンソールでの認可には、OAuth クライアント ID とウェブブラウザを使用します。プロセスの個々の手順を示し、ターミナルから HTTP リクエストを送信できるよう cURL コマンドが用意されています。

目標

  • Google Cloud コンソール プロジェクトで API を有効にし、OAuth クライアント ID の認証情報を作成します。
  • App Engine で認証するためのアクセス トークンを取得します。
  • Admin API を使用してサンプル アプリケーションを App Engine にデプロイします。
  • (省略可)サンプルアプリをデプロイしたバージョンへのトラフィックを構成します。

始める前に

  • Google アカウントが必要です。まだアカウントをお持ちでない場合は、新規作成してください。
  • Google Cloud CLI をダウンロードしてインストールし、gcloud CLI を初期化します。
    SDK をダウンロード

Google Cloud プロジェクトの構成

Google Cloud プロジェクトで App Engine Admin API と Cloud Storage API を有効にしてから、認証情報を構成します。

  1. Google Cloud コンソールで API を有効にします。

    API を有効にする

  2. ウィザードで、リストから既存のプロジェクトを選択するか、[続行] をクリックして新しいプロジェクトを作成します。

  3. [続行] をクリックして、OAuth クライアント ID の認証情報を作成します。

    1. [OAuth 同意画面] で、少なくとも [メールアドレス] と [ユーザーに表示するサービス名] を入力します。
    2. [保存] をクリックして、同意画面の設定を保存してから、[認証情報] タブに切り替えます。
    3. [認証情報を作成] をクリックしてから [OAuth クライアント ID] をクリックして、クライアント ID を作成します。
    4. [ウェブ アプリケーション] をクリックして名前を指定し、リダイレクト URI として https://www.google.com を使用します。

    5. [作成] をクリックして、認証情報を保存します。

    6. 表示されるクライアント ID をメモしておきます。後のステップでアクセス トークンをリクエストする際に使用します。

Admin API の認証情報を作成する方法については、API へのアクセスをご覧ください。

構成ファイルの作成

Hello World アプリのデプロイを定義する構成ファイルを作成します。app.json という名前のファイルの sourceUrl フィールドで Hello World アプリの Cloud Storage バケットを定義し、id フィールドでバージョン ID などのバージョンの構成情報を定義します。

{
  "deployment": {
    "files": {
      "main.py": {
        "sourceUrl": "https://storage.googleapis.com/admin-api-public-samples/hello_world/main.py"
      },
    }
  },
  "handlers": [
    {
      "script": {
        "scriptPath": "main.app"
      },
      "urlRegex": "/.*"
    }
  ],
  "runtime": "python27",
  "threadsafe": true,
  "id": "appengine-helloworld",
  "inboundServices": [
    "INBOUND_SERVICE_WARMUP"
  ]
}

例: root/python-docs-samples/appengine/standard/hello_world/app.json

HTTP リクエストの承認

App Engine で認証し、Admin API で HTTP リクエストを送信できるようにします。

すぐに始めるには、以下のいずれかのオプションを使用してください。HTTPS オプションと gcloud オプションのどちらでも、Admin API を試用するためのアクセス トークンを手動かつ簡単な手順で取得できます。

HTTPS

クライアント側の OAuth 2.0 のフローをシミュレートするには、OAuth クライアント ID の認証情報を URI に追加して、ウェブブラウザから HTTPS リクエストを送信します。

  1. ウェブブラウザで、API 認証情報のクライアント ID を使用してアクセス トークンをリクエストします。次の例では、client_id=[MY_CLIENT_ID]redirect_uri=https://www.google.com を使用します。[MY_CLIENT_ID] は、先ほど作成した認証情報のクライアント ID です。

    https://accounts.google.com/o/oauth2/v2/auth?response_type=token&client_id=[MY_CLIENT_ID]&scope=https://www.googleapis.com/auth/cloud-platform&redirect_uri=https://www.google.com
    
  2. リクエストのレスポンスからアクセス トークンを取得します。

    ウェブブラウザのアドレス フィールドには、認証情報で指定したリダイレクト URI と、URI に付加されたアクセス トークンを含める必要があります。以下に例を示します。

    https://www.google.com/#access_token=[MY_ACCESS_TOKEN]&token_type=Bearer&expires_in=3600
    

    これで、access_token フィールドで指定されたアクセス トークン [MY_ACCESS_TOKEN] を使用して、HTTP リクエストを Google Cloud プロジェクトに送信できます。

gcloud

アクセス トークンを簡単に取得するには、以下の gcloud コマンドを実行します。

  1. アクセス トークンのリクエストに使用するアプリケーションのデフォルト認証情報(ADC)を設定します。

    gcloud auth application-default login
    
  2. アクセス トークンをリクエストします。

    gcloud auth application-default print-access-token
    

これらのコマンドの詳細については、gcloud auth application-default をご覧ください。

注意: アクセス トークンは発行後約 60 分で失効します。

上記のオプションはプログラムによる実装では使用しませんが、OAuth 2.0 の認証フローの実装方法については、Admin API へのアクセスをご覧ください。

Hello World アプリのデプロイ

HTTP リクエストを使用して、Admin API で Hello World アプリをデプロイします。

  1. Admin API で HTTP POST リクエストを送信して、Hello World アプリのバージョンを App Engine アプリケーションにデプロイします。次に例を示します。

    POST https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/versions app.json
    

    cURL コマンドの例:

    app.json 構成ファイルを作成したディレクトリから次のコマンドを実行します。次に例を示します。

    cd root/python-docs-samples/appengine/standard/hello_world/
    
    curl -X POST -T "app.json" -H "Content-Type: application/json" -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/versions
    

    ここで

    • [MY_ACCESS_TOKEN] は、HTTP リクエストを承認するために取得したアクセス トークンです。
    • [MY_PROJECT_ID] は、バージョンをデプロイするプロジェクトの ID です。

    レスポンスの例:

    {
      "name": "apps/[MY_PROJECT_ID]/operations/89729825-ef1f-4ffa-b3e3-e2c25eb66a85",
      "metadata": {
        "@type": "type.googleapis.com/google.appengine.v1.OperationMetadataV1",
        "insertTime": "2016-07-29T17:12:44.679Z",
        "method": "google.appengine.v1.Versions.CreateVersion",
        "target": "apps/[MY_PROJECT_ID]/services/default/versions/appengine-helloworld",
        "user": "me@example.com"
      }
    }
    

    ここで [MY_PROJECT_ID] は、Google Cloud プロジェクト ID です。

  2. Hello World アプリのバージョンが、App Engine アプリケーションに正常にデプロイされたことを確認します。

    1. 前のステップで HTTP GET メソッドname フィールドとして返されたオペレーションの名前を使用して、実際のデプロイ オペレーションのステータスを表示します。次に例を示します。

      GET https://appengine.googleapis.com/v1/[OPERATION_NAME]
      

      cURL コマンドの例:

      curl -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/[OPERATION_NAME]
      

      ここで

      • [OPERATION_NAME] は、前の手順でアプリをデプロイしたときに返された name フィールドの値です(例: apps/[MY_PROJECT_ID]/operations/89729825-ef1f-4ffa-b3e3-e2c25eb66a85)。
      • [MY_ACCESS_TOKEN] は、HTTP リクエストを承認するために取得したアクセス トークンです。
      • [MY_PROJECT_ID] は、バージョンをデプロイするプロジェクトの ID です。

      レスポンスの例:

      {
        "done": true,
        "metadata": {
          "@type": "type.googleapis.com/google.appengine.v1.OperationMetadataV1",
          "endTime": "2016-07-29T17:13:20.424Z",
          "insertTime": "2016-07-29T17:12:44.679Z",
          "method": "google.appengine.v1.Versions.CreateVersion",
          "target": "apps/[MY_PROJECT_ID]/services/default/versions/appengine-helloworld",
          "user": "me@example.com"
        },
        "name": "apps/[MY_PROJECT_ID]/operations/89729825-ef1f-4ffa-b3e3-e2c25eb66a85",
        "response": {
          "@type": "type.googleapis.com/google.appengine.v1.Version",
          "creationTime": "2016-07-29T17:12:46.000Z",
          "deployer": "me@example.com",
          "id": "appengine-helloworld",
          "name": "apps/[MY_PROJECT_ID]/services/default/versions/appengine-helloworld",
          "runtime": "python27",
          "servingStatus": "SERVING",
          "threadsafe": true,
        }
      }
      

      ここで [MY_PROJECT_ID] は、Google Cloud プロジェクト ID です。

    2. HTTP GET リクエストを使用してバージョンの詳細を表示し、Hello World アプリのバージョンが App Engine アプリケーションに作成されたことを確認します。次に例を示します。

      GET https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/versions/appengine-helloworld/?view=FULL
      

      cURL コマンドの例:

      curl -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/versions/appengine-helloworld/?view=FULL
      

      ここで

      • [MY_ACCESS_TOKEN] は、HTTP リクエストを承認するために取得したアクセス トークンです。
      • [MY_PROJECT_ID] は、バージョンをデプロイするプロジェクトの ID です。

      レスポンスの例:

      {
        "creationTime": "2016-07-29T17:12:46.000Z",
        "deployer": "me@example.com",
        "deployment": {
          "files": {
            "main.py": {
              "sha1Sum": "13f7ea1e24f7cd2de5c66660525f2b509da37c14",
              "sourceUrl": "https://storage.googleapis.com/admin-api-public-samples/hello_world/main.py"
            }
          }
        },
        "handlers": [
          {
            "authFailAction": "AUTH_FAIL_ACTION_REDIRECT",
            "login": "LOGIN_OPTIONAL",
            "script": {
              "scriptPath": "main.app",
            },
            "securityLevel": "SECURE_OPTIONAL",
            "urlRegex": "/.*"
          }
        ]
        "id": "appengine-helloworld",
        "name": "apps/[MY_PROJECT_ID]/services/default/versions/appengine-helloworld",
        "runtime": "python27",
        "servingStatus": "SERVING",
        "threadsafe": true,
        "versionUrl": "https://appengine-helloworld-dot-[MY_PROJECT_ID].[REGION_ID].r.appspot"
      }
      

      ここで [MY_PROJECT_ID] は、Google Cloud プロジェクト ID です。

  3. 前の手順で指定された HTTP レスポンスの versionUrl フィールドの URL にウェブブラウザでアクセスし、Hello World アプリを表示します。次に例を示します。

    https://appengine-helloworld-dot-[MY_PROJECT_ID].[REGION_ID].r.appspot.com
    

    ここで [MY_PROJECT_ID] は、Google Cloud プロジェクト ID です。

    REGION_ID は、アプリの作成時に選択したリージョンに基づいて Google が割り当てる省略形のコードです。一部のリージョン ID は、一般的に使用されている国や州のコードと類似しているように見える場合がありますが、このコードは国または州に対応するものではありません。2020 年 2 月以降に作成されたアプリの場合、REGION_ID.r が App Engine の URL に含まれています。この日付より前に作成されたアプリの場合、URL のリージョン ID は省略可能です。

  4. Hello World アプリへのトラフィックを構成します。

    デフォルトでは、新しい App Engine アプリケーションに最初にデプロイされたバージョンは自動的にすべてのトラフィックを受け取り、それ以降のバージョンはトラフィックをまったく受信しません。

    1. トラフィックを受信するようにバージョンが構成されているかを確認するには、次のように HTTP GET リクエストを送信します。

      GET https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default
      

      cURL コマンドの例:

      curl -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default
      

      ここで

      • [MY_ACCESS_TOKEN] は、HTTP リクエストを承認するために取得したアクセス トークンです。
      • [MY_PROJECT_ID] は、バージョンをデプロイするプロジェクトの ID です。

      レスポンスの例:

      {
        "name": "apps/[MY_PROJECT_ID]/services/default/",
        "id": "default",
        "split": {
          "allocations": {
            "appengine-helloworld": 1
          }
        }
      }
      

      ここで [MY_PROJECT_ID] は、Google Cloud プロジェクト ID です。

    2. すべてのトラフィックを特定のバージョンに移行するには、次のように HTTP PATCH リクエストを送信します。

      PATCH https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split {"split": { "allocations": { "appengine-helloworld": 1 } } }
      

      cURL コマンドの例:

      curl -X PATCH -H "Content-Type: application/json" -d "{ 'split': { 'allocations': { 'appengine-helloworld': '1' } } }" -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split
      

      ここで

      • [MY_ACCESS_TOKEN] は、HTTP リクエストを承認するために取得したアクセス トークンです。
      • [MY_PROJECT_ID] は、バージョンをデプロイするプロジェクトの ID です。

      レスポンスの例:

      {
        "name": "apps/[MY_PROJECT_ID]/operations/bdda402c-77a9-4c6d-b022-f2f69ba78420",
        "metadata": {
          "@type": "type.googleapis.com/google.appengine.v1.OperationMetadataV1",
          "insertTime": "2016-07-29T17:25:30.413Z",
          "method": "com.google.appengine.v1.Services.UpdateService",
          "target": "apps/[MY_PROJECT_ID]/services/default",
          "user": "me@example.com"
        }
      }
      

      ここで [MY_PROJECT_ID] は、Google Cloud プロジェクト ID です。

さらに詳しく

アプリのバージョンが複数ある場合は、以下の手順を実行してバージョン間でトラフィックを分割できます。

  1. Hello World アプリの 2 番目のバージョンを、以下の方法で同じ App Engine アプリケーションにデプロイします。

    1. 先ほど作成した Hello World アプリの既存の app.json 構成ファイルで、id フィールドを更新して別のバージョンを指定します。たとえば、-2 を追加します。

      "id": "appengine-helloworld-2"
      
    2. appengine-helloworld-2 バージョンを再度デプロイするには、同じ手順をもう一度すべて行います。次に例を示します。

      1. プロジェクトで認証します。
      2. 新しい appengine-helloworld-2 バージョンをデプロイします。
      3. appengine-helloworld-2 バージョンが正常にデプロイされたことを確認します。
      4. ウェブブラウザで実行中のアプリを表示します。
  2. トラフィックの移行と分割で説明されているトラフィックの分割手順を行います。たとえば、この手順では、HTTP PATCH リクエストの送信を行います。

    PATCH https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split { 'split': { 'shardBy': 'IP', 'allocations': { 'appengine-helloworld': '0.5', 'appengine-helloworld-2': '0.5' } } }
    

    cURL コマンドの例:

    curl -X PATCH -H "Content-Type: application/json" -d "{ 'split': { 'shardBy': 'IP', 'allocations': { 'appengine-helloworld': '0.5', 'appengine-helloworld-2': '0.5' } } }" -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split
    

    ここで

    • [MY_ACCESS_TOKEN] は、HTTP リクエストを承認するために取得したアクセス トークンです。
    • [MY_PROJECT_ID] は、バージョンをデプロイするプロジェクトの ID です。

次のステップ

  • API へのアクセスで、アプリケーションの認証情報を作成、構成、設定する方法を確認します。