OpenAPI ドキュメントでの Cloud Endpoints の構成が完了した後で、この構成をデプロイすると、API を管理するために必要な情報が Cloud Endpoints に送られます。Endpoints の構成をデプロイするには、gcloud
endpoints services deploy
コマンドを使用します。このコマンドは、Google の基礎的なサービス プラットフォームである Service Infrastructure を使用します。このプラットフォームは、Endpoints やその他のサービスで API やサービスを作成、管理するために使用されます。このページでは、OpenAPI ドキュメントを Endpoints にデプロイする方法について説明します。
要件
このページの説明は、次のことを前提としています。
自分が編集者またはオーナーの役割を持つ Google Cloud プロジェクトを作成済みであること。最初のデプロイ後に、ユーザー、グループ、サービス アカウントに対してより制限の厳しい Service Config 編集者の役割を付与できます。詳細については、API へのアクセス権の付与と取り消しをご覧ください。
カスタム ドメイン名(
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 へのアクセス権の付与と取り消しをご覧ください。
次のステップ
- Cloud Endpoints Portal のスタートガイド
- API バックエンドをデプロイする
- Kubernetes でデプロイする
- ESP をローカルまたは別のプラットフォームで実行する
- サービス名と構成 ID を取得する