このチュートリアルでは、Compute Engine 上に事前にビルドされた Docker コンテナ内で稼働するサンプル API と Extensible Service Proxy V2(ESPv2)を構成してデプロイする方法について説明します。
サンプルコードの REST API は、OpenAPI 仕様に従って作成されています。このチュートリアルでは、API キーを作成して API へのリクエストで使用する方法も説明します。
Cloud Endpoints の概要については、Endpoints についてと Endpoints アーキテクチャをご覧ください。
目標
タスクの概要を示す次のリストを参照しながら、チュートリアルを実施してください。API にリクエストを送信するには、すべてのタスクを行う必要があります。- Google Cloud プロジェクトを設定します。始める前にをご覧ください。
- Compute Engine VM インスタンスを作成します。Compute Engine のインスタンスを作成するをご覧ください。
- サンプルコードをダウンロードします。サンプルコードを取得するをご覧ください。
- Endpoints の構成に使用する
openapi.yaml
ファイルを構成します。Endpoints を構成するをご覧ください。 - Endpoints 構成をデプロイして Endpoints サービスを作成します。Endpoints 構成をデプロイするをご覧ください。
- API と ESPv2 を Compute Engine VM でデプロイします。API バックエンドをデプロイするをご覧ください。
- IP アドレスを使用して API にリクエストを送信します。IP アドレスを使用してリクエストを送信するをご覧ください。
- サンプル API の DNS レコードを構成します。Endpoints の DNS を構成するをご覧ください。
- 完全修飾ドメイン名を使用して API にリクエストを送信します。FQDN を使用してリクエストを送信するをご覧ください。
- API のアクティビティを追跡します。API の活動を追跡するをご覧ください。
- Google Cloud アカウントへの課金が発生しないようにします。クリーンアップをご覧ください。
費用
このドキュメントでは、Google Cloud の次の課金対象のコンポーネントを使用します。
料金計算ツールを使うと、予想使用量に基づいて費用の見積もりを生成できます。
このドキュメントに記載されているタスクの完了後、作成したリソースを削除すると、それ以上の請求は発生しません。詳細については、クリーンアップをご覧ください。
始める前に
- Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
- 後で必要になるため、プロジェクト ID をメモしておきます。
-
サンプル API にリクエストを送信するためのアプリケーションが必要です。
- Linux ユーザーと MacOS ユーザーの場合: このチュートリアルでは、
curl
の使用例を示します。これは通常、オペレーティング システムにプリインストールされています。curl
を所有していない場合は、curl
のリリースとダウンロードのページからダウンロードできます。 - Windows ユーザーの場合: このチュートリアルでは、
Invoke-WebRequest
の使用例を示しています。これは PowerShell 3.0 以降でサポートされています。
- Linux ユーザーと MacOS ユーザーの場合: このチュートリアルでは、
- Google Cloud CLI をダウンロードします。
-
gcloud CLI を更新し、Endpoints コンポーネントをインストールします。
gcloud components update
-
Google Cloud CLI(
gcloud
)が、Google Cloud にある対象のデータとサービスへのアクセスが許可されていることを確認します。 表示された新しいブラウザタブで、アカウントを選択します。gcloud auth login
-
デフォルト プロジェクトを実際のプロジェクト ID に設定します。
gcloud config set project YOUR_PROJECT_ID
YOUR_PROJECT_ID を実際のプロジェクト ID に置き換えます。他にも Google Cloud プロジェクトがあり、
gcloud
を使用してそのプロジェクトを管理する場合は、gcloud CLI 構成の管理をご覧ください。
このドキュメントに記載されているタスクの完了後、作成したリソースを削除すると、それ以上の請求は発生しません。詳細については、クリーンアップをご覧ください。
Compute Engine インスタンスの作成
- In the Google Cloud console, go to the Create an instance page.
- [ファイアウォール] で、 [HTTP トラフィックを許可する] と [HTTPS トラフィックを許可する] を選択します。
- VM を作成するには、[作成] をクリックします。
- VM インスタンスに接続できることを確認します。
- In the list of virtual machine instances, click SSH in the row of the instance that you want to connect to.
- これで、ターミナルを使用して Debian インスタンスで Linux コマンドを実行できるようになりました。
- インスタンスとの接続を切断するには、「
exit
」と入力します。
- 後で必要となるため、インスタンス名、ゾーン、外部 IP アドレスをメモします。
Compute Engine のインスタンスを作成するには:
インスタンスが起動するまで、しばらくお待ちください。準備が完了すると、[VM インスタンス] ページに緑色のステータス アイコン付きで表示されます。
サンプルコードをダウンロードする
サンプルコードをローカルマシンにダウンロードします。
サンプル API をクローニングまたはダウンロードするには:
- ローカルマシンにサンプルアプリのリポジトリのクローンを作成します。
git clone https://github.com/GoogleCloudPlatform/java-docs-samples
または、zip ファイルとしてサンプルをダウンロードし、ファイルを解凍します。
- サンプルコードが含まれているディレクトリに移動します。
cd java-docs-samples/endpoints/getting-started
サンプル API をクローニングまたはダウンロードするには:
- ローカルマシンにサンプルアプリのリポジトリのクローンを作成します。
git clone https://github.com/GoogleCloudPlatform/python-docs-samples
または、zip ファイルとしてサンプルをダウンロードし、ファイルを解凍します。
- サンプルコードが含まれているディレクトリに移動します。
cd python-docs-samples/endpoints/getting-started
サンプル API をクローニングまたはダウンロードするには:
GOPATH
環境変数が設定されていることを確認します。- ローカルマシンにサンプルアプリのリポジトリのクローンを作成します。
go get -d github.com/GoogleCloudPlatform/golang-samples/endpoints/getting-started
- サンプルコードが含まれているディレクトリに移動します。
cd $GOPATH/src/github.com/GoogleCloudPlatform/golang-samples/endpoints/getting-started
サンプル API をクローニングまたはダウンロードするには:
- ローカルマシンにサンプルアプリのリポジトリのクローンを作成します。
git clone https://github.com/GoogleCloudPlatform/php-docs-samples
または、zip ファイルとしてサンプルをダウンロードし、ファイルを解凍します。
- サンプルコードが含まれているディレクトリに移動します。
cd php-docs-samples/endpoints/getting-started
サンプル API をクローニングまたはダウンロードするには:
- ローカルマシンにサンプルアプリのリポジトリのクローンを作成します。
git clone https://github.com/GoogleCloudPlatform/ruby-docs-samples
または、zip ファイルとしてサンプルをダウンロードし、ファイルを解凍します。
- サンプルコードが含まれているディレクトリに移動します。
cd ruby-docs-samples/endpoints/getting-started
サンプル API をクローニングまたはダウンロードするには:
- ローカルマシンにサンプルアプリのリポジトリのクローンを作成します。
git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples
または、zip ファイルとしてサンプルをダウンロードし、ファイルを解凍します。
- サンプルコードが含まれているディレクトリに移動します。
cd nodejs-docs-samples/endpoints/getting-started
Endpoints を構成する
サンプルコードには、OpenAPI 構成ファイル openapi.yaml
が含まれています。このファイルは OpenAPI 仕様 v2.0 に準拠しています。openapi.yaml
の構成とデプロイをローカルマシンで実行します。
Endpoints を設定するには:
- サンプルコードのディレクトリで、
openapi.yaml
構成ファイルを開きます。Java Python Go PHP Ruby Node.js 次の点にご注意ください。
- 上記の構成サンプルでは
host
フィールドの近辺に表示されている行を変更する必要があります。openapi.yaml
ファイルを Endpoints にデプロイするには、完全な OpenAPI ドキュメントが必要です。 - サンプル
openapi.yaml
ファイルには、このチュートリアルでは不要な認証を構成するためのセクションが含まれています。YOUR-SERVICE-ACCOUNT-EMAIL と YOUR-CLIENT-ID の行を構成する必要はありません。 - OpenAPI は言語に依存しない仕様です。利便性を考慮し、各言語の GitHub リポジトリで、同じ
openapi.yaml
ファイルがgetting-started
サンプル内に用意されています。
- 上記の構成サンプルでは
host
フィールドで、テキストを次の形式の Endpoints サービス名に置き換えます。host: "echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog"
YOUR_PROJECT_ID を Google Cloud プロジェクト ID に置き換えます。次に例を示します。
host: "echo-api.endpoints.example-project-12345.cloud.goog"
この echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog
は Endpoints サービスの名前です。これは、API にリクエストを送信するために使用する完全修飾ドメイン名(FQDN)ではありません。
Endpoints に必要な OpenAPI ドキュメントのフィールドについては、Endpoints を構成するをご覧ください。
次の構成手順をすべて完了し、IP アドレスを使用してサンプル API にリクエストを正常に送信できるようになったら、Endpoints の DNS を構成するを参照して、echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog
を FQDN として構成する方法をご確認ください。
Endpoints 構成をデプロイする
Endpoints の構成をデプロイするには、gcloud endpoints
services deploy
コマンドを使用します。このコマンドを実行すると、Service Management を使用してマネージド サービスが作成されます。
Endpoints 構成をデプロイするには:
endpoints/getting-started
ディレクトリ内にいることを確認します。- 構成をアップロードしてマネージド サービスを作成します。
gcloud endpoints services deploy openapi.yaml
gcloud
コマンドが Service Management API を呼び出して、openapi.yaml
ファイルの host
フィールドで指定した名前のマネージド サービスを作成します。Service Management は、openapi.yaml
ファイル内の設定に従ってサービスを構成します。openapi.yaml
に変更を加えるときは、このファイルを再デプロイして Endpoints サービスを更新する必要があります。
Service Management でサービスの作成と構成が行われるとき、情報がターミナルに出力されます。openapi.yaml
ファイル内のパスが API キーを要求していないことを示す警告は無視して問題ありません。サービスの構成が完了すると、Service Management に、次のようなサービス構成 ID とサービス名を含むメッセージが表示されます。
Service Configuration [2017-02-13r0] uploaded for service [echo-api.endpoints.example-project-12345.cloud.goog]
上記の例では、2017-02-13r0
はサービス構成 ID、echo-api.endpoints.example-project-12345.cloud.goog
は Endpoints サービスです。サービス構成 ID は、日付スタンプとそれに続くリビジョン番号で構成されます。同じ日に openapi.yaml
ファイルを再度デプロイすると、サービス構成 ID のリビジョン番号が増分されます。Endpoints のサービス構成は、Google Cloud コンソールの [Endpoints] > [サービス] ページで確認できます。
エラー メッセージが表示された場合は、Endpoints 構成のデプロイのトラブルシューティングをご覧ください。
必要なサービスの確認
Endpoints と ESP を使用するには、少なくとも次の Google サービスの有効化が必要です。名前 | タイトル |
---|---|
servicemanagement.googleapis.com |
Service Management API |
servicecontrol.googleapis.com |
Service Control API |
ほとんどの場合、gcloud endpoints services deploy
コマンドによってこれらの必須サービスが有効化されます。ただし、以下の状況では、gcloud
コマンドは正常に完了しますが、必須サービスが有効になりません。
Terraform などのサードパーティのアプリケーションを使用していて、上記のサービスを含めていない場合。
上記のサービスが明示的に無効にされている既存の Google Cloud プロジェクトに Endpoints 構成をデプロイした場合。
必要なサービスが有効になっていることを確認するには、次のコマンドを実行します。
gcloud services list
必要なサービスが表示されない場合は、次のコマンドを使用してサービスを有効にします。
gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.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
サービスをご覧ください。
API バックエンドをデプロイする
ここまでの手順で OpenAPI ドキュメントを Service Management にデプロイしましたが、API バックエンドを処理するコードはまだデプロイしていません。このセクションでは、VM インスタンスで Docker を設定し、Docker コンテナで API バックエンド コードと ESPv2 を実行する方法について説明します。
必要な権限を確認する
- Google Cloud コンソールで、[Compute Engine インスタンス] ページに移動します。
- インスタンスをリストから選択します。
- 関連するサービス アカウントと与えられている権限を確認できます。
サービス アカウントに必要な権限を付与します。
gcloud projects add-iam-policy-binding PROJECT_NAME \ --member "serviceAccount:SERVICE_ACCOUNT" \ --role roles/servicemanagement.serviceController
詳細については、ロールと権限についてをご覧ください。
VM インスタンスに Docker をインストールする
Docker を VM インスタンスにインストールするには:
- 次のコマンドを実行して、プロジェクトのゾーンを設定します。
gcloud config set compute/zone YOUR_INSTANCE_ZONE
YOUR_INSTANCE_ZONE は、インスタンスが実行されているゾーンに置き換えます。
- 次のコマンドを使用して、インスタンスに接続します。
gcloud compute ssh INSTANCE_NAME
INSTANCE_NAME は、VM インスタンス名に置き換えます。
- Docker のドキュメントを参照して Docker リポジトリを設定します。VM インスタンスの該当するバージョンとアーキテクチャ用の手順に従ってください。
- Jessie 以降
- x86_64 / amd64
Docker コンテナで API と ESPv2 を実行する
ESPv2 は、ユーザーのバックエンド コードの前にある Envoy
ベースのプロキシです。受信トラフィックを処理し、認証、API キー管理、ロギングなどの Endpoints の API 管理機能を提供します。
サンプル API と ESPv2 を Docker コンテナにインストールして実行するには:
esp_net
という独自のコンテナ ネットワークを作成します。sudo docker network create --driver bridge esp_net
- サンプル API を提供するサンプルの Echo サーバーを実行します。
Java sudo docker run --detach --name=echo --net=esp_net gcr.io/google-samples/echo-java:1.0
Python sudo docker run --detach --name=echo --net=esp_net gcr.io/google-samples/echo-python:1.0
Go sudo docker run --detach --name=echo --net=esp_net gcr.io/google-samples/echo-go:1.0
PHP sudo docker run --detach --name=echo --net=esp_net gcr.io/google-samples/echo-php:1.0
Ruby sudo docker run --detach --name=echo --net=esp_net gcr.io/google-samples/echo-ruby:1.0
NodeJS sudo docker run --detach --name=echo --net=esp_net gcr.io/google-samples/echo-node:1.0
- あらかじめパッケージ化されたパブリック ESPv2 Docker コンテナを実行します。ESPv2 スタートアップ オプションで、SERVICE_NAME を実際のサービスの名前に置き換えます。これは、OpenAPI ドキュメントの
host
フィールドで構成した名前と同じです。sudo docker run \ --detach \ --name=esp \ --publish=80:9000 \ --net=esp_net \ gcr.io/endpoints-release/endpoints-runtime:2 \ --service=SERVICE_NAME \ --rollout_strategy=managed \ --listener_port=9000 \ --backend=http://echo:8080
--rollout_strategy=managed
オプションを指定すると、デプロイ済みの最新のサービス構成を使用するように ESPv2 が構成されます。このオプションを指定すると、新しいサービス構成をデプロイしてから 1 分以内に ESPv2 が変更を検出し、自動的に使用します。ESPv2 が特定の構成 ID でなく、このオプションを使用するようにしてください。上記以外の他の ESPv2 オプションについては、ESPv2 スタートアップ オプションをご覧ください。
エラー メッセージが表示された場合は、Compute Engine の Endpoints をトラブルシューティングするをご覧ください。 詳細については、API バックエンドをデプロイするご覧ください。
IP アドレスを使用してリクエストを送信する
サンプル API と ESPv2 が Compute Engine インスタンスで実行されたら、ローカルマシンから API にリクエストを送信できます。
API キーを作成し、環境変数を設定する
サンプルコードには API キーが必要です。リクエストを簡単にするために、API キーの環境変数を設定します。
API に使用したものと同じ Google Cloud プロジェクトの API 認証情報ページで API キーを作成します。別の Google Cloud プロジェクトで API キーを作成するには、Google Cloud プロジェクトでの API の有効化をご覧ください。
- [認証情報を作成] をクリックして [API キー] を選択します。
- キーをクリップボードにコピーします。
- [閉じる] をクリックします。
- ローカルマシンで、API キーを貼り付けて環境変数に割り当てます。
- Linux または Mac OS の場合:
export ENDPOINTS_KEY=AIza...
- Windows PowerShell の場合:
$Env:ENDPOINTS_KEY="AIza..."
- Linux または Mac OS の場合:
リクエストを送信する
Linux または Mac OS
前の手順で設定した ENDPOINTS_KEY 環境変数を使用して、curl
を使用して HTTP リクエストを送信します。IP_ADDRESS をインスタンスの外部 IP アドレスに置き換えます。
curl --request POST \ --header "content-type:application/json" \ --data '{"message":"hello world"}' \ "http://IP_ADDRESS:80/echo?key=${ENDPOINTS_KEY}"
上記の curl
で:
--data
オプションは、API に送信するデータを指定します。--header
オプションは、データが JSON 形式であることを指定します。
PowerShell
前の手順で設定した ENDPOINTS_KEY
環境変数を使用して、Invoke-WebRequest
により HTTP リクエストを送信します。IP_ADDRESS をインスタンスの外部 IP アドレスに置き換えます。
(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' ` -Headers @{"content-type"="application/json"} ` -URI "http://IP_ADDRESS:80/echo?key=$Env:ENDPOINTS_KEY").Content
上記の例では、最初の 2 行はバッククォートで終わります。この例を PowerShell に貼り付けるとき、バッククォートの後にスペースがないことを確認してください。このリクエスト例で使用されているオプションについては、Microsoft のドキュメントの Invoke-WebRequest をご覧ください。
サードパーティ製アプリ
Chrome ブラウザの拡張機能である Postman などのサードパーティのアプリケーションを使用してリクエストを送信できます。
- HTTP 動詞として
POST
を選択します。 - ヘッダーで、キー
content-type
とその値application/json
を選択します。 - 本文で、次のように入力します。
{"message":"hello world"}
-
URL で、環境変数ではなく実際の API キーを使用します。
例:
http://192.0.2.0:80/echo?key=AIza...
API によって送信メッセージがエコーバックされ、次のようなレスポンスが返されます。
{
"message": "hello world"
}
正常なレスポンスが返されなかった場合は、レスポンス エラーのトラブルシューティングをご覧ください。
これで Endpoints の API のデプロイとテストが完了しました。
Endpoints の DNS を構成する
API の Endpoints サービス名は .endpoints.YOUR_PROJECT_ID.cloud.goog
ドメイン中にあるため、openapi.yaml
ファイルの構成を少し変更することで、完全修飾ドメイン名(FQDN)として使用できます。このようにすると、サンプル API にリクエストを送信するときに IP アドレスの代わりに echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog
を使用できます。
Endpoints DNS を構成するには:
- OpenAPI 構成ファイルである
openapi.yaml
を開き、次のスニペットに示すように、ファイルの最上位レベルにx-google-endpoints
プロパティを追加(インデントまたはネストさせずに)します。host: "echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog" x-google-endpoints: - name: "echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog" target: "IP_ADDRESS"
name
プロパティで、YOUR_PROJECT_ID を実際のプロジェクト ID で置き換えます。target
プロパティで、IP_ADDRESS をサンプル API にリクエストを送信する際に使用した IP アドレスで置き換えます。- 更新した OpenAPI 構成ファイルを Service Management にデプロイします。
gcloud endpoints services deploy openapi.yaml
たとえば、openapi.yaml
ファイルは次のように構成されていると仮定します。
host: "echo-api.endpoints.example-project-12345.cloud.goog" x-google-endpoints: - name: "echo-api.endpoints.example-project-12345.cloud.goog" target: "192.0.2.1"
前述の gcloud
コマンドで openapi.yaml
ファイルをデプロイすると、Service Management はターゲット IP アドレス 192.0.2.1
に解決される DNS A レコード echo-api.endpoints.my-project-id.cloud.goog
を作成します。新しい DNS 構成が反映されるまでに数分かかる場合があります。
SSL を設定する
DNS と SSL の構成方法の詳細については、Endpoints で SSL を有効にするをご覧ください。
FQDN を使用してリクエストを送信する
サンプル API の DNS レコードが構成されたところで、FQDN(YOUR_PROJECT_ID は実際のプロジェクト ID で置き換えます)と設定済みの ENDPOINTS_KEY 環境変数を使用してサンプル API にリクエストを送信します。- Linux または Mac OS の場合:
curl --request POST \ --header "content-type:application/json" \ --data '{"message":"hello world"}' \ "http://echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog:80/echo?key=${ENDPOINTS_KEY}"
- Windows PowerShell の場合:
(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' -Headers @{"content-type"="application/json"} -URI "http://echo-api.endpoints.[YOUR_PROJECT_ID].cloud.goog:80/echo?key=$Env:ENDPOINTS_KEY").Content
API のアクティビティを追跡する
API の活動を追跡するには:
- [エンドポイント] > [サービス] ページで API のアクティビティ グラフを確認します。
グラフにリクエストが反映されるまでに、しばらく時間がかかる場合があります。 - [ログ エクスプローラ] ページで、API のリクエストログを確認します。
API のデベロッパー ポータルを作成する
Cloud Endpoints Portal を使用してデベロッパー ポータルを作成できます。デベロッパー ポータルとは、サンプル API の操作に使用できるウェブサイトです。詳細については、Cloud Endpoints Portal の概要をご覧ください。
クリーンアップ
このチュートリアルで使用したリソースについて、Google Cloud アカウントに課金されないようにするには、リソースを含むプロジェクトを削除するか、プロジェクトを維持して個々のリソースを削除します。
- API を削除します。
gcloud endpoints services delete SERVICE_NAME
SERVICE_NAME
は、実際のサービス名に置き換えます。 - In the Google Cloud console, go to the VM instances page.
- Select the checkbox for the instance that you want to delete.
- To delete the instance, click More actions, click Delete, and then follow the instructions.