Admin API のスタートガイド

リージョン ID

REGION_ID は、アプリの作成時に選択したリージョンに基づいて Google が割り当てる省略形のコードです。一部のリージョン ID は、一般的に使用されている国や州のコードと類似しているように見える場合がありますが、このコードは国または州に対応するものではありません。既存のアプリでは省略可能ですが、まもなく、新しいアプリのすべてにおいて App Engine の URL に REGION_ID.r を含めることが必須となる予定です。

移行がスムーズに行われるように、リージョン ID を使用するよう App Engine を徐々に更新しています。Google Cloud プロジェクトがまだ更新されていない場合、アプリにリージョン ID は表示されません。ID は既存のアプリでは省略可能なため、リージョン ID が既存のアプリで使用可能になったときに、URL の更新や他の変更を行う必要はありません。

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

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

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

目標

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

始める前に

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

ヒント: Hello World アプリをローカルで手動実行する場合は、Python App Engine スタンダード環境のクイックスタートをご覧ください。

Google Cloud プロジェクトの構成

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

  1. Cloud Console で 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 は、一般的に使用されている国や州のコードと類似しているように見える場合がありますが、このコードは国または州に対応するものではありません。既存のアプリでは省略可能ですが、まもなく、新しいアプリのすべてにおいて App Engine の URL に REGION_ID.r を含めることが必須となる予定です。

    移行がスムーズに行われるように、リージョン ID を使用するよう App Engine を徐々に更新しています。Google Cloud プロジェクトがまだ更新されていない場合、アプリにリージョン ID が表示されません。ID は既存のアプリでは省略可能なため、リージョン ID が既存のアプリで使用可能になったときに、URL の更新や他の変更を行う必要はありません。

  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 へのアクセスで、アプリケーションの認証情報を作成、構成、設定する方法を確認します。