ESPv2 を使用して Cloud Run 用の Cloud Endpoints OpenAPI を設定する

OpenAPI | gRPC

このページでは、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 の [エンドポイント] > [サービス] ページで確認できます。

Endpoints アーキテクチャ

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

ESPv2 に移行する

Cloud Endpoints の以前のリリースでは、Cloud Run との Extensible Service Proxy（ESP）の使用がサポートされていました。既存の API を ESPv2 に移行するには、詳細について Extensible Service Proxy V2 への移行をご覧ください。

タスクリスト

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

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

費用

このドキュメントでは、Google Cloud の次の課金対象のコンポーネントを使用します。

料金計算ツールを使うと、予想使用量に基づいて費用の見積もりを生成できます。新しい Google Cloud ユーザーは無料トライアルをご利用いただける場合があります。

このドキュメントに記載されているタスクの完了後、作成したリソースを削除すると、それ以上の請求は発生しません。詳細については、クリーンアップをご覧ください。

始める前に

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

Google Cloud コンソールで [リソースの管理] ページに移動し、プロジェクトを作成します。
[リソースの管理] ページに移動
プロジェクトに対して課金が有効になっていることを確認します。
課金を有効にする方法について
後で必要になるため、プロジェクト ID をメモしておきます。このページでは以降、このプロジェクト ID を ESP_PROJECT_ID として記載します。
後で必要になるため、プロジェクト番号をメモしておきます。このページでは以降、このプロジェクト番号を ESP_PROJECT_NUMBER として記載します。
Google Cloud CLI をダウンロードしてインストールします。
gcloud CLI をダウンロードする
独自の Cloud Run バックエンドサービスをデプロイしていない場合は、クイックスタート: 事前にビルドされたサンプルコンテナのデプロイの手順に従って Google Cloud プロジェクトを選択または作成し、サンプルバックエンドをデプロイします。サービスがデプロイされているリージョンとプロジェクト ID をメモしておきます。このページでは以降、このプロジェクト ID を BACKEND_PROJECT_ID とします。デプロイされたサービスの名前は BACKEND_SERVICE_NAME とします。

Cloud Run ホスト名の予約

OpenAPI ドキュメントまたは gRPC サービス構成を構成するには、ESPv2 サービス用の Cloud Run ホスト名を予約する必要があります。ホスト名を予約するには、Cloud Run にサンプルコンテナをデプロイします。後で、同じ Cloud Run サービスに ESPv2 コンテナをデプロイします。

gcloud CLI がデータやサービスにアクセスできるように承認されていることを確認します。
1. ログインします。
```
gcloud auth login
```
2. 表示された新しいブラウザタブで、ESPv2 を Cloud Run にデプロイするために作成した Google Cloud プロジェクトの編集者またはオーナーのロールが割り当てられているアカウントを選択します。

リージョンを設定します。

gcloud config set run/region us-central1

サンプルイメージ gcr.io/cloudrun/hello を Cloud Run にデプロイします。CLOUD_RUN_SERVICE_NAME は、このサービスに使用する名前に置き換えます。
```
gcloud run deploy CLOUD_RUN_SERVICE_NAME \
    --image="gcr.io/cloudrun/hello" \
    --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_NAME を gateway に設定した場合:
```
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.app が CLOUD_RUN_SERVICE_URL で、gateway-12345-uc.a.run.app が CLOUD_RUN_HOSTNAME です。
CLOUD_RUN_SERVICE_NAME と CLOUD_RUN_HOSTNAME をメモします。ESPv2 ベータ版を後で CLOUD_RUN_SERVICE_NAME Cloud Run サービスにデプロイします。OpenAPI ドキュメントの host フィールドで CLOUD_RUN_HOSTNAME を指定します。

Endpoints を構成する

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

openapi-run.yaml という名前のテキストファイルを作成します。（便宜上、このページでは OpenAPI ドキュメントをファイル名で表記していますが、必要に応じてファイル名以外の名前を指定することもできます）。

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: CLOUD_RUN_HOSTNAME
schemes:
  - https
produces:
  - application/json
x-google-backend:
  address: BACKEND_SERVICE_NAME
  protocol: h2
paths:
  /hello:
    get:
      summary: Greet a user
      operationId: hello
      responses:
        '200':
          description: A successful response
          schema:
            type: string

yaml 形式ではインデントが重要です。たとえば、host フィールドは info と同じレベルにする必要があります。

x-google-backend セクションの address フィールドで、BACKEND_SERVICE_NAME を始める前にのステップ 6 で作成したバックエンド Cloud Run サービスの実際の URL に置き換えます。

この例では、クイックスタート: 事前にビルドされたサンプルコンテナのデプロイで作成された hello バックエンドサービスを使用していることを前提としています。別のバックエンド Cloud Run サービスを使用している場合は、BACKEND_SERVICE_NAME を Cloud Run サービスの URL に置き換えます。
host フィールドで、CLOUD_RUN_HOSTNAME を指定します。これは、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
```
openapi-run.yaml ファイルの title プロパティの値をメモします。
```
title: Cloud Endpoints + Cloud Run
```
title プロパティの値は、構成をデプロイした後の Endpoints サービスの名前になります。
OpenAPI ドキュメントを保存します。

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

Endpoints 構成をデプロイする

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

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

OpenAPI ドキュメントが格納されているディレクトリに移動します。
構成をアップロードしてマネージドサービスを作成します。
```
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-01r0] uploaded for service [gateway-12345-uc.a.run.app]
```
サービス構成 ID は、日付スタンプとそれに続くリビジョン番号で構成されます。同じ日に openapi-run.yaml を再度デプロイすると、サービス構成 ID のリビジョン番号が増分されます。Google Cloud コンソールで [エンドポイント] > [サービス] ページを開くと、サービス構成とデプロイの履歴を確認できます。

エラーメッセージが表示された場合は、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 コンソールの [Endpoints] ページに移動します。[サービス名] 列に、考えられる ENDPOINTS_SERVICE_NAME のリストが表示されます。
OpenAPI の場合、ENDPOINTS_SERVICE_NAME は OpenAPI 仕様の host フィールドで指定したものです。gRPC の場合、ENDPOINTS_SERVICE_NAME は gRPC Endpoints 構成の name フィールドで指定したものです。

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

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

新しい ESPv2 Docker イメージに Endpoints サービス構成をビルドします。その後、このイメージを予約済みの Cloud Run サービスにデプロイします。

注:

このステップは必須です。

Cloud Run はゼロスケーリングのサービスのため、サービス構成を新しい Docker イメージに構築する必要があります。つまり、トラフィックがない場合はすべてのインスタンスが削除され、トラフィックが増加すると新しいインスタンスがオンデマンドで生成されます。このタイプのサービスインスタンスの生成をコールドスタートともいいます。詳細については、Cloud Run の同時実行のドキュメントをご覧ください。

Docker イメージにサービス構成が組み込まれていない場合、コールドスタート時に Cloud Run は Google ServiceManagement に対して 2 つの API 呼び出しを行う必要があります。これらの呼び出しは、Google ServiceManagement API の割り当て制限の対象になります。

サービス構成を ESPv2 Docker イメージにビルドすると、この 2 つの API 呼び出しを行う必要がなくなることから、Google ServiceManagement サービスの割り当てカウントに対する影響が生じることを回避できます。また、新しいインスタンスの作成時間も短くなるので、新しいインスタンスを待機するリクエストのレイテンシも少なくなります。

以下の場合に、このステップ全体を再度実行し、新しいコンテナを再度デプロイする必要があります。

Endpoints サービス構成を変更して再デプロイする際。これ以外の場合、サービス構成の変更は ESPv2 には伝播されません。
新しいバージョンの ESPv2 がリリースされる際。これ以外の場合は、以前のバージョンの ESPv2 がデプロイされたままになります。

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

gcloud CLI がインストールされているローカルマシンにこのスクリプトをダウンロードします。
注:
このスクリプトには bash が必要です。macOS または Linux を使用していない場合は、Cloud Shell、Compute Engine、または Windows Subsystem for Linux で実行できます。
次のコマンドでスクリプトを実行します。
```
chmod +x gcloud_build_image

./gcloud_build_image -s CLOUD_RUN_HOSTNAME \
    -c CONFIG_ID -p ESP_PROJECT_ID
```
CLOUD_RUN_HOSTNAME には、Cloud Run ホスト名の予約で予約した URL のホスト名を指定します。プロトコルの識別子である https:// は含めません。

次に例を示します。
```
chmod +x gcloud_build_image

./gcloud_build_image -s gateway-12345-uc.a.run.app \
    -c 2019-02-01r0 -p your-project-id
```
このスクリプトは、gcloud コマンドを使用してサービス構成をダウンロードし、新しい ESPv2 イメージにサービス構成をビルドして、新しいイメージを次のプロジェクトコンテナレジストリにアップロードします。このスクリプトは、出力イメージ名に ESP_VERSION で示される ESPv2 の最新リリースを自動的に使用します。出力イメージは次の場所にアップロードされます。
```
gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID
```
次に例を示します。
```
gcr.io/your-project-id/endpoints-runtime-serverless:2.14.0-gateway-12345-uc.a.run.app-2019-02-01r0"
```
注:
別のレジストリのロケーションにイメージを生成するには、-z フラグをスクリプトに渡します。

たとえば、生成された ESPv2 イメージを Euopean Union のデータセンターに push するには、-z eu をスクリプトに渡します。

ESPv2 コンテナをデプロイする

前の手順で作成した新しいイメージを使用して、ESPv2 Cloud Run サービスをデプロイします。CLOUD_RUN_SERVICE_NAME は、Cloud Run ホスト名の予約で、前の手順でホスト名を予約したときと同じ Cloud Run サービスの名前に置き換えます。
```
gcloud run deploy CLOUD_RUN_SERVICE_NAME \
  --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID" \
  --allow-unauthenticated \
  --platform managed \
  --project=ESP_PROJECT_ID
```
注:
ESPv2 でアクセスを管理する場合は、--allow-unauthenticated フラグを使用して、ESPv2 により JWT トークンを確認します。このフラグを使用しない場合は、Cloud Run のアクセス制御 IAM サーバーによって、JWT トークンがインターセプトおよび検証されます。IAM と ESPv2 は同じ Authorization ヘッダーを使用するため、これらが連携することはありません。どちらか一方のみを使用してください。アクセスの管理には、ESPv2 ではなく IAM を使用することをおすすめします。
CORS を有効にするなどの追加の ESPv2 起動オプションを使用するように Endpoints を構成する場合は、引数を ESPv2_ARGS 環境変数に渡すことができます。
```
gcloud run deploy CLOUD_RUN_SERVICE_NAME \
  --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-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 のフラグをご覧ください。
Service Management と Service Control を呼び出す権限を ESPv2 に付与します。

Google Cloud コンソールで [Cloud Run] ページに移動します。

[Cloud Run] ページに移動

デプロイした Cloud Run インスタンスと、それに関連付けられたサービスアカウントを確認できます。
サービスアカウントに必要な権限を付与します。

gcloud projects add-iam-policy-binding PROJECT_NAME \
       --member "serviceAccount:SERVICE_ACCOUNT" \
       --role roles/servicemanagement.serviceController

ロールと権限について

Cloud Run サービスを呼び出す権限を ESPv2 に付与します。各サービスに対して次のコマンドを実行します。次のコマンドを実行します。
注:
フラグ --service-account を使用せずに ESPv2 Cloud Run サービスをデプロイし、バックエンドサービス BACKEND_SERVICE_NAME を ESP_PROJECT_NUMBER プロジェクトにデプロイする場合、このステップは必要ありません。
- BACKEND_SERVICE_NAME は、呼び出す Cloud Run サービスの名前で置き換えます。クイックスタート: 事前にビルドされたサンプルコンテナのデプロイで作成したバックエンドサービスを使用している場合は、hello をこの値として使用します。
- ESP_PROJECT_NUMBER は、ESPv2 に作成したプロジェクトのプロジェクト番号に置き換えます。この番号を調べる 1 つの方法としては、Google Cloud コンソールの [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
```

詳しくは、IAM を使用したアクセスの管理をご覧ください。

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

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

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 の活動を追跡する

Google Cloud コンソールで [Endpoints] > [サービス] ページに移動して、API のアクティビティグラフを表示します。

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

グラフにリクエストが反映されるまでしばらくかかります。
[ログエクスプローラ] ページで、API のリクエストログを確認します。Endpoints のリクエストログを表示

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

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

クリーンアップ

このページで使用したリソースについて、Google Cloud アカウントに課金されないようにするには、次の手順を行います。

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