ゲートウェイの動作を構成するために Google が独自に開発した OpenAPI 仕様の拡張機能が、Endpoints でサポートされています。これらの拡張機能を使用すると、OpenAPI ドキュメント内で API 管理設定、認証方法、割り当て上限、バックエンド統合を直接指定できます。これらの拡張機能を理解すると、サービス動作を調整して Endpoints の機能と統合できます。
このページでは、Google 独自の OpenAPI 仕様 3.x の拡張機能について説明します。
以下の例は YAML 形式ですが、JSON もサポートされています。
x-google-api-management
必須。
x-google-api-management 拡張機能は、サービスの最上位の API 管理設定を定義します。この拡張機能を OpenAPI ドキュメントのルートに配置します。
次の表に、x-google-api-management のフィールドを示します。
| フィールド | 型 | 必須 | デフォルト | 説明 |
|---|---|---|---|---|
metrics |
map[string]Metric |
いいえ | 空白 | 割り当て上限を適用する指標を定義します。 |
quota |
map[string]Quota |
いいえ | 空白 | サービスの割り当て上限を指定します。 |
backends |
map[string]Backend |
いいえ | 空白 | バックエンド サービスを構成します。 |
apiName |
string |
いいえ | 空白 | OpenAPI ドキュメントで定義されたオペレーションに名前を関連付けます。 |
Metric オブジェクト
Metric オブジェクトは、割り当ての適用に使用される指標を定義します。
次の表に、Metric のフィールドを示します。
| フィールド | 型 | 必須 | デフォルト | 説明 |
|---|---|---|---|---|
displayName |
string |
いいえ | 空白 | 指標の表示名。 |
Quota オブジェクト
Quota オブジェクトは割り当て上限を定義します。
次の表に、Quota のフィールドを示します。
| フィールド | 型 | 必須 | デフォルト | 説明 |
|---|---|---|---|---|
limits |
map[string]QuotaLimit |
いいえ | 空白 | 割り当て上限を指定します。 |
Quota Limit オブジェクト
QuotaLimit オブジェクトは、特定の割り当て上限を定義します。
次の表に、QuotaLimit のフィールドを示します。
| フィールド | 型 | 必須 / 省略可 | 説明 |
|---|---|---|---|
metric |
string |
はい | この OpenAPI ドキュメントで宣言された指標を参照します。 |
values |
int64 |
はい | クライアント リクエストが拒否される前に指標が到達できる最大値を設定します。 |
Backend オブジェクト
Backend オブジェクトはバックエンド サービスを構成します。jwtAudience または disableAuth を設定する必要があります。
次の表に、Backend のフィールドを示します。
| フィールド | 型 | 必須 | デフォルト | 説明 |
|---|---|---|---|---|
address |
string |
いいえ | 空白 | バックエンドの URL を指定します。 |
jwtAudience |
string |
いいえ | 空白 | デフォルトでは、Endpoints はアドレス フィールドと一致する JWT オーディエンスを使用してインスタンス ID トークンを作成します。jwt_audience を手動で指定するのは、ターゲット バックエンドが JWT ベースの認証を使用し、想定されるオーディエンスがアドレス フィールドで指定された値と異なる場合のみ必要になります。App Engine にデプロイされたリモート バックエンドまたは IAP を使用するリモート バックエンドの場合は、JWT オーディエンスをオーバーライドする必要があります。App Engine と IAP は、OAuth クライアント ID を想定されるオーディエンスとして使用します。 |
disableAuth |
bool |
いいえ | False |
データプレーン プロキシがインスタンス ID トークンを取得してリクエストにアタッチすることを禁止します。 |
pathTranslation |
string |
いいえ | APPEND_PATH_TO_ADDRESS または CONSTANT_ADDRESS |
ターゲット バックエンドにリクエストをプロキシするときにパス変換ストラテジを設定します。x-google-backend が最上位レベルで設定されている場合、デフォルトの pathTranslation は APPEND_PATH_TO_ADDRESS です。オペレーションで x-google-backend が設定されている場合、デフォルトは CONSTANT_ADDRESS です。 |
deadline |
double |
いいえ | 15.0 |
リクエストに対する完全な応答を待機する秒数を指定します。この期限を超える応答はタイムアウトします。 |
protocol |
string |
いいえ | http/1.1 |
バックエンドにリクエストを送信するためのプロトコルを設定します。サポートされる値は http/1.1 と h2 です。 |
x-google-auth
省略可。
x-google-auth 拡張機能は、セキュリティ スキーム オブジェクト内で認証設定を定義します。
次の表に、x-google-auth のフィールドを示します。
| フィールド | 型 | 必須 | デフォルト | 説明 |
|---|---|---|---|---|
issuer |
string |
いいえ | 空白 | 認証情報の発行者を指定します。ホスト名またはメールアドレスを指定します。 |
jwksUri |
string |
いいえ | 空白 | JSON ウェブトークンの署名検証に使用されるプロバイダの公開鍵の URI を指定します。 |
audiences |
[string] |
いいえ | 空白 | JWT 認証時に JWT の aud フィールドが一致する必要があるオーディエンスのリスト。 |
jwtLocations |
[JwtLocations] |
いいえ | 空白 | JWT トークンの場所をカスタマイズします。デフォルトでは、JWT は Authorization ヘッダー（接頭辞「Bearer」）、X-Goog-Iap-Jwt-Assertion ヘッダー、または access_token クエリ パラメータのいずれかで渡されます。 |
JwtLocations オブジェクト
JwtLocations オブジェクトは、JWT トークンのカスタマイズされた場所を提供します。
次の表に、JwtLocations のフィールドを示します。
| フィールド | 型 | 必須 | デフォルト | 説明 |
|---|---|---|---|---|
header | query |
string |
はい | なし | JWT を含むヘッダーの名前、または JWT を含むクエリ パラメータの名前を指定します。 |
valuePrefix |
string |
いいえ | 空白 | ヘッダーの場合のみ。設定されている場合、その値は JWT を含むヘッダー値の接頭辞と一致する必要があります。 |
x-google-quota
省略可。
x-google-quota 拡張機能は割り当て上限を定義します。この拡張機能は、OpenAPI ドキュメントのトップレベルまたは個々のオペレーションで定義できます。
次の表に、x-google-quota のフィールドを示します。
| フィールド | 型 | 必須 / 省略可 | 説明 |
|---|---|---|---|
self |
map[string]int64 |
はい | quota オブジェクト（self）は、オブジェクト内で定義された指標を参照します。この場合、指標（read-requests など）を指標を増やす量にマッピングします。指標値が割り当て上限に達すると、リクエストは拒否されます。 |
x-google-backend
必須。
x-google-backend 拡張機能は、x-google-api-management で定義されたバックエンドを参照します。この拡張機能は Endpoints に設定する必要があります。この拡張機能は、OpenAPI ドキュメントのトップレベルまたは個々のオペレーションで定義できます。
次の表に、x-google-backend のフィールドを示します。
| フィールド | 型 | 必須 / 省略可 | 説明 |
|---|---|---|---|
self |
string |
はい | x-google-api-management で定義されたバックエンドの ID を参照します。 |
x-google-endpoint
必須。
x-google-endpoint 拡張機能は、OpenAPI 3.x ドキュメントの servers 配列で定義されたサーバーのプロパティを構成するために使用されます。OpenAPI ドキュメントのサーバー エントリで x-google-endpoint 拡張機能を使用できるのは 1 つだけです。
この拡張機能では、次のバックエンド機能も定義します。
- CORS:
allowCorsプロパティをtrueに設定すると、クロスオリジン リソース シェアリング（CORS）を有効にできます。 - ベースパス:
x-google-endpointを使用してサーバーに設定されたベースパスが API に使用されます。たとえば、次の構成ではv1がベースパスとして設定されます。
servers:
- url: https://API_NAME.apigateway.PROJECT_ID.cloud.goog/v1
x-google-endpoint: {}
次の表に、x-google-endpoint のフィールドを示します。
| フィールド | 型 | 必須 | デフォルト | 説明 |
|---|---|---|---|---|
target |
string |
いいえ | ホストが解決する IP アドレスを指定します。 | |
allowCors |
bool |
いいえ | false |
CORS リクエストを許可します。 |
OpenAPI 拡張機能の制限事項について
これらの OpenAPI 拡張機能には特定の制限があります。詳細については、OpenAPI 3.x の機能の制限事項をご覧ください。
次のステップ
- OpenAPI 仕様を確認する。
- 特定のエンドポイントまたは ESPv2 構成については、Endpoints のドキュメントをご覧ください。