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

OpenAPI 3.x 機能の制限

このドキュメントでは、API Gateway で OpenAPI 3.x を使用する場合の機能制限について説明します。

サポートされている OpenAPI 仕様のバージョンの詳細については、OpenAPI の概要をご覧ください。

新しい OpenAPI 3.x の制限事項

このセクションでは、OpenAPI 3.x の新機能の制限事項について説明します。

サーバー

OpenAPI 3.x では、複数の server オブジェクトを使用してホストとベースパスを定義できます。ただし、API Gateway は、x-google-endpoint 拡張機能で識別される単一のサーバーオブジェクトを使用してサービスを構成します。

複数のサーバーを定義できますが、API Gateway は x-google-endpoint 拡張機能を含むサーバーのみを考慮し、そのようなサーバーを 1 つだけ許可します。API Gateway の場合、サーバー URL は必要ありません。そのため、サーバーを定義しないか、x-google-endpoint 拡張機能を持つサーバーを 1 つ定義します。

たとえば、次の定義は API Gateway で有効です。

servers:
  - url: https://example.com
    x-google-endpoint: {}

servers:
  - url: https://example.com
    x-google-endpoint: {}
  - url: https://example2.com

次の定義は、複数の x-google-endpoint 拡張機能が含まれているため、無効です。

servers:
  - url: https://example.com
    x-google-endpoint: {}
  - url: https://example2.com
    x-google-endpoint: {}

次の定義は API Gateway で有効ですが、API Gateway はサーバーオブジェクトを無視します。

servers:
  - url: https://example.com

複数のファイルにまたがるサーバー

複数の OpenAPI ファイルをアップロードし、1 つのファイルに x-google-endpoint 拡張子を持つサーバーが含まれている場合、すべてのファイルに、同じ x-google-endpoint 拡張子とサーバー URL 内の同じホストを持つサーバーが定義されている必要があります。ベースパスはファイルごとに異なる場合があります。

相対 URL

API Gateway の場合、servers オブジェクトの相対 URL は、仕様でホスト名が不要なため、ベースパスとして扱われます。これは、OpenAPI 定義をホストするサーバーに対して相対 URL を解決する標準の OpenAPI の動作とは異なります。たとえば、API Gateway は url: /v1 をベースパスとして扱います。

ベースパスは「/」で始まる必要があります。API Gateway は、スキームがない URL や、ベースパスを示す「/」で始まらない URL を拒否します。

サポートされていない拡張機能

API Gateway は、OpenAPI 3.x の x-google-allow 拡張機能をサポートしていません。

ファイルサイズの上限:

API Gateway では、アップロードされた OpenAPI 3.x ファイルの合計サイズの上限が 10 MB、ファイル数の上限が 50 に制限されています。

MCP の制限事項

パブリックプレビュー期間中、Model Context Protocol（MCP）のサポートには次の制限が適用されます。

ツール数の上限: 1 つの Gateway で使用できる MCP ツールは最大 1,000 個です。
HTTP メソッド: MCP ツールとして公開できるのは、GET、POST、PUT、PATCH、および DELETE の操作のみです。HEAD、OPTIONS、TRACE はサポートされていません。
ストリーミング: 長時間実行されるツール呼び出しのサーバー送信イベント（SSE）ストリーミングはサポートされていません。
バッチリクエスト: JSON-RPC バッチ配列は拒否されます。
マルチモーダルペイロード: ツールのレスポンスは UTF-8 テキストに制限されています。バイナリレスポンスはサポートされていません。
ステートレス性: 実装はステートレスです。セッション識別子（MCP-Session-Id など）は使用されず、維持されません。
サポートされていない MCP メソッド: resources/*、prompts/*、sampling/*、completion/*、ping、logging/* などの特殊なメソッドはサポートされておらず、JSON-RPC エラーコード -32601 を返します。
ツールアノテーションなし: destructiveHint や readOnlyHint などのヒントは、ツール宣言で出力されません。
CORS プリフライト: /mcp パスでの自動 CORS プリフライト処理（OPTIONS リクエスト）は、ゲートウェイによって管理されません。
モデルルーティングの相互排他: 同じ API 構成内で MCP とモデルルーティングの両方を使用することはできません。
サポートされていない MCP レスポンス: レスポンスで空の本文を返すオペレーション（HTTP 204 レスポンスなど）はサポートされていません。
スキーマ検出: OpenAPI 仕様から派生した複雑なネストされたオブジェクトスキーマは、既知の構成処理の制限により、tools/list 検出レスポンスで完全または正しくレンダリングされない場合があります。
ツールリストの変更通知なし: ゲートウェイは notifications/tools/list_changed を出力しません。新しい API 構成をデプロイした後、クライアントは tools/list を再度呼び出す必要があります。公開されている MCP ツールを更新するをご覧ください。

既存の制限事項

このセクションでは、OpenAPI 2.0 から引き継がれ、OpenAPI 3.x にも適用される制限事項について説明します。

スコープが無視される

API Gateway は、セキュリティスキームオブジェクトで定義されたスコープを持つ OpenAPI ドキュメントを受け入れますが、これらのスコープの確認や適用は行いません。

複数のセキュリティ要件

API キーの要件: API Gateway は、スキームの 1 つが API キーである場合、代替（論理 OR）セキュリティ要件をサポートしません。ただし、API Gateway は論理積（論理 AND）をサポートしているため、API キーと OAuth2 トークンの両方を要求できます。
OAuth2 の要件: API Gateway は、さまざまな OAuth2 セキュリティスキームに対して代替（論理 OR）セキュリティ要件をサポートしています。API Gateway は、追加のセキュリティ要件が API キーでない限り、接続詞（論理 AND）をサポートしていません。
オプションのセキュリティ: 空のセキュリティ要件（- {}）を使用して、API キーのセキュリティをオプションにできますが、API Gateway では OAuth でこれをサポートしていません。

セキュリティ定義の検証

API Gateway は、securityDefinitions セクションに対応する定義がないセキュリティ要件を使用する OpenAPI 3.x 仕様を拒否します。

URL パステンプレート

API Gateway は、パスセグメント全体を表す URL パステンプレートパラメータ（/items/{itemId} など）のみをサポートします。API Gateway は、部分セグメント（/items/prefix_{id}_suffix など）に対応するパラメータをサポートしておらず、拒否します。

パラメータ、スキーマ、リクエスト本文、型

API Gateway は、さまざまなパラメータと型定義（required パラメータや配列形式など）を含む OpenAPI ドキュメントを受け入れますが、それらを適用しません。API Gateway は、これらの定義に関係なく、受信リクエストを API に転送します。

API Gateway は、リクエストパラメータでプリミティブ型のみをサポートします。

外部型参照

API Gateway は、提供された OpenAPI ドキュメント外のタイプへの参照をサポートしていません。たとえば、API Gateway は外部 URL を指す $ref を許可せず、拒否します。

ホストアドレスのカスタムポート

API Gateway では、OpenAPI ドキュメントの servers.url フィールドにカスタムポートを使用できません。

YAML エイリアスの制限事項

API Gateway に送信される OpenAPI ドキュメントには、最大 200 個の YAML エイリアスノードを含めることができます。