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

API Gateway の OpenAPI 3.x 拡張機能

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

このページでは、OpenAPI 仕様 3.x の Google 固有の拡張機能について説明します。

以下の例は 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`	×	空白	モデルルーティングなどの人工知能機能を構成します。
`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`	リクエストに対する完全な応答を待機する秒数を指定します。この期限を超える応答はタイムアウトします。期限の最大値は 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`	○	空白	ターゲットモデル 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 セキュリティスキームを 1 つだけ指定する必要があります。API キー認証はパブリックプレビューではサポートされていません。

`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 Routing を 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 ドキュメントのサーバーエントリで 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 の機能の制限事項をご覧ください。

次のステップ

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`