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

---

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

目標

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

1. Google Cloud プロジェクトを設定します。始める前にをご覧ください。
2. 必須ソフトウェアをインストールし、App Engine アプリケーションを作成します。必須ソフトウェアをインストールして構成するをご覧ください。
3. サンプルコードをダウンロードします。サンプルコードを取得するをご覧ください。
4. OpenAPI 構成ファイルを生成します。Cloud 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 ユーザーは無料トライアルをご利用いただける場合があります。

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

始める前に

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

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

   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

3. Make sure that billing is enabled for your Google Cloud project.

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

   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

5. Make sure that billing is enabled for your Google Cloud project.

6. プロジェクト ID をメモします。この ID は、後のステップで使用します。

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

1. Java 8 をインストールしていない場合は、Oracle から Java Development Kit（JDK）をダウンロードしてインストールします。Endpoints Frameworks for Java は App Engine 標準 Java 8 ランタイム環境に依存するため、Endpoints Frameworks ではその他のバージョンの Java はサポートされていません。
2. Maven 3.3.9 以降がインストールされていない場合には、ダウンロードしてインストールします。

Windows ユーザーへの注: Windows で JDK と Maven をインストールする場合、パスにスペースが含まれていないディレクトリにインストールしてください。詳しくは、Windows での Maven をご覧ください。

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

   • Linux ユーザーと MacOS ユーザーの場合: このチュートリアルでは、curl の使用例を示します。これは通常、オペレーティング システムにプリインストールされています。 curl を所有していない場合は、curl のリリースとダウンロードのページからダウンロードできます。
   • Windows ユーザーの場合: このチュートリアルでは、Invoke-WebRequest の使用例を示しています。これは PowerShell 3.0 以降でサポートされています。
4. Google Cloud CLI をダウンロードして初期化します。
5. 次のコマンドを実行します。
   1. gcloud CLI が、Google Cloud にある対象のデータとサービスにアクセスできるよう許可されていることを確認します。

      gcloud auth login

   2. 次のアプリケーションのデフォルト認証情報を使用します。

      gcloud auth application-default login

   3. Google Cloud SDK app-engine-java のコンポーネントをインストールします。

      gcloud components install app-engine-java

   4. Google Cloud SDK とすべてのコンポーネントを最新バージョンに更新します。

      gcloud components update

6. App Engine アプリケーションを作成します。
   1. プロジェクト ID にデフォルト プロジェクトを設定します。

      gcloud config set project YOUR_PROJECT_ID

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

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

      gcloud app regions list

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

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

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

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

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

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

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

   cd java-docs-samples/appengine-java8/endpoints-v2-backend
   

Endpoints を構成する

サンプルコードに含まれている Endpoints Frameworks ツールは、サンプルコードの REST API を記述する OpenAPI 構成ファイルを生成します。このセクションの手順に従って、サンプル Maven プロジェクトを構成してビルドし、OpenAPI 構成ファイルを生成できるようにします。

サンプル API コードへのプロジェクト ID の追加

コードをデプロイするには、その前に、プロジェクトを作成したときに入手したプロジェクト ID をサンプルの pom.xml に追加しておく必要があります。

プロジェクト ID を追加するには:

1. java-docs-samples/appengine-java8/endpoints-v2-backend/pom.xml ファイルを編集します。

2. <endpoints.project.id> を検索します。YOUR_PROJECT_ID は、実際の Google Cloud プロジェクト ID で置き換えます。

   例:

   <endpoints.project.id>example-project</endpoints.project.id>
   

3. 変更を保存します。

サンプル プロジェクトのビルド

プロジェクトをビルドするには:

1. java-docs-samples/appengine-java8/endpoints-v2-backend ディレクトリ内にいることを確認します。

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

   mvn clean package
   

3. プロジェクトがビルドされるのを待ちます。プロジェクトが正常に終了すると、それを知らせる次のようなメッセージが表示されます。

   [INFO] BUILD SUCCESS
   [INFO] ------------------------------------------------------------------------
   [INFO] Total time: 14.846s
   [INFO] Finished at: Wed April 13 09:43:09 PDT 2016
   [INFO] Final Memory: 24M/331M
   

OpenAPI 構成ファイルを生成する

Endpoints Frameworks ライブラリのツールを使用して、openapi.json という名前の OpenAPI ドキュメントを生成します。このファイルには、サンプルコードの REST API が記述されています。

OpenAPI 構成ファイルを生成するには:

1. 次のコマンドを使用して、Endpoints Frameworks ツールを起動します。

   mvn endpoints-framework:openApiDocs
   

2. 構成仕様がビルドされるのを待ちます。完了すると、以下のようなメッセージが表示されます。

   OpenAPI document written to target/openapi-docs/openapi.json
   

   静的ロガークラスの読み込みの失敗に関するメッセージは無視してください。

Endpoints 構成をデプロイする

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

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

1. java-docs-samples/appengine-java8/endpoints-v2-backend ディレクトリ内にいることを確認します。

2. 前のセクションで生成した OpenAPI 構成ファイルをデプロイします。

   gcloud endpoints services deploy target/openapi-docs/openapi.json
   

これにより、新しい Endpoints サービスが作成され、YOUR_PROJECT_ID.appspot.com という形式の名前が付けられます。この名前は、pom.xml と、サンプルに含まれる他の構成ファイルに追加されます。App Engine に API をデプロイすると、YOUR_PROJECT_ID.appspot.com という形式の名前で DNS レコードが作成されます。これは、API にリクエストを送信するときに使用する完全修飾ドメイン名（FQDN）です。

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

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

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

詳細については、gcloudEndpoints サービス デプロイをご覧ください。

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

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

名前	タイトル
servicemanagement.googleapis.com	Service Management API
servicecontrol.googleapis.com	Service Control API
endpoints.googleapis.com	Google Cloud Endpoints

ほとんどの場合、gcloud endpoints services deploy コマンドによってこれらの必須サービスが有効化されます。ただし、以下の状況では、gcloud コマンドは正常に完了しますが、必須サービスが有効になりません。

• Terraform などのサードパーティのアプリケーションを使用していて、上記のサービスを含めていない場合。

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

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

gcloud services list

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

gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com
gcloud services enable endpoints.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. ENDPOINTS_SERVICE_NAME という環境変数を作成します。この環境変数は、サンプルの appengine-web.xml ファイルでホスト名を設定するために使用されます。以下では、YOUR_PROJECT_ID を実際の Google Cloud プロジェクト ID に置き換えます。

   Linux または Mac OS の場合:

   export ENDPOINTS_SERVICE_NAME=YOUR_PROJECT_ID.appspot.com
   

   Windows PowerShell の場合:

   $Env:ENDPOINTS_SERVICE_NAME="YOUR_PROJECT_ID.appspot.com"
   

2. アプリケーションのデフォルト認証情報として使用する新しいユーザー認証情報を取得します。

   gcloud auth application-default login
   

3. 開発用サーバーを実行します。

   mvn appengine:run
   

   ローカル インスタンスには http://localhost:8080 でアクセスでき、このことは mvn appengine:run コマンドが出力したログに示されています。

   [INFO] GCLOUD: INFO: Module instance default is running at http://localhost:8080/
   

4. ローカル インスタンスにリクエストを送信します。

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. java-docs-samples/appengine-java8/endpoints-v2-backend ディレクトリ内にいることを確認します。

2. Maven を使用して、API 実装コードをデプロイします。

    mvn appengine:deploy
   

   サンプル アプリケーションを初めてアップロードするとき、デプロイを承認するよう求められます。画面の指示に従います。ブラウザ ウィンドウが開いてコードが表示されたら、そのコードをターミナル ウィンドウにコピーします。

3. アップロードが完了するまで待ちます。

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

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

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"
}

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

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

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

API の活動を追跡する

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

   [Endpoints] の [サービス] ページに移動

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

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

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

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

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

クリーンアップ

このチュートリアルで使用したリソースについて、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 のバージョニングについて学習する。
• コミュニティ サポート オプションについて学習する。