Cloud Run での Endpoints スタートガイド

このページでは、Cloud Run 用に Cloud Endpoints を設定する方法を説明します。Endpoints は Extensible Service Proxy V2 ベータ版(ESPv2 ベータ版)API ゲートウェイとして使用します。Cloud Run 向けに API 管理機能を提供するには、事前にビルドされた ESPv2 ベータ版コンテナを Cloud Run にデプロイします。Cloud Run IAM を使用してサービスを保護し、ESPv2 ベータ版がサービスを呼び出せるようにします。

この設定では、ESPv2 ベータ版がサービスに対するすべてのリクエストを傍受し、必要なチェック(認証など)を行ってから、該当するサービスを呼び出します。サービスが応答すると、ESPv2 ベータ版はテレメトリーを収集して報告します。サービスの指標は、Google Cloud Console の [エンドポイント] > [サービス] ページで確認できます。

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

タスクリスト

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

  1. Google Cloud プロジェクトを作成します。独自の Cloud Run をデプロイしていない場合は、サンプルのサービスをデプロイします。始める前にをご覧ください。
  2. ESPv2 ベータ版コンテナを Cloud Run にデプロイします。ESPv2 ベータ版のデプロイをご覧ください。
  3. API を記述する OpenAPI ドキュメントを作成し、Cloud Run へのルートを構成します。Endpoints を構成するをご覧ください。
  4. OpenAPI ドキュメントをデプロイして、マネージド サービスを作成します。Endpoints 構成をデプロイするをご覧ください。
  5. Endpoints サービス構成で新しい ESPv2 ベータ版 Docker イメージをビルドし、デプロイします。次に、サービスを呼び出すための Cloud Identity and Access Management(Cloud IAM)権限を ESPv2 ベータ版に付与します。新しい ESPv2 ベータ版イメージをビルドするをご覧ください。
  6. サービスを呼び出します。API にリクエストを送信するをご覧ください。
  7. サービスに対するアクティビティを追跡します。API のアクティビティを追跡するをご覧ください。
  8. Google Cloud アカウントへの課金が発生しないようにします。クリーンアップをご覧ください。

始める前に

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

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

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

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

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

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

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

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

    Cloud SDK をダウンロード

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

ESPv2 ベータ版のデプロイ

ESPv2 ベータ版コンテナを Cloud Run にデプロイするには:

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

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

    Service [CLOUD_RUN_SERVICE_NAME] revision [CLOUD_RUN_SERVICE_NAME-REVISION_NUM] has been deployed and is serving traffic at CLOUD_RUN_SERVICE_URL

    CLOUD_RUN_SERVICE_NAMEgateway に設定した場合:

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

    この例では、https://gateway-12345-uc.a.run.appCLOUD_RUN_SERVICE_URLgateway-12345-uc.a.run.appCLOUD_RUN_HOSTNAME です。

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

Endpoints を構成する

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

  1. openapi-run.yaml という名前のテキスト ファイルを作成します。(便宜上、このページでは OpenAPI ドキュメントをファイル名で表記していますが、必要に応じてファイル名以外の名前を指定することもできます)。
  2. Cloud Run バックエンド サービスは、x-google-backend 定義にある openapi-run.yaml ファイルの上部で定義されます。例:
      swagger: '2.0'
      info:
        title: Cloud Endpoints + Cloud Run
        description: Sample API on Cloud Endpoints with a Cloud Run backend
        version: 1.0.0
      host: HOST
      schemes:
        - https
      produces:
        - application/json
      x-google-backend:
        address: https://hello-HASH-uc.a.run.app
      paths:
        /hello:
          get:
            summary: Greet a user
            operationId: hello
            responses:
              '200':
                description: A successful response
                schema:
                  type: string
    
    yaml 形式ではインデントが重要です。たとえば、host フィールドは info と同じレベルにする必要があります。
  3. x-google-backend セクションの address フィールドで、https://hello-HASH-uc.a.run.app は Cloud Run サービスの実際の URL で置き換えます。ここで、HASH はサービスの作成時に生成された一意のハッシュコードです。

    この例では、クイックスタート: gcloud コマンドライン ツールの使用で作成された hello コードを使用していることを前提としています。必要であれば、この値を Cloud Run サービスの URL に置き換えます。

  4. host フィールドで、CLOUD_RUN_HOSTNAME を指定します。これは、ESPv2 ベータ版のデプロイで ESPv2 ベータ版をデプロイしたときに Cloud Run が作成した URL のホスト名の部分です。プロトコルの識別子である https:// は含めません。例:

    swagger: '2.0'
      info:
        title: Cloud Endpoints + Cloud Run
        description: Sample API on Cloud Endpoints with a Cloud Run backend
        version: 1.0.0
      host: gateway-12345-uc.a.run.app
    
  5. openapi-run.yaml ファイルの title プロパティの値をメモします。

    title: Cloud Endpoints + Cloud Run

    title プロパティの値は、構成をデプロイした後の Endpoints サービスの名前になります。

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

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

Endpoints 構成をデプロイする

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

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

  1. OpenAPI ドキュメントが格納されているディレクトリに移動します。
  2. 構成をアップロードしてマネージド サービスを作成します。

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

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

    Service Management でサービスの作成と構成が行われるとき、情報がデバイスに出力されます。デプロイが完了すると、次のようなメッセージが表示されます。

    Service Configuration [CONFIG_ID] uploaded for service [CLOUD_RUN_HOSTNAME]

    CONFIG_ID は、デプロイで作成される一意の Endpoints サービス構成 ID です。例:

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

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

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

必要なサービスを確認する

Endpoints と ESP を使用するには、少なくとも次のサービスが必要です。
名前 タイトル
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 SERVICE_NAME

SERVICE_NAME は、有効化するサービスの名前で置き換えます。

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

新しい ESPv2 ベータ版イメージをビルドする

新しい ESPv2 ベータ版 Docker イメージに Endpoints サービス構成を作成し、そのイメージを使用して ESPv2 ベータ版 Cloud Run サービスを再デプロイします。その後、サービスを呼び出すための Cloud IAM の権限を ESPv2 ベータ版に付与します。

新しい ESPv2 ベータ版 Docker イメージにサービス構成をビルドするには:

  1. gcloud SDK がインストールされているローカルホストにこのスクリプトをダウンロードし、次のように実行します。

    chmod +x gcloud_build_image
    ./gcloud_build_image -s CLOUD_RUN_HOSTNAME \
        -c CONFIG_ID -p ESP_PROJECT_ID

    CLOUD_RUN_HOSTNAME には、CLOUD_RUN_SERVICE_URL のホスト名を指定します。これは、ESPv2 ベータ版のデプロイで ESPv2 ベータ版をデプロイしたときに Cloud Run が作成した URL です。プロトコルの識別子である https:// は含めません。

    例:

    chmod +x gcloud_build_image
    ./gcloud_build_image -s gateway-12345-uc.a.run.app \
        -c 2019-02-01-r0 -p ESP_PROJECT_ID

    このスクリプトは、gcloud コマンドを使用してサービス構成をダウンロードし、新しい ESPv2 ベータ版イメージにサービス構成を組み込み、新しいイメージを次のプロジェクト コンテナ レジストリにアップロードします。

    gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:CLOUD_RUN_HOSTNAME-CONFIG_ID

    例:

    gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:gateway-12345-uc.a.run.app-2019-02-01-r0"
  2. 新しいイメージを使用して、ESPv2 ベータ版 Cloud Run サービスを再デプロイします。CLOUD_RUN_SERVICE_NAME は、ESPv2 ベータ版のデプロイで最初にデプロイしたときに使用した Cloud Run サービスで置き換えます。

    gcloud run deploy CLOUD_RUN_SERVICE_NAME \
      --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:CLOUD_RUN_HOSTNAME-CONFIG_ID" \
      --allow-unauthenticated \
      --platform managed \
      --project=ESP_PROJECT_ID
  3. CORS を有効にするなどの追加の ESPv2 ベータ版起動オプションを使用するように Endpoints を構成する場合は、引数を ESPv2_ARGS 環境変数に渡すことができます。

    gcloud run deploy CLOUD_RUN_SERVICE_NAME \
      --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:CLOUD_RUN_HOSTNAME-CONFIG_ID" \
      --set-env-vars=ESPv2_ARGS=--cors_preset=basic \
      --allow-unauthenticated \
      --platform managed \
      --project ESP_PROJECT_ID

    使用可能なオプション、複数のオプションの指定方法など、ESPv2_ARGS 環境変数の詳細と設定例については、Extensible Service Proxy V2 ベータ版のフラグをご覧ください。

  4. Cloud Run サービスを呼び出すための権限を ESPv2 ベータ版に付与します。各サービスに対して次のコマンドを実行します。このコマンドで、次の要素を置き換えてください。
    • BACKEND_SERVICE_NAME は、呼び出す Cloud Run サービスの名前で置き換えます。クイックスタート: gcloud コマンドライン ツールの使用で作成した関数を使用している場合、この値として hello を使用します。
    • ESP_PROJECT_NUMBER は、ESPv2 ベータ版に作成したプロジェクトのプロジェクト番号で置き換えます。この番号を調べる 1 つの方法としては、IAM コンソールに移動して、デフォルトのコンピューティング サービス アカウントを探す方法があります。これは、member フラグで使用されているサービス アカウントです。
    gcloud run services add-iam-policy-binding BACKEND_SERVICE_NAME \
      --member "serviceAccount:ESP_PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
      --role "roles/run.invoker" \
      --platform managed \
      --project BACKEND_PROJECT_ID

詳細については、Cloud IAM によるアクセス管理をご覧ください。

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 インスタンスを削除するをご覧ください。

次のステップ