Endpoints 構成をデプロイする

OpenAPI | gRPC

OpenAPI ドキュメントでの Cloud Endpoints の構成が完了した後で、この構成をデプロイすると、API を管理するために必要な情報が Cloud Endpoints に送られます。Endpoints の構成をデプロイするには、gcloud endpoints services deploy コマンドを使用します。このコマンドは、Google の基礎的なサービスプラットフォームである Service Infrastructure を使用します。このプラットフォームは、Endpoints やその他のサービスで API やサービスを作成、管理するために使用されます。このページでは、OpenAPI ドキュメントを Endpoints にデプロイする方法について説明します。

前提条件

このページの説明は、次のことを前提としています。

自分が編集者またはオーナーのロールを持つ Google Cloud プロジェクトを作成済みであること。最初のデプロイ後に、ユーザー、グループ、サービスアカウントに対してより制限の厳しい Service Config 編集者のロールを付与できます。詳細については、API へのアクセス権の付与と取り消しをご覧ください。
Endpoints を構成済みであること。
カスタムドメイン名（my-api.example.com など）を使用する場合は、ドメイン名を確認する必要があります。これが完了すると、OpenAPI ドキュメントをデプロイできます。

Google Cloud CLI のデプロイの準備

gcloud コマンドラインツールを使用して構成をデプロイします。コマンドの詳細については、gcloud リファレンスをご覧ください。

デプロイの準備を行うには:

gcloud CLI をインストールして初期化する
gcloud CLI を更新します。
```
gcloud components update
```
gcloud CLI がデータやサービスにアクセスできるように承認されていることを確認します。
```
gcloud auth login
```
新しいブラウザタブが開き、アカウントの選択を求めるプロンプトが表示されます。
デフォルトプロジェクトを設定します。[YOUR-PROJECT-ID] を実際の GCP プロジェクト ID に置き換えます。
```
gcloud config set project [YOUR-PROJECT-ID]
```
API バックエンドを Kubernetes または Kubernetes Engine のいずれかにデプロイする場合は、次のコマンドを実行して、アプリケーションのデフォルト認証情報として使用する新しいユーザー認証情報を取得します。ユーザー認証情報は kubectl を承認するために必要です。
```
gcloud auth application-default login
```
新しいブラウザタブが開き、アカウントの選択を要求するプロンプトが表示されます。

`openapi.json` 構文を検証する

OpenAPI ドキュメントファイルの形式は YAML または JSON です。JSON 形式の場合は、ファイルをデプロイする前に構文を検証することをおすすめします。openapi.json が正しい形式の JSON ファイルであることを確認するには、JSON の検証に対応したテキストエディタ（vim など）でファイルを開くか、オンライン JSON リンターサービスを使用するか、または Python を使用します。次に例を示します。

python -m json.tool openapi.json

出力結果を読みやすくするため、JSON ファイルを pretty-print で出力できます。

python -m json.tool input.json > output.json

input.json は、openapi.json ファイルのパスで置き換えます。output.json は、pretty-print 形式の JSON ファイルです。

OpenAPI ドキュメントを検証する

現時点で、すべての OpenAPI コンストラクトが Cloud Endpoints でサポートされているわけではありません。OpenAPI ドキュメントをデプロイする前にドキュメントを検証できます。

OpenAPI ドキュメントを検証するには:

OpenAPI ドキュメントが格納されている場所へディレクトリを変更します。
サービスを作成する Google Cloud プロジェクトを確認します。カスタムドメイン名（myapi.example.com など）を使用する場合は、次のコマンドで返されるプロジェクト ID を検証して、サービスが誤ったプロジェクトに作成されないようにします。
```
gcloud config list project
```
デフォルトプロジェクトを変更する必要がある場合は、次のコマンドを実行します。このとき [YOUR_PROJECT_ID] を、サービスを作成する Google Cloud プロジェクトの ID に置き換えます。
```
gcloud config set project [YOUR_PROJECT_ID]
```
次のコマンドを実行します。このとき [YOUR_OPENAPI_DOCUMENT] を、API が記述されている OpenAPI ドキュメントの名前に置き換えます。
```
gcloud endpoints services deploy [YOUR_OPENAPI_DOCUMENT] --validate-only
```

gcloud コマンドは Service Management API を呼び出し、OpenAPI ドキュメントの host フィールドに指定した名前でマネージドサービスを作成します。--validate-only フラグを指定した場合もサービスは作成されますが、構成はデプロイされません。サービスを作成しないで OpenAPI ドキュメントを検証することはできません。サービスを削除することはできますが、約 30 日間、Service Management で同じ名前のサービスを作成できなくなります。

OpenAPI ドキュメントのデプロイ

API をデプロイする準備ができたら Google Cloud CLI を実行します。このツールは、Service Management を使用して API 構成をアップロードし、マネージドサービスを作成または更新します。

OpenAPI ドキュメントをデプロイするには:

OpenAPI ドキュメントが格納されている場所へディレクトリを変更します。
次のコマンドで返されるプロジェクト ID を検証して、サービスが間違ったプロジェクト内に作成されないようにします。
```
gcloud config list project
```
デフォルトプロジェクトを変更する必要がある場合は、次のコマンドを実行します。このとき [YOUR_PROJECT_ID] を、サービスを作成する Google Cloud プロジェクトの ID に置き換えます。
```
gcloud config set project [YOUR_PROJECT_ID]
```
次のコマンドを実行します。このとき [YOUR_OPENAPI_DOCUMENT] を、API が記述されている OpenAPI ドキュメントの名前に置き換えます。
```
gcloud endpoints services deploy [YOUR_OPENAPI_DOCUMENT]
```

前述のコマンドを初めて実行するときに、Service Management は新しい Endpoints サービスをデフォルトプロジェクト内に作成し、OpenAPI ドキュメントの host フィールドで指定したテキストと一致する名前を割り当て、サービス構成をアップロードします。

Service Management でサービスの作成と構成が行われるとき、情報がターミナルに出力されます。正常に完了すると、サービス構成 ID とサービス名を示す次のような行が表示されます。

Service Configuration [2017-02-13r0] uploaded for service [echo-api.endpoints.example-project-12345.cloud.goog]

上の例では、2017-02-13r0 がサービス構成 ID で、echo-api.endpoints.example-project-12345.cloud.goog がサービス名です。

デプロイが正常に完了したら、Google Cloud コンソールの [エンドポイント] > [サービス] ページで API を確認できます。

エラーメッセージが表示された場合は、Endpoints 構成のデプロイのトラブルシューティングをご覧ください。

再デプロイ

OpenAPI ドキュメントになんらかの変更を加えるたびに、必ずドキュメントを再デプロイし、Endpoints に API のサービス構成の最新バージョンを認識させてください。以前に ESP をデプロイしたときに rollout オプションを managed に設定している場合は、ESP の再デプロイや再起動は必要ありません。このオプションを構成すると、ESP はデプロイされた最新のサービス構成を使用します。このオプションを指定すると、新しいサービス構成をデプロイしてから 5 分以内に ESP が変更を検出し、自動的に使用します。ESP が特定の構成 ID でなく、このオプションを使用するようにしてください。

最初の Endpoints 構成のデプロイ後に、ユーザー、サービスアカウント、グループに対して、Endpoints 構成を再デプロイできるロールを付与できます。詳細については、API へのアクセス権の付与と取り消しをご覧ください。