App Engine フレキシブル環境での Cloud Endpoints のスタートガイド

{% include "_shared/_delete_tutorial_resources.html" with name="Getting started with Cloud Endpoints on the App Engine flexible environment" %}

このチュートリアルでは、サンプル API と Extensible Service Proxy(ESP)App Engine フレキシブル環境内のインスタンスで実行するように構成してデプロイする方法を説明します。サンプルコードの REST API は、OpenAPI 仕様を使用して作成されています。このチュートリアルでは、API キーを作成して API に対するリクエストで使用する方法も説明します。

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

目標

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

  1. Google Cloud Platform(GCP)プロジェクトをセットアップして、必要なソフトウェアをインストールし、App Engine アプリを作成します。始める前にをご覧ください。
  2. サンプルコードをダウンロードします。サンプルコードを取得するをご覧ください。
  3. Endpoints の構成に使用する openapi-appengine.yaml ファイルを構成します。Endpoints を構成するをご覧ください。
  4. Endpoints 構成をデプロイして、Endpoints サービスを作成します。Endpoints 構成をデプロイするをご覧ください。
  5. API と ESP を App Engine にデプロイします。API バックエンドをデプロイするをご覧ください。
  6. API にリクエストを送信します。API にリクエストを送信するをご覧ください。
  7. API の活動を追跡します。API の活動を追跡するをご覧ください。
  8. GCP アカウントに課金されないようにします。クリーンアップをご覧ください。

料金

このチュートリアルでは、以下の課金対象の Google Cloud Platform コンポーネントを使用します。

料金計算ツールを使用して、予測される使用量に基づき、費用の見積もりを出すことができます。 GCP を初めてご利用の場合は、無料トライアルをご利用いただけます。

このチュートリアルを終了した後、作成したリソースを削除すると、それ以上の請求は発生しません。詳しくは、クリーンアップをご覧ください。

始める前に

  1. Google アカウントにログインします。

    Google アカウントをまだお持ちでない場合は、新しいアカウントを登録します。

  2. GCP プロジェクトを選択または作成します。

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

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

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

  4. 後で必要になるので、プロジェクト ID をメモしておきます。
  5. サンプル API にリクエストを送信するためのアプリケーションが必要です。

    • Linux ユーザーと macOS ユーザー: このチュートリアルでは、curl の使用例を示します。これは通常、オペレーティング システムにプリインストールされていますが、curl をお持ちでない場合は、curlリリースとダウンロードのページからダウンロードできます。
    • Windows ユーザー: このチュートリアルでは、Invoke-WebRequest の使用例を示しています。これは PowerShell 3.0 以降でサポートされています。
  6. Cloud SDK をダウンロードします
  7. Cloud SDK を更新し、Endpoints コンポーネントをインストールします。
    gcloud components update
  8. Cloud SDK(gcloud)が GCP にある対象のデータとサービスにアクセスできるよう許可されていることを確認します。
    gcloud auth login
    表示された新しいブラウザタブで、アカウントを選択します。
  9. ご使用のプロジェクト ID をデフォルト プロジェクトとして設定します。
    gcloud config set project YOUR_PROJECT_ID

    YOUR_PROJECT_ID は、実際のプロジェクト ID で置き換えます。他にも GCP プロジェクトがあり、gcloud を使用してそのプロジェクトを管理する場合は、Cloud SDK 構成の管理をご覧ください。

  10. App Engine アプリケーションを作成するリージョンを選択します。次のコマンドを実行してリージョンのリストを取得します。
    gcloud app regions list
  11. App Engine アプリケーションを作成します。YOUR_PROJECT_ID は実際の GCP プロジェクト ID に、YOUR_REGION は App Engine アプリケーションを作成するリージョンに置き換えます。
      gcloud app create \
      --project=YOUR_PROJECT_ID \
      --region=YOUR_REGION
    

サンプルコードの取得

Java

サンプル API のクローンを作成するか、ダウンロードするには:

  1. サンプルコードでは Maven を使用しています。Maven 3.3.9 以降がインストールされていない場合には、ダウンロードしてインストールします。
  2. ローカルマシンにサンプルアプリのリポジトリのクローンを作成します。
    git clone https://github.com/GoogleCloudPlatform/java-docs-samples

    または、zip ファイルとしてサンプルをダウンロードし、ファイルを解凍します。

  3. サンプルコードが含まれているディレクトリに移動します。
    cd java-docs-samples/endpoints/getting-started
Python

サンプル API のクローンを作成するか、ダウンロードするには:

  1. ローカルマシンにサンプルアプリのリポジトリのクローンを作成します。
    git clone https://github.com/GoogleCloudPlatform/python-docs-samples

    または、zip ファイルとしてサンプルをダウンロードし、ファイルを解凍します。

  2. サンプルコードが含まれているディレクトリに移動します。
    cd python-docs-samples/endpoints/getting-started
Go

サンプル API のクローンを作成するか、ダウンロードするには:

  1. GOPATH 環境変数が設定されていることを確認します。
  2. ローカルマシンにサンプルアプリのリポジトリのクローンを作成します。
    go get -u -d github.com/GoogleCloudPlatform/golang-samples/endpoints/getting-started
  3. サンプルコードが含まれているディレクトリに移動します。
    cd $GOPATH/src/github.com/GoogleCloudPlatform/golang-samples/endpoints/getting-started
PHP

サンプル API のクローンを作成するか、ダウンロードするには:

  1. ローカルマシンにサンプルアプリのリポジトリのクローンを作成します。
    git clone https://github.com/GoogleCloudPlatform/php-docs-samples

    または、zip ファイルとしてサンプルをダウンロードし、ファイルを解凍します。

  2. サンプルコードが含まれているディレクトリに移動します。
    cd php-docs-samples/endpoints/getting-started
Ruby

サンプル API のクローンを作成するか、ダウンロードするには:

  1. ローカルマシンにサンプルアプリのリポジトリのクローンを作成します。
    git clone https://github.com/GoogleCloudPlatform/ruby-docs-samples

    または、zip ファイルとしてサンプルをダウンロードし、ファイルを解凍します。

  2. サンプルコードが含まれているディレクトリに移動します。
    cd ruby-docs-samples/endpoints/getting-started
NodeJS

サンプル API のクローンを作成するか、ダウンロードするには:

  1. ローカルマシンにサンプルアプリのリポジトリのクローンを作成します。
    git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples

    または、zip ファイルとしてサンプルをダウンロードし、ファイルを解凍します。

  2. サンプルコードが含まれているディレクトリに移動します。
    cd nodejs-docs-samples/endpoints/getting-started

Endpoints を構成する

サンプルコードには、OpenAPI 構成ファイル openapi-appengine.yaml が含まれています。このファイルは OpenAPI 仕様 v2.0 に準拠しています。

Endpoints を構成するには:
  1. サンプルコードのディレクトリで openapi-appengine.yaml 構成ファイルを開きます。

    次の点にご注意ください。

    • この構成サンプルでは、host フィールドの近辺に表示されている行を変更する必要があります。openapi-appengine.yaml を Endpoints にデプロイするには、完全な OpenAPI ドキュメントが必要です。
    • サンプル openapi-appengine.yaml ファイルには、このチュートリアルでは不要な認証を構成するためのセクションが含まれています。YOUR-SERVICE-ACCOUNT-EMAILYOUR-CLIENT-ID の行を構成する必要はありません。
    • OpenAPI は言語に依存しない仕様です。利便性を考慮し、各言語の GitHub リポジトリの getting-started サンプル内に、同じ openapi-appengine.yaml ファイルが用意されています。
  2. host フィールドが含まれる行で、YOUR-PROJECT-ID を実際の GCP プロジェクト ID に置き換えます。次に例を示します。
    host: "example-project-12345.appspot.com"
    

Endpoints は、host フィールドのテキストをサービス名として使用します。App Engine バックエンドに API をデプロイすると、YOUR-PROJECT-ID.appspot.com 形式の名前を持つ DNS エントリが自動的に作成されます。

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

Endpoints 構成をデプロイする

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

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

  1. endpoints/getting-started ディレクトリ内にいることを確認します。
  2. 構成をアップロードしてマネージド サービスを作成します。
    gcloud endpoints services deploy openapi-appengine.yaml
    

その後で、gcloud コマンドが Service Management API を呼び出して、openapi-appengine.yaml ファイルの host フィールドで指定された名前でマネージド サービスを作成します。Service Management は、openapi-appengine.yaml ファイル内の設定に従ってサービスを構成します。openapi-appengine.yaml に変更を加えるときは、このファイルを再デプロイして Endpoints サービスを更新する必要があります。

Service Management でサービスの作成と構成が行われるとき、情報がターミナルに出力されます。openapi-appengine.yaml ファイル内のパスが API キーを要求していない、という警告は無視できます。サービスの構成が完了すると、サービス構成 ID とサービス名を含む次のようなメッセージが Service Management に表示されます。

Service Configuration [2017-02-13r0] uploaded for service [example-project-12345.appspot.com]

上記の例では、2017-02-13r0 がサービス構成 ID で、example-project-12345.appspot.com が Endpoints サービスです。サービス構成 ID は、日付スタンプとそれに続くリビジョン番号で構成されます。openapi-appengine.yaml ファイルを同じ日に再デプロイすると、サービス構成 ID のリビジョン番号が大きくなります。Endpoints サービス構成は、GCP 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 などのサードパーティ製アプリケーションを使用していて、上記のサービスを含めていない場合。

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

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

gcloud services list

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

gcloud services enable SERVICE_NAME

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

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

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

ここまでの手順で OpenAPI ドキュメントを Service Management にデプロイしましたが、API バックエンドを処理するコードはまだデプロイしていません。ここでは、サンプル API と ESP を App Engine にデプロイします。

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

  1. app.yaml ファイルにサービス名を追加します。

    Java

    endpoints/getting-started/src/main/appengine/app.yaml ファイルを開きます。

    endpoints_api_service:
      # The following values are to be replaced by information from the output of
      # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
      name: ENDPOINTS-SERVICE-NAME
      rollout_strategy: managed

    Python

    endpoints/getting-started/app.yaml ファイルを開きます。

    endpoints_api_service:
      # The following values are to be replaced by information from the output of
      # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
      name: ENDPOINTS-SERVICE-NAME
      rollout_strategy: managed

    Go

    endpoints/getting-started/app.yaml ファイルを開きます。

    endpoints_api_service:
      # The following values are to be replaced by information from the output of
      # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
      name: ENDPOINTS-SERVICE-NAME
      rollout_strategy: managed

    PHP

    endpoints/getting-started/app.yaml ファイルを開きます。

    endpoints_api_service:
      # The following values are to be replaced by information from the output of
      # 'gcloud endpoints services deploy openapi-appengine.yaml' command. If you have
      # previously run the deploy command, you can list your existing configuration
      # ids using the 'configs list' command as follows:
      #
      #     gcloud endpoints configs list --service=YOUR-PROJECT-ID.appspot.com
      #
      name: ENDPOINTS-SERVICE-NAME
      rollout_strategy: managed

    Ruby

    endpoints/getting-started/app.yaml ファイルを開きます。

    endpoints_api_service:
      # The following values are to be replaced by information from the output of
      # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
      name: ENDPOINTS-SERVICE-NAME
      rollout_strategy: managed

    NodeJS

    endpoints/getting-started/app.yaml ファイルを開きます。

    endpoints_api_service:
      # The following values are to be replaced by information from the output of
      # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
      name: ENDPOINTS-SERVICE-NAME
      rollout_strategy: managed

    ENDPOINTS-SERVICE-NAME は、Endpoints サービスの名前に置き換えます。これは、OpenAPI ドキュメントの host フィールドで構成した名前と同じです。次に例を示します。

    endpoints_api_service:
      name: example-project-12345.appspot.com
      rollout_strategy: managed
    

    rollout_strategy: managed オプションは、ESP がデプロイ済みの最新のサービス構成を使用するように構成します。このオプションを指定すると、新しいサービス構成をデプロイしてから 1 分以内に ESP が変更を検出し、自動的に使用します。ESP が特定の構成 ID でなく、このオプションを使用するように指定することをおすすめします。

  2. app.yaml ファイルを保存します。
  3. endpoints_api_service セクションを app.yaml ファイルに追加したので、gcloud app deploy コマンドは ESP を App Engine フレキシブル環境の別のコンテナにデプロイして構成します。すべてのリクエスト トラフィックは ESP 経由でルーティングされ、ESP はバックエンド サーバーコードを実行するコンテナとの間でリクエストとレスポンスの送受信を行います。

  4. endpoints/getting-started ディレクトリ内にいることを確認します。ここに openapi-appengine.yaml 構成ファイルがあります。
  5. 次のコマンドを実行して、サンプル API と ESP を App Engine にデプロイします。
  6. Java

    Maven を使用してデプロイします。

    mvn appengine:stage
    gcloud app deploy target/appengine-staging
    
    Python
    gcloud app deploy
    Go
    gcloud app deploy
    PHP
    gcloud app deploy
    Ruby
    gcloud app deploy
    NodeJS
    gcloud app deploy

    gcloud app deploy コマンドは、YOUR_PROJECT_ID.appspot.com という形式の DNS レコードを作成します。このレコードは、API にリクエストを送信するときに使われます。App Engine が完全に初期化されるまで数分待ってから、API にリクエストを送信することをおすすめします。

エラー メッセージが表示された場合は、App Engine フレキシブル環境でのデプロイのトラブルシューティングをご覧ください。

詳しくは、API バックエンドをデプロイするをご覧ください。

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

サービスが App Engine 上で実行されていますので、それにリクエストを送信できます。

API キーを作成し、環境変数を設定する

サンプルコードには API キーが必要です。リクエストを簡単にするために、API キーの環境変数を設定します。

  1. API に使用したのと同じ GCP プロジェクトの API 認証情報ページで API キーを作成します。別の GCP プロジェクトで API キーを作成するには、GCP プロジェクトでの API の有効化をご覧ください。

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

  2. [認証情報を作成] をクリックして [API キー] を選択します。
  3. キーをクリップボードにコピーします。
  4. [閉じる] をクリックします。
  5. ローカル コンピュータで、API キーを貼り付けて環境変数に割り当てます。
    • Linux または Mac OS の場合: export ENDPOINTS_KEY=AIza...
    • Windows PowerShell の場合: $Env:ENDPOINTS_KEY="AIza..."

リクエストを送信する

Linux または Mac OS

  1. App Engine プロジェクト URL の環境変数を作成します。YOUR_PROJECT_ID は実際の GCP プロジェクト ID に置き換えてください。

    export ENDPOINTS_HOST=https://YOUR_PROJECT_ID.appspot.com

  2. 設定済みの ENDPOINTS_HOST 環境変数と ENDPOINTS_KEY 環境変数を使用して、HTTP リクエストを送信します。

    curl --request POST \
        --header "content-type:application/json" \
        --data '{"message":"hello world"}' \
        "${ENDPOINTS_HOST}/echo?key=${ENDPOINTS_KEY}"
    

上記の curl の各要素の内容は次のとおりです。

  • --data オプションは、API に送信するデータを指定します。
  • --header オプションは、データが JSON 形式であることを指定します。

PowerShell

  1. App Engine プロジェクト URL の環境変数を作成します。YOUR_PROJECT_ID は実際の GCP プロジェクト ID に置き換えてください。

    $Env:ENDPOINTS_HOST="https://YOUR_PROJECT_ID.appspot.com"

  2. 設定済みの ENDPOINTS_HOST 環境変数と ENDPOINTS_KEY 環境変数を使用して、HTTP リクエストを送信します。

    (Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
        -Headers @{"content-type"="application/json"} `
        -URI "$Env:ENDPOINTS_HOST/echo?key=$Env:ENDPOINTS_KEY").Content
    

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

サードパーティ製アプリ

Chrome ブラウザの拡張機能である Postman などのサードパーティ製アプリケーションを使用してリクエストを送信できます。

  • HTTP 動詞として POST を選択します。
  • ヘッダーで、キー content-type と値 application/json を選択します。
  • 本文で、次のように入力します。
    {"message":"hello world"}
  • URL では、環境変数ではなく実際の appspot.com アドレスと API キーを使用します。例:
    https://example-project-12345.appspot.com/echo?key=AIza...

API によって送信メッセージがエコーバックされ、次のようなレスポンスが返されます。

{
  "message": "hello world"
}

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

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

API の活動を追跡する

  1. [エンドポイント] ページで API のアクティビティ グラフを確認します。

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

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

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

    ログビューア ページに移動

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

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

クリーンアップ

このチュートリアルで使用するリソースについて、Google Cloud Platform アカウントに課金されないようにする手順は次のとおりです。

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

次のステップ

このページは役立ちましたか?評価をお願いいたします。

フィードバックを送信...

OpenAPI を使用した Cloud Endpoints
ご不明な点がありましたら、Google のサポートページをご覧ください。