App Engine スタンダード環境用 Endpoints スタートガイド

このページでは、App Engine 用に Cloud Endpoints を設定する方法を説明します。Endpoints は Extensible Service Proxy(ESP)API ゲートウェイとして使用します。App Engine 向けに API 管理機能を提供するには、事前にビルドされた ESP コンテナを Cloud Run にデプロイします。そのうえで、Identity Aware Proxy(IAP)を使用してアプリのセキュリティを確保し、ESP がアプリを呼び出せるようにします。この設定では、ESP がアプリに対するすべてのリクエストを傍受し、必要なチェック(認証など)を行ってから、該当するアプリを呼び出します。アプリが応答すると、ESP はテレメトリーを収集して報告します。アプリの指標は、Google Cloud Console の [エンドポイント] > [サービス] ページで確認できます。

Cloud Endpoints の概要については、Endpoints についてEndpoints アーキテクチャをご覧ください。

タスクリスト

次のタスクリストを参照しながら、チュートリアルを実施してください。Endpoints でアプリを管理するには、ここに挙げるすべてのタスクを行う必要があります。

  1. Google Cloud プロジェクトを作成します。独自の App Engine をデプロイしていない場合は、サンプルアプリをデプロイします。始める前にをご覧ください。
  2. IAP を構成してアプリのセキュリティを確保します。IAP を構成するをご覧ください。
  3. ESP コンテナを Cloud Run にデプロイします。 ESP をデプロイするをご覧ください。
  4. API を記述する OpenAPI ドキュメントを作成し、App Engine へのルートを構成します。Endpoints を構成するをご覧ください。
  5. OpenAPI ドキュメントをデプロイして、マネージド サービスを作成します。 Endpoints 構成をデプロイするをご覧ください。
  6. サービスの構成を検出できるように ESP を構成します。ESP を構成するをご覧ください。
  7. アプリを呼び出します。API にリクエストを送信するをご覧ください。
  8. アプリに対するアクティビティを追跡します。 API の活動を追跡するをご覧ください。
  9. Google Cloud アカウントへの課金が発生しないようにします。 クリーンアップをご覧ください。

始める前に

App Engine 用 Endpoints はアルファ版のため、次のことをおすすめします。

  • 新しい Google Cloud プロジェクトを作成し、ESP コンテナを Cloud Run にデプロイするときにこのプロジェクトを使用する。

  • App Engine 用の新しいプロジェクトを作成するか、既存のプロジェクトを選択する。

次の手順に従って設定します。

  1. Cloud Console で [リソースの管理] ページに移動し、プロジェクトを作成します。

    [リソースの管理] ページに移動

  2. プロジェクトに対して課金が有効になっていることを確認します。

    課金を有効にする方法について

  3. 後で必要になるため、プロジェクト ID をメモしておきます。このページでは以降、このプロジェクト ID を ESP_PROJECT_ID と表記します。

  4. 後で必要になるため、プロジェクト番号をメモしておきます。このページでは以降、このプロジェクト番号を ESP_PROJECT_NUMBER と表記します。

  5. Cloud SDK をダウンロードしてインストールします。

    Cloud SDK をダウンロード

  6. 独自の App Engine をデプロイしていない場合は、お使いの言語の App Engine のクイックスタートの手順に従って、gcloud コマンドライン ツールを使用し、Google Cloud プロジェクトを選択または作成してサンプルアプリをデプロイします。アプリがデプロイされているリージョンとプロジェクト ID をメモしておきます。このページでは以降、このプロジェクト ID を APP_PROJECT_ID と表記します。

IAP を構成してアプリのセキュリティを確保する

App Engine アプリを保護するには、Identity Aware Proxy(IAP)を使用して、リクエストが認証されるようにする必要があります。

手順に従って IAP を有効化し、アプリにログインできることを確認します。

また、OAuth クライアントを構成するときに、OAuth client_id をメモしておきます。このクイックスタートでは、この ID を IAP_CLIENT_ID と表記します。

ESP をデプロイする

ESP コンテナを Cloud Run にデプロイするには:

  1. データとサービスへのアクセスを Cloud SDK に対して承認していることを確認します。
    1. ログインします。
      gcloud auth login
    2. 表示された新しいブラウザタブで、ESP を Cloud Run にデプロイするために作成した Google Cloud プロジェクトの編集者またはオーナーのロールが割り当てられているアカウントを選択します。
  2. リージョンを設定します。現在、Cloud Run でサポートされているのは us-central1 だけです。
    gcloud config set run/region us-central1
  3. ESP を Cloud Run にデプロイします。CLOUD_RUN_SERVICE_NAME は、このサービスに使用する名前に置き換えます。
        gcloud beta run deploy CLOUD_RUN_SERVICE_NAME \
            --image="gcr.io/endpoints-release/endpoints-runtime-serverless:1.30.0" \
            --allow-unauthenticated \
            --project=ESP_PROJECT_ID
        

    このコマンドが正常に完了すると、次のようなメッセージが表示されます。

        Service [gateway] revision [gateway-00001] has been deployed and is serving
        traffic at https://gateway-12345-uc.a.run.app

    上記の例では、gateway は、Cloud Run サービスの名前です。

  4. URL に含まれるホスト名をメモしておきます。このホスト名を、OpenAPI ドキュメントの host フィールドに指定します。
  5. この Cloud Run サービスはインターネット上で一般公開されます。認証機能を追加する場合は、Endpoints でサポートされている認証方法のいずれかを使用することをおすすめします。

エンドポイントの作成

OpenAPI 仕様 v2.0 に基づいて、アプリの surface と認証要件を記述する OpenAPI ドキュメントを用意する必要があります。また、ESP がアプリを呼び出すために必要な情報を取得できるよう、このドキュメントには各アプリの URL を設定した Google 固有のフィールドも追加する必要があります。OpenAPI を初めて使用する場合は、OpenAPI の概要で詳細をご覧ください。

  1. openapi-appengine.yaml という名前のテキスト ファイルを作成します(便宜上、このページでは OpenAPI ドキュメントをこのファイル名で表記していますが、必要に応じて別の名前を指定することもできます)。
  2. 各アプリは、openapi-appengine.yaml ファイルの paths セクションに表示されている必要があります。例:
          swagger: '2.0'
          info:
            title: Cloud Endpoints + App Engine
            description: Sample API on Cloud Endpoints with an App Engine backend
            version: 1.0.0
          host: HOST
          schemes:
            - https
          produces:
            - application/json
          x-google-backend:
            address: https://APP_PROJECT_ID.REGION.r.appspot.com
            jwt_audience: IAP_CLIENT_ID
          paths:
            /hello:
              get:
                summary: Greet a user
                operationId: hello
                responses:
                  '200':
                    description: A successful response
                    schema:
                      type: string
        
  3. x-google-backend セクションの address フィールドで、APP_PROJECT_ID を Google Cloud プロジェクト ID、REGION を App Engine をデプロイした GCP リージョン、IAP_CLIENT_ID を IAP の設定時に作成した OAuth クライアント ID に置き換えます。
  4. host フィールドに、Cloud Run で ESP 用に作成されたサービス提供 URL のホスト名を追加します。プロトコル識別子の https:// は含めません。例:
        swagger: '2.0'
          info:
            title: Cloud Endpoints + App Engine
            description: Sample API on Cloud Endpoints with an App Engine backend
            version: 1.0.0
          host: gateway-12345-uc.a.run.app
        

    Endpoints は、host フィールドで構成した名前をサービスの名前として使用します。

  5. OpenAPI ドキュメントを保存します。

Endpoints に必要な OpenAPI ドキュメントのフィールドについては、Endpoints を構成するをご覧ください。

Endpoints 構成をデプロイする

Endpoints の構成をデプロイするには、gcloud endpoints services deploy コマンドを使用します。このコマンドを実行すると、Service Management を使用してマネージド サービスが作成されます。

Endpoints 構成をデプロイするには:

  1. OpenAPI ドキュメントが格納されているディレクトリに移動します。

  2. 構成をアップロードしてマネージド サービスを作成します。

        gcloud endpoints services deploy openapi-appengine.yaml \
          --project ESP_PROJECT_ID
        

    これにより、openapi-appengine.yaml ファイルの host フィールドに指定した名前で、新しい Endpoints サービスが作成されます。このサービスは、OpenAPI ドキュメントに従って構成されています。

サービスが作成され構成されるに従い、ターミナルには Service Management からの情報が出力されます。デプロイが完了すると、次のようなメッセージが表示されます。

    Service Configuration [2019-02-01-r0] uploaded for service [gateway-12345-uc.a.run.app]
    

上記の例では、2019-02-01-r0 はサービス構成 ID で、gateway-12345-uc.a.run.app は Endpoints サービス名です。サービス構成 ID は、日付スタンプとそれに続くリビジョン番号で構成されます。同じ日に openapi-appengine.yaml を再度デプロイすると、サービス構成 ID のリビジョン番号が増分されます。Cloud Console で [エンドポイント] の [サービス] ページを開くと、サービス構成とデプロイの履歴を確認できます。

エラー メッセージが表示された場合は、Endpoints 構成のデプロイのトラブルシューティングをご覧ください。

必要なサービスの確認

Endpoints と ESP を使用するには、少なくとも次の Google サービスの有効化が必要です。
名前 タイトル
servicemanagement.googleapis.com Service Management API
servicecontrol.googleapis.com Service Control API
endpoints.googleapis.com Google Cloud Endpoints

ほとんどの場合、gcloud endpoints services deploy コマンドによってこれらの必須サービスが有効化されます。ただし、以下の状況では、gcloud コマンドは正常に完了しますが、必須サービスが有効になりません。

  • Terraform などのサードパーティのアプリケーションを使用していて、上記のサービスを含めていない場合。

  • 上記のサービスが明示的に無効にされている既存の Google Cloud プロジェクトに Endpoints 構成をデプロイした場合。

必要なサービスが有効になっていることを確認するには、次のコマンドを実行します。

gcloud services list
    

必要なサービスが表示されない場合は、次のコマンドを使用してサービスを有効にします。

gcloud services enable servicemanagement.googleapis.com
    gcloud services enable servicecontrol.googleapis.com
    gcloud services enable endpoints.googleapis.com

Endpoints サービスも有効にします。

gcloud services enable ENDPOINTS_SERVICE_NAME

ENDPOINTS_SERVICE_NAME を確認するには、次のいずれかを行います。

  • Endpoints 構成をデプロイ後、Cloud Console の [Endpoints] ページに移動します。ENDPOINTS_SERVICE_NAME のリストはサービス名の列の下に表示されます。

  • OpenAPI の場合、ENDPOINTS_SERVICE_NAMEは OpenAPI 仕様の host フィールドで指定したものです。gRPC の場合、ENDPOINTS_SERVICE_NAME は gRPC Endpoints 構成の name フィールドで指定したものです。

gcloud コマンドの詳細については、gcloud サービスをご覧ください。

ESP を構成する

Endpoints サービスの構成を検出できるように ESP を構成します。そのうえで、IAP で保護されたアプリを呼び出すための Cloud IAM 権限を ESP に付与します。

ESP を構成するには:

  1. ESP が Endpoints の構成を検出して読み込めるよう、次のコマンドを使用して Endpoints サービス名を構成します。このコマンドで、次の要素を置き換えてください。

    • YOUR_SERVICE_NAME を実際の Endpoints サービスの名前に置き換えます。これは、OpenAPI ドキュメントの host フィールドで指定した名前です。
    • CLOUD_RUN_SERVICE_NAME を実際の Cloud Run サービスの名前に置き換えます。
        gcloud beta run services update CLOUD_RUN_SERVICE_NAME \
           --set-env-vars ENDPOINTS_SERVICE_NAME=YOUR_SERVICE_NAME \
           --project ESP_PROJECT_ID
        
  2. CORS を有効にするなどの追加の ESP 起動オプションを使用するように Endpoints を構成する場合は、引数を ESP_ARGS 環境変数に渡すことができます。

        gcloud beta run services update CLOUD_RUN_SERVICE_NAME \
           --set-env-vars="^|^ENDPOINTS_SERVICE_NAME=YOUR_SERVICE_NAME|ESP_ARGS=--rollout_strategy=managed,--cors_preset=basic" \
           --project ESP_PROJECT_ID
        

    この場合、ENDPOINTS_SERVICE_NAME--rollout_strategy を指定する必要があります。

  3. IAP で保護されたアプリを呼び出す権限を ESP に付与します。次のコマンドを実行します。コマンドは次のように変更してください。

    • APP_PROJECT_ID を App Engine のプロジェクト ID に置き換えます。
    • ESP_PROJECT_NUMBER を ESP 用に作成したプロジェクトのプロジェクト番号で置き換えます。この番号を調べる 1 つの方法としては、IAM コンソールに移動して、デフォルトのコンピューティング サービス アカウントを探す方法があります。member フラグでは、このサービス アカウントを使用しています。
        gcloud projects add-iam-policy-binding APP_PROJECT_ID \
            --member "serviceAccount:ESP_PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
            --role "roles/iap.httpsResourceAccessor"
        

API にリクエストを送信する

このセクションでは、API にリクエストを送信する方法を説明します。

  1. Endpoints サービス名の環境変数を作成します。これは、OpenAPI ドキュメントの host フィールドで指定した名前です。例:
    • Linux または macOS:

      export ENDPOINTS_HOST=gateway-12345-uc.a.run.app

    • Windows PowerShell:

      $Env: ENDPOINTS_HOST="gateway-12345-uc.a.run.app"

Linux または Mac OS

前の手順で設定した ENDPOINTS_HOST 環境変数を使用して、curl で HTTP リクエストを送信します。

    curl --request GET \
       --header "content-type:application/json" \
       "https://${ENDPOINTS_HOST}/hello"

PowerShell

前の手順で設定した ENDPOINTS_HOST 環境変数を使用して、Invoke-WebRequest で HTTP リクエストを送信します。

    (Invoke-WebRequest -Method GET `
        -Headers @{"content-type"="application/json"} `
        -URI "https://$Env:ENDPOINTS_HOST/hello").Content
    

上記の例では、最初の 2 行はバッククォートで終わります。この例を PowerShell に貼り付けるとき、バッククォートの後にスペースがないことを確認してください。このリクエスト例で使用されているオプションについては、Microsoft のドキュメントの Invoke-WebRequest をご覧ください。

サードパーティ製アプリ

Chrome ブラウザ拡張機能の Postman など、サードパーティのアプリケーションを使用できます。

  • HTTP 動詞として GET を選択します。
  • ヘッダーで、キー content-type とその値 application/json を選択します。
  • 環境変数ではなく、実際の URL を使用します。次に例を示します。

    https://gateway-12345-uc.a.run.app/hello
        

正常なレスポンスが返されなかった場合は、レスポンス エラーのトラブルシューティングをご覧ください。

これで Endpoints の API のデプロイとテストが完了しました。

API の活動を追跡する

  1. Cloud Console で [エンドポイント] の [サービス] ページに移動して、API のアクティビティ グラフを確認します。

    Endpoints のアクティビティ グラフを表示

    グラフにリクエストが反映されるまでしばらくかかります。

  2. [ログビューア] ページで API のリクエストログを確認します。

    Endpoints のリクエストログを表示

API のデベロッパー ポータルを作成する

Cloud Endpoints Portal を使用してデベロッパー ポータルを作成できます。デベロッパー ポータルとは、サンプル API の操作に使用できるウェブサイトです。詳細については、Cloud Endpoints Portal の概要をご覧ください。

クリーンアップ

このクイックスタートで使用したリソースについて、Google Cloud アカウントに課金されないようにするには:

このチュートリアルで使用したサービスを停止するには、API と API インスタンスを削除するをご覧ください。

次のステップ