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

API Gateway の OpenAPI 3.x 拡張機能

API Gateway は、ゲートウェイの動作を構成する OpenAPI 仕様に対する Google 固有の拡張機能のセットを受け入れます。これらの拡張機能を使用すると、API 管理設定、認証方法、割り当て上限、バックエンド統合を OpenAPI ドキュメント内で直接指定できます。これらの拡張機能を理解すると、サービス動作をカスタマイズして 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`	いいえ	空白	モデルルーティングなどの AI 機能を構成します。
`mcp`	`MCP` または `bool`	いいえ	空白	Model Context Protocol（MCP）機能を有効にするか、構成します。

`Metric` オブジェクト

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

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

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

`Quota` オブジェクト

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

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

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

`QuotaLimit` オブジェクト

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`	リクエストに対する完全なレスポンスを待機する秒数を指定します。この期限を超えたレスポンスはタイムアウトします。SSE またはチャンク転送エンドポイントでは、デッドラインはストリーム全体の期間を制限します。gRPC または WebSocket エンドポイントでは、メッセージ間のギャップを制限します。各種類のリクエストに適用されるタイムアウトについては、ストリームの期限を設定するをご覧ください。デフォルトを使用するには、このフィールドを省略するか、`0` に設定します。負の値は拒否されます。期限は最大 3,600 秒まで構成できます。非ストリーミングゲートウェイでは、最大 600 秒が適用されます。API 構成の作成時ではなく、ゲートウェイの作成時または更新時に、より長い期限が拒否されます。
`protocol`	`string`	いいえ	`http/1.1`	バックエンドにリクエストを送信するためのプロトコルを設定します。サポートされている値は `http/1.1` と `h2` です。プロトコルの要件は、ストリーミングタイプによって異なります。 - gRPC: プロトコルを `h2` に設定する必要があります。 - WebSockets: `http/1.1` を使用する必要があります。 - サーバー送信イベント（SSE）と増分レスポンス配信: `http/1.1` または `h2` を使用できます。パフォーマンスを向上させるため、`h2` をおすすめします。

`AI` オブジェクト

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`	○	空白	ターゲットモデル ID を `<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`	○	空白	ターゲットモデル ID を `<provider>/<model-id>` の形式で指定します。この値はプロバイダの変換を選択し、レスポンスの `model` フィールドにエコーバックされます。

`MCP` オブジェクト

MCP オブジェクトは、サービスの Model Context Protocol（MCP）機能を構成します。mcp は、ブール値またはオブジェクトに設定できます。true に設定すると、デフォルト設定ですべての対象オペレーションに対して MCP がグローバルに有効になります。

次の表に、MCP オブジェクトのフィールドを示します。

フィールド	種類	必須	デフォルト	説明
`tools-list`	`ToolsList`	いいえ	空白	`tools/list` MCP メソッドの設定を構成します。

`ToolsList` オブジェクト

ToolsList オブジェクトは、tools/list MCP メソッドの設定を構成します。

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

フィールド	種類	必須	デフォルト	説明
`security`	`map`	いいえ	空白	`tools/list` で認証を有効にします。セキュリティのベストプラクティスとして、このオプションを構成することを強くおすすめします。`components.securitySchemes` で定義された JWT または API キーのセキュリティスキームを 1 つだけ指定する必要があります。

`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 仕様内の異なるパスでモデルルーティングオペレーションと非モデルルーティングオペレーションを混在させることもできません。また、モデルルーティングを Model Context Protocol（MCP）と組み合わせて使用することはできません。x-google-api-management.mcp を有効にすると、この拡張機能は使用できなくなります。

次に例を示します。

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-mcp-tool`

省略可。

x-google-mcp-tool 拡張機能は、個々のオペレーションで使用され、MCP ツールとして公開されます。また、生成されたツール名と説明をオーバーライドすることもできます。

この拡張機能は OpenAPI 3.x 仕様でのみサポートされています。OpenAPI 2.0（Swagger）仕様では使用できません。この拡張機能は、個々のオペレーションレベルでのみ定義できます。

ブール値またはオブジェクトを指定します。

ブール値形式: このオペレーションを有効にするには、true に設定します。false に設定すると、グローバルな有効化をオーバーライドして無効にできます。
オブジェクトフォーム: 生成されたツール設定をオプトインしてオーバーライドします。

次の表に、オブジェクトとして使用される場合の x-google-mcp-tool のフィールドを示します。

フィールド	種類	必須	デフォルト	説明
`name`	`string`	いいえ	オペレーションの `operationId`	MCP ツールの名前。`[A-Za-z0-9_.-]{1,128}` と一致し、仕様全体で一意である必要があります。
`description`	`string`	いいえ	オペレーションの説明（概要にフォールバック）	MCP ツールの説明。これは、LLM がツールの選択に使用する主なシグナルです。

次に例を示します。

paths:
  /v1/shelves/{shelf}:
    delete:
      operationId: deleteShelf
      summary: Delete a shelf.
      x-google-backend: bookstore-backend
      x-google-mcp-tool:
        name: delete_shelf
        description: "Permanently delete a shelf and every book on it."

`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 オブジェクト

QuotaLimit オブジェクト

Backends オブジェクト

AI オブジェクト

Models オブジェクト

Routing オブジェクト

Router オブジェクト

DefaultModel オブジェクト

Rule オブジェクト

MCP オブジェクト

ToolsList オブジェクト

x-google-auth

JwtLocations オブジェクト

x-google-quota

x-google-backend

x-google-model-router

x-google-mcp-tool

x-google-endpoint

x-google-parameter

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

次のステップ

`x-google-api-management`

`Metric` オブジェクト

`Quota` オブジェクト

`QuotaLimit` オブジェクト

`Backends` オブジェクト

`AI` オブジェクト

`Models` オブジェクト

`Routing` オブジェクト

`Router` オブジェクト

`DefaultModel` オブジェクト

`Rule` オブジェクト

`MCP` オブジェクト

`ToolsList` オブジェクト

`x-google-auth`

`JwtLocations` オブジェクト

`x-google-quota`

`x-google-backend`

`x-google-model-router`

`x-google-mcp-tool`

`x-google-endpoint`

`x-google-parameter`