API Gateway の OpenAPI 3.x 拡張機能

API Gateway では、ゲートウェイの動作を構成するために Google が独自に開発した OpenAPI 仕様の拡張機能がサポートされています。これらの拡張機能を使用すると、OpenAPI ドキュメント内で API 管理設定、認証方法、割り当て上限、バックエンド統合を直接指定できます。これらの拡張機能を理解すると、サービス動作を調整して API Gateway の機能と統合できます。

このページでは、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 × 空白 デフォルトでは、API Gateway はアドレス フィールドと一致する 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 がトップレベルで設定され、path_translation が指定されていない場合、デフォルトの pathTranslation は APPEND_PATH_TO_ADDRESS になります。オペレーション レベルで x-google-backend が設定され、path_translation が指定されていない場合、デフォルトは 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 を指定します。API Gateway は、この OpenAPI 拡張機能で定義された次の 2 つの非対称公開鍵形式をサポートしています。

  1. JWK セット形式。例: jwksUri: "https://YOUR_ACCOUNT_NAME.YOUR_AUTH_PROVIDER_URL/.well-known/jwks.json"
  2. X509例: jwksUri: "https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com"

対称鍵形式を使用する場合は、Base64URL エンコードされた鍵文字列を含むファイルの URI に jwksUri を設定します。
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 で定義されたバックエンドを参照します。API Gateway にこの拡張機能を設定する必要があります。この拡張機能は、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 のフィールドを示します。

フィールド タイプ 必須 デフォルト 説明
allowCors bool × false CORS リクエストを許可します。

x-google-parameter

省略可。

x-google-parameter 拡張機能は parameter アイテムで定義されます。これは、パスで パス テンプレートを使用して、ダブル ワイルドカード照合動作を使用することを指定する場合に使用できます。

次の表に、x-google-parameter のフィールドを示します。

フィールド タイプ 必須 説明
pattern string はい これは ** に設定する必要があります。

OpenAPI 拡張機能の制限事項について

これらの OpenAPI 拡張機能には特定の制限があります。詳細については、OpenAPI 3.x の機能の制限事項をご覧ください。

次のステップ