Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

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 ドキュメントで定義されたオペレーションに名前を関連付けます。
`ai`	`AI`	いいえ	空白	モデルルーティングなど、人工知能機能を構成します。

`Metric` オブジェクト

Metric オブジェクトは、割り当ての適用に使用される指標を定義します。

次の表に、Metric のフィールドを示します。

フィールド	タイプ	必須	デフォルト	説明
`displayName`	`string`	いいえ	空白	指標の表示名。

`Quota` オブジェクト

Quota オブジェクトは、割り当て上限を定義します。

次の表に、Quota のフィールドを示します。

フィールド	タイプ	必須	デフォルト	説明
`limits`	`map[string]QuotaLimit`	いいえ	空白	割り当て上限を指定します。

`Quota Limit` オブジェクト

QuotaLimit オブジェクトは、特定の割り当て上限を定義します。

次の表に、QuotaLimit のフィールドを示します。

フィールド	タイプ	必須	説明
`metric`	`string`	はい	この OpenAPI ドキュメントで宣言された指標を参照します。
`values`	`int64`	はい	クライアントリクエストが拒否される前に指標が到達できる最大値を設定します。

`Backends` オブジェクト

必須。

Backends オブジェクトは、バックエンドサービスを構成します。jwtAudience または disableAuth のいずれかを設定する必要があります。

次の表に、Backends のフィールドを示します。

フィールド	タイプ	必須	デフォルト	説明
`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`	リクエストに対する完全な応答を待機する秒数を指定します。この期限を超えたレスポンスはタイムアウトします。期限の最大値は 600 秒です。
`protocol`	`string`	いいえ	`http/1.1`	バックエンドにリクエストを送信するプロトコルを設定します。サポートされている値は `http/1.1` と `h2` です。

`AI` オブジェクト

AI オブジェクトは、モデルルーティングなど、サービスの人工知能機能を構成します。

次の表に、AI のフィールドを示します。

フィールド	タイプ	必須	デフォルト	説明
`models`	`Models`	いいえ	空白	AI モデルの統合を構成します。

`Models` オブジェクト

Models オブジェクトは、モデル固有の構成を定義します。

次の表に、Models のフィールドを示します。

フィールド	タイプ	必須	デフォルト	説明
`routing`	`Routing`	いいえ	空白	モデルルーティングの設定を構成します。

`Routing` オブジェクト

Routing オブジェクトは、モデルルーティングルールとルーターを定義します。

次の表に、Routing のフィールドを示します。

フィールド	タイプ	必須	デフォルト	説明
`routers`	`map[string]Router`	いいえ	空白	名前付きモデルルーターを定義します。

`Router` オブジェクト

Router オブジェクトは、名前付きモデルルーターを定義します。

次の表に、Router のフィールドを示します。

フィールド	タイプ	必須	デフォルト	説明
`defaultModel`	`DefaultModel`	はい	空白	受信リクエストが明示的なルールと一致しない場合に使用される、必須のフォールバックモデルの宛先。
`rules`	`[Rule]`	いいえ	空白	明示的なモデルルーティングルールのリスト。

`DefaultModel` オブジェクト

DefaultModel オブジェクトは、フォールバックの宛先を指定します。

次の表に、DefaultModel のフィールドを示します。

フィールド	タイプ	必須	デフォルト	説明
`backend`	`string`	はい	空白	`x-google-api-management.backends` で宣言されたバックエンドを参照します。
`targetModel`	`string`	はい	空白	ターゲットモデルの識別子を `<provider>/<model-id>` の形式で指定します。OpenAI 互換のルートの場合、フォールバックが発生すると、この値はリクエスト本文の出力 `model` 属性として転送されます。

`Rule` オブジェクト

Rule オブジェクトは、明示的なモデルルーティングルールを定義します。

次の表に、Rule のフィールドを示します。

フィールド	タイプ	必須	デフォルト	説明
`model`	`string`	はい	空白	クライアントの JSON ペイロードの `model` 属性と照合される入力文字列。OpenAI 互換のルートの場合、この文字列はリクエスト本文の出力 `model` 属性として転送され、有効な `<provider>/<model-id>` 文字列である必要があります。
`backend`	`string`	はい	空白	`x-google-api-management.backends` で宣言されたバックエンドを参照します。
`targetModel`	`string`	はい	空白	ターゲットモデルの識別子を `<provider>/<model-id>` の形式で指定します。この値はプロバイダの変換を選択し、レスポンスの `model` フィールドにエコーバックされます。

`x-google-auth`

省略可。

x-google-auth 拡張機能は、セキュリティスキームオブジェクト内で認証設定を定義します。

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

フィールド	タイプ	必須	デフォルト	説明
`issuer`	`string`	いいえ	空白	認証情報の発行者を指定します。値には、ホスト名またはメールアドレスを指定できます。
`jwksUri`	`string`	いいえ	空白	JSON ウェブトークンの署名検証に使用されるプロバイダの公開鍵の URI を指定します。API Gateway は、この OpenAPI 拡張で定義された次の 2 つの非対称公開鍵形式がサポートされています。 JWK セット形式例: `jwksUri: "https://YOUR_ACCOUNT_NAME.YOUR_AUTH_PROVIDER_URL/.well-known/jwks.json"` 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 拡張機能は、個々のオペレーションで使用され、x-google-api-management.metrics で定義されたどの指標がそのオペレーションへのリクエストの影響を受けるかを指定します。

x-google-quota は、Key-Value ペアを含むオブジェクトです。各キーは指標名で、値はそのオペレーションへのリクエストごとの整数コストです。例:

x-google-api-management:
  metrics:
    read-requests:
      displayName: "Greeter requests"
    write-requests:
      displayName: "Greeter requests by name"
  quota:
    limits:
      read-requests-limit:
        metric: read-requests
        values: 1
# Set at the top-level so this applies to all operations (unless overridden)
x-google-quota:
    read-requests: 1
paths:
  /v1/projects/projectId/pets:
    get:
      # Set at the path level, so it overrides the top level quota
      x-google-quota:
          write-requests: 1

`x-google-backend`

必須。

x-google-backend 拡張機能は、x-google-api-management.backends で定義されたバックエンドを参照します。使用する場合、その値は x-google-api-management.backends で定義されたバックエンドの名前に一致する文字列である必要があります。この拡張機能は API Gateway に設定する必要があります。この拡張機能は、OpenAPI ドキュメントの最上位または個々のオペレーションで定義して、最上位のバックエンドをオーバーライドできます。

例:

x-google-api-management:
  backends:
    my-backend:
      address: myapp.run.app
x-google-backend: my-backend

`x-google-model-router`

省略可。

x-google-model-router 拡張機能は、x-google-api-management.ai.models.routing.routers で定義されたモデルルーターを参照します。使用する場合、その値は x-google-api-management.ai.models.routing.routers で定義されたルーターの名前に一致する文字列である必要があります。

この拡張機能は OpenAPI 3.x 仕様でのみサポートされており、OpenAPI 2.0（Swagger）仕様では使用できません。この拡張機能は、POST HTTP メソッドを使用するオペレーションの個々のオペレーションレベルでのみ定義できます。同じオペレーションで x-google-model-router と x-google-backend の両方を指定することはできません。また、同じ API 仕様内の異なるパスでモデルルーティングオペレーションと非モデルルーティングオペレーションを混在させることもできません。

例:

x-google-api-management:
  backends:
    gemini-backend:
      address: https://aiplatform.googleapis.com/v1/...
  ai:
    models:
      routing:
        routers:
          my-router:
            defaultModel:
              backend: gemini-backend
              targetModel: google/gemini-3.5-flash-lite
paths:
  /v1/chat:
    post:
      x-google-model-router: my-router

`x-google-endpoint`

省略可。

x-google-endpoint 拡張機能は、OpenAPI 3.x ドキュメントの servers 配列で定義されたサーバーのプロパティを構成するために使用されます。OpenAPI ドキュメント内のサーバーエントリは 1 つのみ、x-google-endpoint 拡張機能を使用できます。

この拡張機能では、次のような他のバックエンド機能も定義します。

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 の機能の制限をご覧ください。

次のステップ

OpenAPI 仕様を確認する。
OpenAPI 3.0 を使用するようにゲートウェイを変更する。

API Gateway の OpenAPI 3.x 拡張機能

x-google-api-management

Metric オブジェクト

Quota オブジェクト

Quota Limit オブジェクト

Backends オブジェクト

AI オブジェクト

Models オブジェクト

Routing オブジェクト

Router オブジェクト

DefaultModel オブジェクト

Rule オブジェクト

x-google-auth

JwtLocations オブジェクト

x-google-quota

x-google-backend

x-google-model-router

x-google-endpoint

x-google-parameter

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

次のステップ

`x-google-api-management`

`Metric` オブジェクト

`Quota` オブジェクト

`Quota Limit` オブジェクト

`Backends` オブジェクト

`AI` オブジェクト

`Models` オブジェクト

`Routing` オブジェクト

`Router` オブジェクト

`DefaultModel` オブジェクト

`Rule` オブジェクト

`x-google-auth`

`JwtLocations` オブジェクト

`x-google-quota`

`x-google-backend`

`x-google-model-router`

`x-google-endpoint`

`x-google-parameter`