本頁面由 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 擴充功能的伺服器，且只允許一個這類伺服器。API Gateway 不需要伺服器網址，因此您可以不定義任何伺服器，也可以定義一個含有 x-google-endpoint 擴充功能的伺服器。

舉例來說，下列定義對 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 檔案，且其中一個檔案含有 x-google-endpoint 擴充功能的伺服器，則所有檔案也必須定義含有相同 x-google-endpoint 擴充功能的伺服器，且伺服器網址中的主機也必須相同。不同檔案的 basepath 可能不同。

相對網址

對於 API Gateway，servers 物件中的相對網址會視為自己的 basepath，因為規格中不需要主機名稱。這與標準 OpenAPI 行為不同，後者會根據代管 OpenAPI 定義的伺服器解析相對網址。舉例來說，API Gateway 會將 url: /v1 視為 basepath。

Basepath 開頭必須為「/」。API Gateway 會拒絕沒有配置或開頭為「/」的網址，因為這表示 basepath。

不支援的擴充功能

API Gateway 不支援 OpenAPI 3.x 的 x-google-allow 擴充功能。

檔案大小限制

API Gateway 會對上傳的 OpenAPI 3.x 檔案強制執行總大小上限 10MB 和檔案數量上限 50 個。

現有限制

本節說明從 OpenAPI 2.0 沿用至 OpenAPI 3.x 的限制。

忽略的範圍

雖然 API Gateway 接受在安全性配置物件中定義範圍的 OpenAPI 文件，但 API Gateway 不會檢查或強制執行這些範圍。

多項安全性要求

API 金鑰規定：如果其中一個配置是 API 金鑰，API Gateway 就不支援其他 (邏輯 OR) 安全性要求。不過，API Gateway 支援連詞 (邏輯 AND)，因此您可以同時要求 API 金鑰和 OAuth2 權杖。
OAuth2 要求：API Gateway 支援不同 OAuth2 安全性配置的其他安全性要求 (邏輯 OR)。除非額外的安全性要求是 API 金鑰，否則 API Gateway 不支援組合 (邏輯 AND)。
選用安全性：您可以透過空白安全需求 (- {}) 讓 API 金鑰選擇性啟用安全性，但 API Gateway 不支援 OAuth。

驗證安全性定義

如果 OpenAPI 3.x 規格使用安全需求，但 securityDefinitions 區段中沒有對應的定義，API Gateway 就會拒絕該規格。

網址路徑範本

API 閘道僅支援代表整個路徑區段的網址路徑範本參數，例如 /items/{itemId}。API 閘道不支援與部分區段對應的參數 (例如 /items/prefix_{id}_suffix)，且會拒絕這類參數。

參數、結構定義、要求主體和類型

API Gateway 接受含有各種參數和類型定義的 OpenAPI 文件 (例如 required 參數和陣列格式)，但不會強制執行這些定義。無論這些定義為何，API Gateway 都會將傳入要求轉送至 API。

API Gateway 僅支援要求參數中的基本類型。

外部類型參考資料

API Gateway 不支援所提供 OpenAPI 文件以外類型的參考資料。舉例來說，API Gateway 不允許指向外部網址的 $ref，並會拒絕這類要求。

主機位址中的自訂通訊埠

API Gateway 不允許在 OpenAPI 文件的 servers.url 欄位中使用自訂通訊埠。

YAML 別名限制

提交至 API Gateway 的 OpenAPI 文件最多可有 200 個 YAML 別名節點。