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

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

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

ほとんどの場合、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. 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 コンソールの [エンドポイント] > [サービス] ページで、API のアクティビティ グラフを確認します。

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

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

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

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

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

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