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

OpenAPI 3.x の機能の制限事項

OpenAPI | gRPC

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

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

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

このセクションでは、OpenAPI 3.x のサポートで新たに導入された OpenAPI の制限事項について説明します。

サーバー

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

OpenAPI 仕様では複数のサーバーを定義できますが、Cloud Endpoints は x-google-endpoint 拡張機能を持つサーバーのみを使用します。x-google-endpoint 拡張機能は 1 つのサーバーでのみ定義できます。

Cloud Endpoints の場合はホスト名が必要になるため、x-google-endpoint 拡張機能を持つサーバーは 1 つだけにする必要があります。

たとえば、次のサーバー定義は Cloud Endpoints で有効です。

servers:
  - url: https://my-api.endpoints.my-project-id.cloud.goog
    x-google-endpoint: {}

servers:
  - url: https://my-api.endpoints.my-project-id.cloud.goog
    x-google-endpoint: {}
  - url: https://example.com

次のサーバー定義は Endpoints では無効です。

servers:
  - url: https://my-api-1.endpoints.my-project-id.cloud.goog
    x-google-endpoint: {}
  - url: https://my-api-2.endpoints.my-project-id.cloud.goog
    x-google-endpoint: {}

次の定義も Cloud Endpoints では無効です。

servers:
  - url: https://my-api.endpoints.my-project-id.cloud.goog

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

複数の OpenAPI ファイルをアップロードする場合は、すべてのファイルが servers セクションの制限に準拠している必要があります。1 つのファイルに x-google-endpoint 拡張子のサーバーが含まれている場合、すべてのファイルで x-google-endpoint 拡張子のサーバーを定義する必要があります。

また、x-google-endpoint 拡張子を持つすべてのサーバーは、サーバー URL で同一のホストを使用する必要があり、x-google-endpoint 構成はすべてのファイルで同一である必要があります。サーバー URL のベースパスは異なる場合があります。

相対 URL

Cloud Endpoints にはホスト名が必要なため、相対 URL はサポートされていません。

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

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

既存の制限事項

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

スコープが無視される

セキュリティスキームオブジェクトでスコープを定義できますが、ESP または Cloud Endpoints Frameworks はスコープをチェックしません。

複数のセキュリティ要件

OpenAPI ドキュメントに複数のセキュリティ要件を指定できます。

API キーを使用したセキュリティ要件: スキームの 1 つが API キーである場合、Cloud Endpoints は択一的（論理 OR）セキュリティ要件をサポートしません。Cloud Endpoints は連結（論理 AND）をサポートしているため、API キーと OAuth2 認証の両方を必須にできます。
OAuth2 のセキュリティ要件: Cloud Endpoints は、さまざまな OAuth2 認証スキームの択一的（論理 OR）セキュリティ要件をサポートしています。追加のセキュリティ要件が API キーでない限り、Cloud Endpoints は連結（論理 AND）をサポートしていません。
省略可能なセキュリティ要件: OpenAPI 3 は、空の要件（{}）を含めることで省略可能なセキュリティをサポートします。API キーはこれをサポートしますが、OAuth はサポートしません。

セキュリティ定義の検証

OpenAPI 3.x では、未定義のセキュリティスキーマを使用するとエラーが発生し、Cloud Endpoints は仕様を拒否します。OpenAPI 2.0 では警告のみが生成されていましたが、この点が変更されています。

URL パステンプレート

Cloud Endpoints は、パスセグメント全体（/ で区切られた部分）に対応する URL パステンプレートパラメータのみをサポートします。Cloud Endpoints は、パスセグメントの一部に対応するパラメータをサポートしていません。

たとえば、Cloud Endpoints は /items/{itemId} をサポートしていますが、/items/overview.{format} はサポートしていません。

URL ルートパス「`/`」上のオペレーション

OpenAPI ドキュメントはルートパス / のオペレーションを受け入れますが、Extensible Service Proxy はルートパスへのリクエストを拒否します。この制限は、ルートパスをサポートする ESPv2 には適用されません。

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

Extensible Service Proxy と ESP は、ほとんどのパラメータ、スキーマ、リクエスト本文、型の定義を無視します。Extensible Service Proxy と ESP は、必要なパラメータと型の定義を適用せず、リクエストを API に転送します。

Extensible Service Proxy と ESP は、リクエストパラメータのプリミティブ型のみをサポートします。

外部型参照

Cloud Endpoints は、OpenAPI ドキュメントの外部にある型への参照をサポートしていません。たとえば、外部 URL に $ref を使用することはできません。

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

servers オブジェクトの url でカスタムポートを使用することはできません。

YAML エイリアスの制限事項

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

繰り返しのないリクエスト本文

オペレーションごとに定義できる requestBody は 1 つだけで、繰り返し以外の型にする必要があります。

OpenAPI 3.x の機能の制限事項 コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。