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 とクライアント ライブラリを生成するためのツール、ライブラリ、機能で構成されています。

目標

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

1. Google Cloud プロジェクトを設定します。始める前にをご覧ください。
2. 必須ソフトウェアをインストールし、App Engine アプリケーションを作成します。必須ソフトウェアをインストールして構成するをご覧ください。
3. サンプルコードをダウンロードします。サンプルコードを取得するをご覧ください。
4. OpenAPI ドキュメントを生成します。Endpoints を構成するをご覧ください。
5. Endpoints 構成をデプロイして、Endpoints サービスを作成します。Endpoints 構成をデプロイするをご覧ください。
6. パソコンでサンプルを実行します。サンプルをローカルで実行するをご覧ください。
7. API を提供するバックエンドを作成し、API をデプロイします。API バックエンドをデプロイするをご覧ください。
8. API にリクエストを送信します。API にリクエストを送信するをご覧ください。
9. API の活動を追跡します。API の活動を追跡するをご覧ください。
10. Google Cloud アカウントに課金されないようにします。クリーンアップをご覧ください。

費用

このドキュメントでは、課金対象である次の Google Cloudコンポーネントを使用します。

• Endpoints
• App Engine

料金計算ツールを使うと、予想使用量に基づいて費用の見積もりを生成できます。

新規の Google Cloud ユーザーは無料トライアルをご利用いただける場合があります。

このドキュメントに記載されているタスクの完了後、作成したリソースを削除すると、それ以上の請求は発生しません。詳細については、クリーンアップをご覧ください。

始める前に

注: Python 2.7.x がインストールされていることを確認してください。Python 3.x は Endpoints Frameworks ではサポートされていません。

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.

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 (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

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 (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

Verify that billing is enabled for your Google Cloud project.

1. 後で必要になるため、 Google Cloud プロジェクト ID をメモしておきます。

必須ソフトウェアをインストールして構成する

1. Python 用 Google Cloud CLI のインストールの手順に従って、App Engine スタンダード開発環境をセットアップします。app-engine-python と app-engine-python-extras gcloud コンポーネントをインストールします。
2. 次のコマンドを実行します。
   1. gcloud CLI を更新します。

      gcloud components update

   2. Google Cloud CLI（gcloud）が、 Google Cloudにある対象のデータとサービスへのアクセスが許可されていることを確認します。

      gcloud auth login

   3. 表示された新しいブラウザタブで、アカウントを選択します。
   4. デフォルト プロジェクトを実際のプロジェクト ID に設定します。

      gcloud config set project [YOUR_PROJECT_ID]

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

3. サンプル API にリクエストを送信するためのアプリケーションが必要です。

   • Linux ユーザーと MacOS ユーザーの場合: このチュートリアルでは、curl の使用例を示します。これは通常、オペレーティング システムにプリインストールされています。 curl を所有していない場合は、curl のリリースとダウンロードのページからダウンロードできます。
   • Windows ユーザーの場合: このチュートリアルでは、Invoke-WebRequest の使用例を示しています。これは PowerShell 3.0 以降でサポートされています。
4. Python 開発環境に pip が含まれていることを確認します。
5. C 拡張機能を Python 用にコンパイルできることを確認します。
   • Windows: Microsoft Visual C++ 9.0 以上が必要です。Microsoft ダウンロード センターから Microsoft Visual C++ Compiler for Python 2.7 をダウンロードできます。
   • その他のオペレーティング システム: オペレーティング システムによっては、コンパイラ ツール（たとえば、build-essential というパッケージ内）や Python 開発ヘッダー（たとえば、python-dev というパッケージ内）のインストールが必要です。

6. Linux の場合、ENDPOINTS_GAE_SDK 環境変数を App Engine SDK フォルダのパス [Path-to-Google-Cloud-SDK]/platform/google_appengine に設定します。

   [Path-to-Google-Cloud-SDK] は、次のコマンドの出力に置き換えます。

   gcloud info --format="value(installation.sdk_root)"

7. App Engine アプリケーションを作成します。
   1. App Engine アプリケーションを作成するリージョンを選択します。次のコマンドを実行してリージョンのリストを取得します。

      gcloud app regions list

   2. 次のコマンドを使用して App Engine アプリケーションを作成します。[YOUR_PROJECT_ID] は実際の Google Cloudプロジェクト ID に、[YOUR_REGION] は App Engine アプリケーションを作成するリージョンに置き換えます。

      gcloud app create \
      --project=[YOUR_PROJECT_ID] \
      --region=[YOUR_REGION]

      次に例を示します。

      gcloud app create --project=example-project-12345 --region=us-central

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

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 のリクエストログを確認します。

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

クリーンアップ

このチュートリアルで使用したリソースについて、Google Cloud アカウントに課金されないようにするには、リソースを含むプロジェクトを削除するか、プロジェクトを維持して個々のリソースを削除します。

注意: プロジェクトを削除すると、次のような影響があります。
• プロジェクト内のすべてのものが削除されます。このドキュメントのタスクで既存のプロジェクトを使用した場合、それを削除すると、そのプロジェクトで行った他の作業もすべて削除されます。
• カスタム プロジェクト ID が失われます。このプロジェクトを作成したときに、将来使用するカスタム プロジェクト ID を作成した可能性があります。そのプロジェクト ID を使用した URL（たとえば、appspot.com）を保持するには、プロジェクト全体ではなくプロジェクト内の選択したリソースだけを削除します。
1. In the Google Cloud console, go to the Manage resources page.

   Go to Manage resources

2. In the project list, select the project that you want to delete, and then click Delete.
3. In the dialog, type the project ID, and then click Shut down to delete the project.

次のステップ

• Endpoints Frameworks のアーキテクチャについて学習する。
• API の作成方法を学習する。
• API を提供するウェブサーバーの作成方法を学習する。
• 別のパスから API を提供する方法について学習する。
• API のモニタリングについて学習する。
• API キーを使用したアクセスの制限について学習する。
• カスタム ドメイン名の構成について学習する。
• API のバージョニングについて学習する。
• サポート オプションについて学習する。