Cloud Endpoints によって管理される API をデプロイする

Cloud Endpoints によって管理される API をデプロイする

このクイックスタートでは、Cloud Endpoints で管理するサンプル API をデプロイする手順について説明します。サンプルコードには次のものが含まれています。

• 3 文字の IATA コードから空港名を照会するための REST API。
• API 構成を Endpoints にアップロードするためのスクリプト。
• サンプル API をホストする App Engine フレキシブル環境バックエンドをデプロイするためのスクリプト。

リクエストをサンプル API に送信した後、 コンソールで Google Cloud Endpoints のアクティビティ グラフと Google Cloud Observability のログを確認できます。これらのツールによって API をモニタリングし、使用状況に関する分析情報を得ることができます。

このクイックスタートでは、スクリプトを使用して構成手順を簡素化し、アクティビティ グラフとログの動作をすばやく確認できます。サンプル API の構成とデプロイの方法については、API フレームワークのいずれかのチュートリアルを選択してください。

• Cloud Endpoints for OpenAPI: チュートリアル
• Cloud Endpoints for gRPC: チュートリアル
• Cloud Endpoints Frameworks: チュートリアル

始める前に

アカウントにログインします。 Google Cloud を初めて使用する場合は、 アカウントを作成して、実際のシナリオで Google プロダクトのパフォーマンスを評価してください。 Google Cloud新規のお客様には、ワークロードの実行、テスト、デプロイができる無料クレジット $300 分を差し上げます。

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.

Verify 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.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.

Verify that billing is enabled for your Google Cloud project.

必要なロール

API のデプロイと管理に必要な権限を取得するには、プロジェクトに対する次の IAM ロールを付与するよう管理者に依頼してください。

• Endpoints 構成をデプロイする: Service Management 管理者 （roles/servicemanagement.admin）
• 必要なサービスを有効にする: Service Usage 管理者 (roles/serviceusage.serviceUsageAdmin)
• App Engine アプリケーションを作成する: App Engine Creator (roles/appengine.appCreator)
• サンプル API を App Engine にデプロイする:
  • App Engine デプロイ担当者 （roles/appengine.deployer）
  • Cloud Build 編集者 (roles/cloudbuild.builds.editor)
  • Storage オブジェクト ユーザー （roles/storage.objectUser）
  • サービス アカウント ユーザー （roles/iam.serviceAccountUser）

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

必要な権限は、カスタム ロールや他の事前定義 ロールから取得することもできます。

Cloud Shell の起動

1. コンソールで、サンプル API に使用するプロジェクトを表示していることを確認します。 Google Cloud

2. Cloud Shell を開く

   Cloud Shell を開く

   コンソールの一番下にある新しいフレーム内に Cloud Shell セッションが開き、コマンドライン プロンプトが表示されます。Google Cloud セッションが初期化されるまで数秒かかることがあります。

   

3. 既存のプロジェクトを使用している場合は、インストールされているすべての gcloud コンポーネントが最新バージョンになっていることを確認します。

   gcloud components update
   

注: Linux または macOS マシンを使用していて、ローカルシェルを使用してこの クイックスタートの手順に従う場合は、 Google Cloud CLI をダウンロードした後、ローカルのコマンドライン インターフェースを使用してこの クイックスタートの手順を実行してください。

サンプルコードの取得

1. Cloud Shell で次のコマンドを入力して、サンプル API とスクリプトを取得します。

git clone https://github.com/GoogleCloudPlatform/endpoints-quickstart

1. サンプルコードが入っているディレクトリに移動します。

cd endpoints-quickstart

Endpoints 構成をデプロイする

Endpoints に REST API を公開するには、API を記述している OpenAPI 構成ファイルが必要です。サンプル API には、事前に構成された OpenAPI ファイル（openapi.yaml）が付属しています。

Endpoints では、 Google Cloud のインフラストラクチャ サービスである Service Management を使用して、API とサービスの作成と管理を行います。Endpoints を使用して API を管理するには、API の OpenAPI 構成ファイルを Service Management にデプロイします。

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

1. Cloud Shell の endpoints-quickstart ディレクトリで、次のように入力します。

cd scripts

1. サンプルに含まれている次のスクリプトを実行します。

./deploy_api.sh

Endpoints では、OpenAPI 構成ファイルの host フィールドを使用して、サービスを識別します。deploy_api.sh スクリプトは、 Google Cloud プロジェクトの ID を host フィールドで構成された名前の一部として設定します。 独自サービス用の OpenAPI 構成ファイルを準備する際には、この処理を手動で行う必要があります。

その後、スクリプト内の gcloud endpoints services deploy openapi.yaml コマンドによって、OpenAPI 構成が Service Management にデプロイされます。

Service Management でサービスの作成と構成が行われる際に、 情報が Google Cloud コンソールに出力されます。openapi.yaml 内のパスが API キーを要求していないことを示す警告は無視して構いません。正常に完了すると、サービス構成 ID とサービス名を示す次のような行が表示されます。

    Service Configuration [2017-02-13-r2] uploaded for service [airports-api.endpoints.example-project.cloud.goog]

必要なサービスを有効にする

Endpoints では、少なくとも次の Google サービスを有効にする必要があります。

名前	タイトル
servicecontrol.googleapis.com	Service Control API
servicemanagement.googleapis.com	Service Management API

ほとんどの場合、Endpoints 構成をデプロイすると、これらの必須サービスが有効になります。

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

gcloud services list

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

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

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

gcloud services enable YOUR-PROJECT-ID.appspot.com

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

API バックエンドをデプロイする

ここまでの手順で OpenAPI 構成を Service Management にデプロイしましたが、API バックエンドを提供するためのコードはまだデプロイしていません。サンプルに含まれている deploy_app.sh スクリプトでは、API バックエンドをホストする App Engine フレキシブル環境を作成し、API を App Engine にデプロイします。

API バックエンドをデプロイするには:

• Cloud Shell の endpoints-quickstart/scripts ディレクトリで、次のスクリプトを実行します。

./deploy_app.sh

このスクリプトは、gcloud app create --region="$REGION" コマンドを実行して、us-central リージョンに App Engine フレキシブル環境を作成します。

App Engine フレキシブル環境バックエンドが作成されるまでには数分かかります。アプリケーションが作成されると、次のように出力されます。

Success! The app is now created.

次に、gcloud app deploy コマンドを実行して、サンプル API を App Engine にデプロイします。

次のように出力されます。

Deploying ../app/app_template.yaml...You are about to deploy the following services:

API を App Engine にデプロイするのに数分かかります。API が App Engine に正常にデプロイされると、次のように出力されます。

Deployed service [default] to [https://example-project.appspot.com]

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

• Cloud Shell で、サンプル API をデプロイした後、次のスクリプトを実行することにより、リクエストを送信できます。

./query_api.sh

このスクリプトでは、API にリクエストを送信するために使用される curl コマンドがエコーされ、その結果が表示されます。次のように出力されます。

curl "https://example-project.appspot.com/airportName?iataCode=SFO"
San Francisco International Airport

API には、SEA や JFK などの有効な IATA 空港コードを設定した 1 つのクエリ パラメータ iataCode を渡します。例:

./query_api.sh JFK

注: App Engine がリクエストにレスポンスするまで数分かかる場合があります。リクエストを送信して HTTP 502、503 または他のサーバーエラーが返された場合には、1 分ほど待ってからもう一度リクエストしてください。

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

注: このチュートリアルについてのご感想やご要望がありましたら、このページの下部からフィードバックをお送りください。いただいたフィードバックは、チュートリアルの品質向上に利用させていただきます。
エラーが発生した場合は、google-cloud-endpoints Google グループに参加して、どのような問題が生じたかをお知らせください。このグループに参加すると、他の Endpoints ユーザーや、このグループをモニタリングしている Google エンジニアから回答を受け取ることができます。

API の活動を追跡する

デプロイされた API を Endpoints で利用すると、コンソールで重要な オペレーション指標をモニタリングし、Cloud Logging によってユーザーと使用状況に関する分析情報を得ることができます。 Google Cloud

1. Cloud Shell で、トラフィック生成スクリプトを実行して、グラフとログにデータが入力されるようにします。

./generate_traffic.sh

Note: This script generates requests in a loop and automatically times out
in 5 minutes. To end the script sooner, enter `Control+C` in
Cloud Shell.

1. コンソールで、API のアクティビティ グラフを確認します。 Google Cloud

   [エンドポイント] の [サービス] ページに移動

   リクエストがグラフに反映されるまでしばらく時間がかかることがあります。データが表示されるまでの間に、次の操作を行うことが可能です。

   • [権限] サイドパネルが開いていない場合は、[+ 権限] をクリックします。[権限] パネルを使用して、API にアクセスできるユーザーとアクセスレベルを制御できます。

   • [デプロイの履歴] をクリックします。このタブには、デプロイ時間や変更のデプロイ担当者など、API のデプロイ履歴が表示されます。

   • [概要] をクリックします。受信トラフィックが表示されます。トラフィック生成スクリプトを 1 分間実行すると、合計レイテンシ グラフに 3 行（50 パーセンタイル値、95 パーセンタイル値、98 パーセンタイル値）が表示されます。このデータからレスポンス時間を推定できます。

2. グラフの下の [**リンク**] で、 [**GET/airportName**] の [**ログを表示**] をクリックします。[ログ エクスプローラ] ページに API のリクエストログが表示されます。

3. Cloud Shell を開きます。

   Cloud Shell を開く

4. スクリプトを停止するには、Control+C を押します。

API に割り当てを追加する

ベータ版

この機能は サービス固有規約の「一般サービス規約」セクションの「一般提供前サービス規約」の対象となります 。pre-GA の機能は「現状のまま」で提供されるものであり、サポートが制限されることがあります。 詳細については、 リリース ステージの説明をご覧ください。

Endpoints を使用すると、アプリケーションが API を呼び出せるペースを制御するための割り当てを設定できます。割り当てを使用することにより、単一のクライアントによる過度の使用から API を保護できます。

1. Cloud Shell で、割り当てがある Endpoints 構成をデプロイします。

./deploy_api.sh ../openapi_with_ratelimit.yaml

After you deploy an updated Endpoints configuration, it
becomes active within a minute.

1. コンソールで、[認証情報] ページに移動します。 Google Cloud

   [認証情報] ページに移動

2. [認証情報を作成] をクリックし、[API キー] をクリックします。新しい API キーが画面に表示されます。

3. [コピー] をクリックします。

4. Cloud Shell で、次のように入力します。YOUR_API_KEY は、先ほど作成した API キーに置き換えます。

export API_KEY=YOUR_API_KEY

1. 生成された API キーを使用して API にリクエストを送信します。

./query_api_with_key.sh $API_KEY

The output is similar to the following:

curl -H 'x-api-key: AIzeSyDbdQdaSdhPMdiAuddd_FALbY7JevoMzAB' "https://example-project.appspot.com/airportName?iataCode=SFO"
San Francisco International Airport

1. これで、API は 1 分あたりのリクエスト数が 5 に制限されました。次のコマンドを実行して、トラフィックを API に送信し、割り当て制限をトリガーします。

./generate_traffic_with_key.sh $API_KEY

1. このスクリプトを 5～10 秒間実行した後、Control+C キーを押してスクリプトを停止します。

2. 別の認証済みリクエストを API に送信します。

./query_api_with_key.sh $API_KEY

The output is similar to the following:

{
    "code": 8,
    "message": "Insufficient tokens for quota 'airport_requests' and limit 'limit-on-airport-requests' of service 'example-project.appspot.com' for consumer     'api_key:AIzeSyDbdQdaSdhPMdiAuddd_FALbY7JevoMzAB'.",
    "details": [
    {
    "@type": "type.googleapis.com/google.rpc.DebugInfo",
    "stackEntries": [],
    "detail": "internal"
    }
    ]
}

レスポンスが異なる場合は、generate_traffic_with_key.sh スクリプトをもう一度実行してから、再試行してください。

これで完了です。これで、API のレート制限を正しく設定できました。API メソッドごとに異なる制限を設定したり、複数種類の割り当てを作成したり、どのユーザーがどの API を使用しているかを追跡したりすることもできます。

詳細については、 割り当てについてをご覧ください。

クリーンアップ

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

課金されないようにするには、プロジェクトを削除することで、プロジェクト内のすべてのリソースに対する課金を停止できます。 Google Cloud

注意 : プロジェクトを削除すると、次の影響があります。
• プロジェクト内のすべてのものが削除されます。既存のプロジェクトを使用してこのドキュメントのタスクを行った場合、そのプロジェクトを削除すると、プロジェクト内で行った他の作業もすべて削除されます。
• カスタム プロジェクト ID が失われます。このプロジェクトを作成したときに、将来使用するカスタム プロジェクト ID を作成した可能性があります。そのプロジェクト ID を使用した URL（例: appspot.com URL）を保持するには、プロジェクト全体ではなく、プロジェクト内の選択したリソースだけを削除します。
1. コンソールで [**リソースの管理**] ページに移動します。 Google Cloud

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

2. プロジェクト リストで、削除するプロジェクトを選択し、[削除] をクリックします。
3. ダイアログでプロジェクト ID を入力し、 [Shut down] をクリックしてプロジェクトを削除します。

次のステップ

• Endpoints の概要については以下をご覧ください。

  • Endpoints について
  • Endpoints: アーキテクチャの概要

• Endpoints でサポートされている各種 API フレームワークについては以下をご覧ください。

  • OpenAPI 仕様
  • Endpoints for gRPC の API
  • Endpoints Frameworks について

• サンプル API の構成とデプロイの方法については、API フレームワークのいずれかのチュートリアルを選択してください。

  • Endpoints for OpenAPI: チュートリアル
  • Endpoints for gRPC: チュートリアル
  • Endpoints Frameworks: チュートリアル