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）のサポートには次の制限が適用されます。

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

既存の制限事項

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

スコープが無視される

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

複数のセキュリティ要件

API キーの要件: スキームの 1 つが API キーである場合、API Gateway は択一的（論理 OR）セキュリティ要件をサポートしません。ただし、API Gateway は連結（論理 AND）をサポートしているため、API キーと OAuth2 トークンの両方を必須にできます。
OAuth2 の要件: API Gateway は、さまざまな OAuth2 セキュリティスキームの択一的（論理 OR）セキュリティ要件をサポートしています。追加のセキュリティ要件が API キーでない限り、API Gateway は連結（論理 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 エイリアスノードを含めることができます。