このページは Cloud Translation API によって翻訳されました。

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 が適用されます。

既存の制限事項

このセクションでは、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 エイリアスノードを含めることができます。