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

サンプルコードを取得する

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 のプロジェクト ディレクトリに追加する手順を説明します。

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 をご覧ください。

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

ほとんどの場合、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. ローカルの開発用サーバーにリクエストを送信します。

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

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

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