Cloud Endpoints Frameworks for Python スタートガイド

ここでは、Cloud Endpoints Frameworks for Python を使用してサンプル API を構成、デプロイし、サンプル API にリクエストを送信する方法を説明します。Endpoints Frameworks for Python は App Engine 標準 Python 2.7 ランタイム環境と統合されています。Endpoints Frameworks は、App Engine アプリケーションから API とクライアント ライブラリを生成するためのツール、ライブラリ、機能で構成されています。

サンプルコードの取得

GitHub からサンプル API のクローンを作成するには:

1. ローカルマシンにサンプル リポジトリのクローンを作成します。

   git clone https://github.com/GoogleCloudPlatform/python-docs-samples
   

2. サンプルコードを含むディレクトリに変更します。

   cd python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo
   

Endpoints を構成する

Endpoints を構成する場合は、先に Endpoints Frameworks Python ライブラリをインストールしておく必要があります。その後、Endpoints Frameworks ライブラリのツールを使用してサンプル API 用の OpenAPI ドキュメントを生成します。Endpoints で API を管理するには、Endpoints Frameworks ライブラリと OpenAPI ドキュメントが必要です。詳しくは、API 管理の追加をご覧ください。

Endpoints Frameworks ライブラリをインストールする

ここでは、Python の pip を使用して Endpoints Frameworks ライブラリをサンプル API のプロジェクト ディレクトリに追加する手順を説明します。

注: 仮想環境で Python を実行しないでください。Endpoints Framework パッケージは、パソコンのプロジェクト ディレクトリ内の lib サブディレクトリにインストールする必要があります。

Endpoints Frameworks ライブラリをサンプルに追加するには、次のようにします。

1. サンプル API のメイン ディレクトリ python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo にいることを確認します。

2. プロジェクトに /lib サブディレクトリを作成します。

   mkdir lib
   

3. サンプルのメイン ディレクトリ python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo から、インストール コマンドを実行します。

   pip install --target lib --requirement requirements.txt --ignore-installed
   

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

   • この pip コマンドでは、GNU Compiler Collection（GCC）を使用して拡張モジュールをコンパイルできます。macOS を使用していて、現在のシステムで初めて GCC を実行する場合は、Apple の XCode ライセンスへの同意が必要になる場合があります。そのためには、sudo xcodebuild -license を実行します。

   • パソコンに複数の Python バージョンがインストールされている場合は、このチュートリアルで使用している Python のバージョンに対応する pip のバージョンを使用します。バージョンの不一致（Pyton 2.7 の python を使用している場合に、Pyton 3.4 の pip など) によって、理解できないエラーが発生することがあります。必要に応じて、pip を Python モジュールとして実行できます。その場合、上記のコマンドの pip を python -m pip に置き換えてください。

   • コマンドの実行時に pip が適切なパッケージを見つけられない場合は、pip install --upgrade pip を実行してアップグレードしてください。アップグレードが完了したら、インストール コマンドをもう一度試します。

   • Debian と Ubuntu の一部のリリースでは、DistutilsOptionError が発生し、pip が失敗する可能性があります。このエラーが発生した場合は、--system フラグを追加します。

正常に完了すると、lib ディレクトリには Endpoints Frameworks アプリケーションのビルドに必要なファイルが含まれます。

OpenAPI ドキュメントを生成する

Endpoints Frameworks ライブラリからツールを使用して、サンプルコードの REST API について記述するドキュメントを生成します。

OpenAPI ドキュメントを生成するには:

1. サンプルのメイン ディレクトリにいることを確認します。

   python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo
   

2. OpenAPI ドキュメントを生成します。

   python lib/endpoints/endpointscfg.py get_openapi_spec main.EchoApi --hostname [YOUR_PROJECT_ID].appspot.com
   

   [YOUR_PROJECT_ID] は、実際の Google Cloud プロジェクト ID に置き換えます。表示される警告は無視してください。Endpoints ツールは、現在のディレクトリに echov1openapi.json という OpenAPI ドキュメントを生成します。Endpoints ツールは、@endpoints.api デコレータに指定されているサービスの名前とバージョンに基づいてファイルの名前を付けます。詳しくは、API の作成をご覧ください。

   Endpoints は hostname 引数で指定されたテキストをサービス名として使用します。YOUR_PROJECT_ID.appspot.com の名前形式は、App Engine バックエンドに API をデプロイしたときに自動的に作成される DNS エントリと一致します。この例では、Endpoints サービス名と完全修飾ドメイン名（FQDN）は同じになります。

正常に完了すると、次のメッセージが表示されます。OpenAPI spec written to ./echov1openapi.json

Endpoints 構成をデプロイする

Endpoints 構成をデプロイするには、Service Infrastructure を使用します。これは Google の基礎的なサービス プラットフォームであり、Endpoints やその他のサービスで API やサービスの作成と管理に使用されています。

構成ファイルをデプロイするには:

1. サンプルのメイン ディレクトリにいることを確認します。

   python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo
   

2. 次のコマンドを実行して、前のセクションで生成した OpenAPI ドキュメントをデプロイします。

   gcloud endpoints services deploy echov1openapi.json

   これにより、Endpoints ツールを実行して、OpenAPI ドキュメントを生成したときに、hostname 引数で指定した名前で新しい Endpoints サービスが作成されます。Endpoints サービス名に関係なく、App Engine に API をデプロイすると、名前形式 YOUR_PROJECT_ID.appspot.com を使用して、DNS レコードが作成されます。これは、API にリクエストを送信するときに使用する FQDN です。

   Service Management でサービスの作成と構成が行われるとき、多くの情報がデバイスに出力されます。echov1openapi.json 内のパスが API キーを要求していないことを示す警告は無視して問題ありません。デプロイが完了すると、次のようなメッセージが表示されます。

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

   上の例では、2017-02-13-r2 がサービス構成 ID で、example-project-12345.appspot.com がサービス名です。

   gcloud 参照ドキュメントの gcloud endpoints services deploy をご覧ください。

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

API 管理を行うために、Endpoints Frameworks には以下のサービスが必要となります。

名前	タイトル
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 サービスをご覧ください。

サンプルのローカルでの実行

Endpoints 構成をデプロイしたら、ローカルの開発用サーバーを使用してサンプルをローカルで実行できます。

1. サンプルのメイン ディレクトリにいることを確認します。

   python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo
   

2. ローカルの開発用サーバーを起動します。

   dev_appserver.py ./app.yaml
   

   デフォルトで、開発用サーバーは、dev_appserver.py によって出力された Google Cloud コンソールログに示されているとおりに、http://localhost:8080 でリッスンします。

   INFO 2018-01-01 [...] Starting module "default" running at: http://localhost:8080
   

3. ローカルの開発用サーバーにリクエストを送信します。

Linux または Mac OS

curl \
    --request POST \
    --header "Content-Type: application/json" \
    --data '{"message":"hello world"}' \
    http://localhost:8080/_ah/api/echo/v1/echo

上記の curl で:

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

PowerShell

(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
    -Headers @{"content-type"="application/json"} `
    -URI "http://localhost:8080/_ah/api/echo/v1/echo").Content

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

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

{
 "message": "hello world"
}

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

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

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

1. 次のコマンドを実行してサービス構成 ID を表示します。

   gcloud endpoints configs list --service=[YOUR_PROJECT_ID].appspot.com

   [YOUR_PROJECT_ID] は、次のように実際のプロジェクト ID に置き換えます。

   gcloud endpoints configs list --service=example-project-12345.appspot.com
   
   

2. Open the app.yaml file in the python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo directory.

   env_variables:
     # The following values are to be replaced by information from the output of
     # 'gcloud endpoints services deploy swagger.json' command.
     ENDPOINTS_SERVICE_NAME: YOUR-PROJECT-ID.appspot.com
     ENDPOINTS_SERVICE_VERSION: 2016-08-01r0

env_variables セクションで次のように変更します。

• ENDPOINTS_SERVICE_NAME フィールドで、YOUR-PROJECT-ID を実際の Google Cloud プロジェクト ID に置き換えます。
• ENDPOINTS_SERVICE_VERSION フィールドで、テキストをサービス構成 ID に置き換えます。次に例を示します。

  ENDPOINTS_SERVICE_NAME: example-project-12345.appspot.com
  ENDPOINTS_SERVICE_VERSION: 2017-02-13r2

次のコマンドを実行します。

gcloud app deploy

画面上の指示に従います。デプロイが成功するまで数分待ちます。警告メッセージは無視します。デプロイが完了すると、次のようなメッセージが表示されます。

File upload done.
Updating service [default]...done.

エラー メッセージが表示された場合は、App Engine のドキュメントのトラブルシューティング セクションを参照してください。

App Engine が完全に初期化される間、API にリクエストを送信するまで数分待つことをおすすめします。

サンプル API にリクエストを送信する

Linux または Mac OS

curl を使用して HTTP リクエストを送信します。[YOUR_PROJECT_ID] は、実際のGoogle Cloud プロジェクト ID に置き換えます。

curl \
    --request POST \
    --header "Content-Type: application/json" \
    --data '{"message":"hello world"}' \
    https://[YOUR_PROJECT_ID].appspot.com/_ah/api/echo/v1/echo

上記の curl で:

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

PowerShell

Invoke-WebRequest を使用して HTTP リクエストを送信します。[YOUR_PROJECT_ID] は、実際の Google Cloud プロジェクト ID に置き換えます。

(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
    -Headers @{"content-type"="application/json"} -URI `
     "https://[YOUR_PROJECT_ID].appspot.com/_ah/api/echo/v1/echo").Content

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

サードパーティ製アプリ

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

• HTTP 動詞として POST を選択します。
• ヘッダーで、キー content-type とその値 application/json を選択します。
• 本文で、次のように入力します。
  {"message":"hello world"}
• サンプル アプリケーションの URL を入力します。例:
  https://example-project-12345.appspot.com/_ah/api/echo/v1/echo

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

{
 "message": "hello world"
}

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

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

API の活動を追跡する

1. Google Cloud コンソールの [エンドポイント] > [サービス] ページで、API のアクティビティ グラフを確認します。

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

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

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

   [ログ エクスプローラ] ページに移動