このページでは、Endpoints の構成時に OpenAPI 3.x 仕様を使用する方法について説明します。
始める前に
- OpenAPI 2.0 仕様で構成された既存の Endpoints インスタンスがあることを確認します。
gcloudCLI をインストールします。詳細については、Google Cloud CLI をインストールするをご覧ください。
OpenAPI 3.x を使用するように Endpoints 構成を変更する
既存の OpenAPI 2.0 Endpoints 構成を変更して OpenAPI 3.x を使用するには、次の手順を行います。
デプロイ履歴を表示する
デプロイ履歴を表示するには、次の手順に従います。
Google Cloud コンソールで、[エンドポイント] > [サービス] ページに移動します。
プロジェクト リストからプロジェクトを選択します。
API が複数ある場合は、リストから対象の API を選択します。
サービス構成デプロイのリストを表示するには、[デプロイの履歴] タブをクリックします。このリストには、次の情報が表示されます。
- 構成 ID。
- サービス構成がデプロイされた日付。
- サービス構成をデプロイしたユーザー。
サービス構成を表示する
[デプロイの履歴] タブで、リストから最新のデプロイを選択します。デプロイされたサービス構成ファイルの内容が表示されます。
OpenAPI ドキュメントを OpenAPI 3.x に変換する
OpenAPI 2.0 ドキュメントを OpenAPI 3.x に変換します。この変換を OpenAPI 3.x にサポートするツールを使用できます。たとえば、Swagger Editor には変換ユーティリティが用意されています。
OpenAPI 3.x への初回変換後、OpenAPI 3.x に合わせてドキュメントに手動で変更を加え、Endpoints の拡張機能と機能との互換性を確保します。
次の表に、必要な変更を示します。
| 機能 | OpenAPI 2.0 | OpenAPI 3.x | 変更の説明 |
|---|---|---|---|
| API キー | securityDefinitions |
securitySchemes |
API キーは、すぐに使用できる OpenAPI API キーのサポートを使用します。変換ツールは通常、これを自動的に処理します。手動での変更は必要ありません。 |
| JWT 認証 | x-google-audiences など |
x-google-auth |
OpenAPI 2.0 拡張機能では、securityDefinition インスタンスの個々の拡張機能を使用して OAuth 構成を定義します。変換ツールは、セキュリティ スキーム インスタンスを #/components/securitySchemes に変換し、拡張機能を残します。これらの拡張機能を x-google-auth の子になるように手動で変更し、x-google- 接頭辞を削除します。値は変更されません。 |
| 割り当て | x-google-management、x-google-quota |
x-google-api-management、x-google-quota |
OpenAPI 2.0 拡張機能では、x-google-management で指標と割り当てを定義し、x-google-quota で関連付けます。変換ツールでは、これらの拡張機能はそのまま残されます。指標と割り当て構成を x-google-management から x-google-api-management に手動で移動します。YAML キーを使用するように構成を変更し、valueType、metricKind、unit を削除します。x-google-quota のインスタンスから metricCosts を削除します。 |
| バックエンド | x-google-backend |
x-google-api-management、x-google-backend |
OpenAPI 2.0 拡張機能では、x-google-backend でバックエンドを定義し、定義された場所で構成が適用されます。OpenAPI 3.x 拡張機能では、x-google-api-management でバックエンドを定義し、x-google-backend で適用します。変換ツールでは、この拡張機能はそのまま残されます。構成を x-google-api-management に手動で移動します。その構成を参照するように x-google-backend のインスタンスを変更します。 |
| エンドポイント | x-google-endpoints |
x-google-endpoint、servers |
OpenAPI 2.0 拡張機能では、x-google-endpoints でエンドポイント構成を定義します。OpenAPI 3.x 拡張機能では x-google-endpoint を使用しますが、これはルートではなく servers の拡張機能です。変換ツールでは、この拡張機能はそのまま残されます。これを手動で servers に移動し、name フィールドを削除します。次に例を示します。# OpenAPI 2.0 x-google-endpoints: - name: "my-api.apigateway.my-project.cloud.goog" allowCors: True # OpenAPI 3.x servers: - url: https://my-api.apigateway.my-project.cloud.goog/ x-google-endpoint: allowCors: True |
| API の名前 | x-google-api-name |
x-google-api-management |
OpenAPI 2.0 拡張機能では、x-google-api-name で API 名を定義します。OpenAPI 3.x 拡張機能では、x-google-api-management の apiName フィールドを使用します。この構成を x-google-api-management に手動で移動します。 |
| すべてのトラフィックを許可する | x-google-allow |
非対応 | OpenAPI ドキュメントから削除します。Endpoints は、OpenAPI 3.x でこれをサポートしていません。 |
サービス構成を再デプロイする
OpenAPI ドキュメントになんらかの変更を加えるたびに、必ずドキュメントを再デプロイし、Endpoints に API のサービス構成の最新バージョンを認識させてください。以前に ESP をデプロイしたときに rollout オプションを managed に設定している場合は、ESP の再デプロイや再起動は必要ありません。このオプションを構成すると、ESP はデプロイされた最新のサービス構成を使用します。このオプションを指定すると、新しいサービス構成をデプロイしてから 5 分以内に ESP が変更を検出し、自動的に使用します。ESP が特定の構成 ID でなく、このオプションを使用するようにしてください。
OpenAPI ドキュメントをデプロイするには:
OpenAPI ドキュメントが格納されている場所へディレクトリを変更します。
次のコマンドで返されるプロジェクト ID を検証して、サービスが間違ったプロジェクト内に作成されないようにします。
gcloud config list projectデフォルト プロジェクトを変更する必要がある場合は、次のコマンドを実行します。このとき YOUR_PROJECT_ID を、サービスを作成する Google Cloud プロジェクト ID に置き換えます。
gcloud config set project <var>YOUR_PROJECT_ID</var>次のコマンドを実行します。このとき YOUR_OPENAPI_DOCUMENT を、API が記述されている OpenAPI ドキュメントの名前に置き換えます。
gcloud endpoints services deploy <var>YOUR_OPENAPI_DOCUMENT</var>
前述のコマンドを初めて実行するときに、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 構成のデプロイのトラブルシューティングをご覧ください。