API 匯入的限制和已知問題

發行項
04/24/2024

適用於：所有 API 管理層

匯入 API 時，您可能會遇到一些限制，或必須識別並解決問題，才能成功匯入。在本文中，您將了解：

API 管理在 OpenAPI 匯入期間的行為。
OpenAPI 匯入限制，以及 OpenAPI 匯出的運作方式。
WSDL 和 WADL 匯入的需求和限制。

OpenAPI 匯入期間的 API 管理

在 OpenAPI 匯入期間，API 管理會進行下列動作：

特別檢查是否有查詢字串參數標示為必要。
根據預設，將必要的查詢字串參數轉換為必要的範本參數。

如果您想要將規格中的必要查詢參數轉譯為 APIM 中的查詢參數，則在入口網站中建立 API 時，請停用 [在作業範本中包含查詢參數] 設定。您也可以使用 API - 建立或更新 REST API，將 API 的 translateRequiredQueryParameters 屬性設定為 query 來完成此作業。

針對 GET、HEAD 和 OPTIONS 作業，API 管理會捨棄要求本文參數 (若已定義於 OpenAPI 規格中)。

OpenAPI/Swagger 匯入限制

如果您在匯入 OpenAPI 文件時收到錯誤，請確定您已透過下列任一方式事先驗證：

使用 Azure 入口網站中的設計工具 ([設計] > [前端] > [OpenAPI 規格編輯器])，或
使用協力廠商工具，例如 Swagger Editor。

一般

URL 範本需求

需求	描述
必要路徑和查詢參數的唯一名稱	在 OpenAPI 中：參數名稱只需要在某個位置內是唯一的，例如路徑、查詢、標頭。在 API 管理中：允許同時以路徑和查詢參數區分作業。 OpenAPI 不支援此區分，因此我們需要參數名稱在整個 URL 範本中為唯一。名稱不區分大小寫。
定義的 URL 參數	必須屬於 URL 範本。
可用的來源檔案 URL	套用至相對伺服器 URL。
`\$ref` 指標	無法參考外部檔案。

OpenAPI 規格

支援的版本

API 管理僅支援下列項目：

OpenAPI 第 2 版。
OpenAPI 3.0.x 版 (最高 3.0.3 版)。
OpenAPI 3.1 版 (僅匯入)

大小限制

大小限制	描述
最多 4 MB	將 OpenAPI 規格內嵌匯入至 API 管理時。
Azure Resource Manager API 要求大小	OpenAPI 文件透過可從您 API 管理服務存取的位置 URL 提供時。 Azure 訂用帳戶限制。

支援的擴充功能

僅支援的延伸模組如下：

副檔名	描述
`x-ms-paths`	可讓您定義與 URL 中查詢參數不同的路徑。在 AutoRest 文件中說明。
`x-servers`	針對 OpenAPI 2 向後移植 OpenAPI 3 `servers` 物件。

不支援的延伸模組

副檔名	描述
`Recursion`	API 管理不支援定義以遞迴方式定義。例如，參考本身的結構描述。
`Server` 物件	API 作業層級不支援。
`Produces` 關鍵字	描述 API 傳回的 MIME 類型。不支援。

自訂延伸模組

匯入時會忽略。
不會儲存或保留以供匯出。

不支援的定義

不支援 API 作業的內嵌結構描述定義。結構描述定義：

在 API 範圍中定義。
可以在 API 作業要求或回應範圍中參考。

忽略的定義

系統會忽略安全性定義。

定義限制

匯入查詢參數時，僅支援使用預設的陣列序列化方法 (style: form，explode: true)。如需 OpenAPI 規格的查詢參數詳細資料，請參閱序列化規格。

不支援定義於 Cookie 中 (英文) 的參數。您仍可使用原則來解碼和驗證 Cookie 的內容。

OpenAPI 第 2 版

OpenAPI 第 2 版支援僅限於 JSON 格式。

不支援「表單」類型參數 (英文)。您仍可使用原則來解碼和驗證 application/x-www-form-urlencoded 和 application/form-data 承載。

OpenAPI 3.x 版

API 管理支援下列規格版本：

OpenAPI 3.0.3
OpenAPI 3.1.0 (僅匯入)

HTTPS URL

如果指定多個 servers，API 管理會使用其找到的第一個 HTTPS URL。
如果沒有任何 HTTPS URL，伺服器 URL 會是空的。

支援

example

不支援

OpenAPI 3.0.x 版 (英文) 或 OpenAPI version 3.1.x (英文) 中包含下列欄位，但不支援：

Object	欄位
OpenAPI	`externalDocs`
資訊	`summary`
元件	`responses` `parameters` `examples` `requestBodies` `headers` `securitySchemes` `links` `callbacks`
PathItem	`trace` `servers`
運算	`externalDocs` `callbacks` `security` `servers`
參數	`allowEmptyValue` `style` `explode` `allowReserved`

OpenAPI 匯入、更新和匯出機制

一般

從 API 管理服務匯出的 API 定義如下：

主要針對需要進行下列呼叫的外部應用程式：呼叫 API 管理服務中裝載的 API。
不打算匯入至相同或不同的 API 管理服務。

如需在不同服務/環境間管理 API 定義的設定，請參閱搭配 Git 使用 API 管理服務的相關文件。

透過 OpenAPI 匯入新增 API

針對在 OpenAPI 文件中找到的每個作業，系統會在下列情況中建立新作業：

Azure 資源名稱設定為 operationId。
- operationId 值已正規化。
- 如果未指定 operationId (不存在、null 或空白)，則會合併 HTTP 方法和路徑範本來產生 Azure 資源名稱值。
  - 例如： get-foo 。
顯示名稱設定為 summary。
- summary 值：
  - 依現狀匯入。
  - 長度限制為 300 個字元。
- 如果未指定 summary (不存在、null 或空白)，則顯示名稱值會設定為 operationId。

operationId 的正規化規則

轉換為小寫。
以單一虛線取代每個非英數字元的序列。
- 例如，GET-/foo/{bar}?buzz={quix} 會轉換成 get-foo-bar-buzz-quix-。
修剪兩邊的虛線。
- 例如，get-foo-bar-buzz-quix- 會變成 get-foo-bar-buzz-quix
截斷以符合 76 個字元，少資源名稱上限四個字元。
如有需要，為重複資料刪除尾碼使用其餘四個字元，以 -1, -2, ..., -999 形式。

透過 OpenAPI 匯入更新現有 API

匯入期間，現有 API 作業會進行下列操作：

變更為符合 OpenAPI 文件中所述的 API。
比較其 operationId 值與現有作業的 Azure 資源名稱，比對 OpenAPI 文件中的作業。
- 如果找到相符項目，現有作業的屬性會「就地」更新。
- 如果找不到相符項目：
  - 會透過合併 HTTP 方法和路徑範本來建立新作業，例如 get-foo。
  - 針對每個新作業，匯入會嘗試從使用相同 HTTP 方法和路徑範本的現有作業複製原則。

會刪除所有現有不相符的作業。

若要讓匯入更可預測，請遵循下列指導方針：

為每個作業指定 operationId 屬性。
避免在初始匯入之後變更 operationId。
請勿同時變更 operationId 和 HTTP 方法或路徑範本。

operationId 的正規化規則

轉換為小寫。
以單一虛線取代每個非英數字元的序列。
- 例如，GET-/foo/{bar}?buzz={quix} 會轉換成 get-foo-bar-buzz-quix-。
修剪兩邊的虛線。
- 例如，get-foo-bar-buzz-quix- 會變成 get-foo-bar-buzz-quix
截斷以符合 76 個字元，少資源名稱上限四個字元。
如有需要，為重複資料刪除尾碼使用其餘四個字元，以 -1, -2, ..., -999 形式。

將 API 匯出為 OpenAPI

針對每個作業：

Azure 資源名稱會匯出為 operationId。
顯示名稱會匯出為 summary。

請注意，operationId 正規化是在匯入時完成，而不是在匯出時。

WSDL

您可以使用 WSDL 檔案，建立 SOAP 傳遞和 SOAP 至 REST API。

SOAP 繫結

只支援 "document" 和 “literal” 編碼樣式的 SOAP 繫結。
不支援 “rpc” 樣式或 SOAP 編碼。

匯入和加入

不支援 wsdl:import、xsd:import 和 xsd:include 指示詞。相反地，將相依性合併成一份文件。
如需解析和合併 WSDL 檔案中 wsdl:import、xsd:import 和 xsd:include 相依性的開放原始碼工具，請參閱此 GitHub 存放庫。

WS-* 規格

不支援併入 WS-* 規格的 WSDL 檔案。

有多個部分的訊息

不支援此訊息類型。

WCF wsHttpBinding

以 Windows Communication Foundation 建立的 SOAP 服務應使用 basicHttpBinding。
不支援 wsHttpBinding。

MTOM

使用 MTOM 的服務可能 正常運作。
目前不提供官方支援。

遞迴

APIM 不支援以遞迴方式定義的類型。
例如，參考本身的陣列。

多個命名空間

儘管可在結構描述中使用多個命名空間，但只有目標命名空間可用來定義訊息部分。這些命名空間可用來定義其他輸入或輸出元素。

目標以外的命名空間不會在匯出時保留。儘管您可以匯入 WSDL 檔案，以其他命名空間定義訊息部分，但所有訊息部分在匯出時都會有 WSDL 目標命名空間。

多個端點

WSDL 檔案可以透過一或多個 wsdl:service 和 wsdl:port 元素來定義多個服務和端點 (連接埠)。不過，APIM 閘道只能將要求匯入和 Proxy 到單一服務和端點。如果在 WSDL 檔案中定義多個服務或端點，則在使用 wsdlSelector 屬性匯入 API 時，識別目標服務名稱和端點。

提示

如果您要跨多個服務和端點對要求進行負載平衡，可考慮設定負載平衡的後端集區 (部分機器翻譯)。

陣列

SOAP 轉 REST 轉換僅支援包裝的陣列，如以下範例所示：

    <complexType name="arrayTypeName">
        <sequence>
            <element name="arrayElementValue" type="arrayElementType" minOccurs="0" maxOccurs="unbounded"/>
        </sequence>
    </complexType>
    <complexType name="typeName">
        <sequence>
            <element name="element1" type="someTypeName" minOccurs="1" maxOccurs="1"/>
            <element name="element2" type="someOtherTypeName" minOccurs="0" maxOccurs="1" nillable="true"/>
            <element name="arrayElement" type="arrayTypeName" minOccurs="1" maxOccurs="1"/>
        </sequence>
    </complexType>

WADL

目前沒有任何已知的 WADL 匯入問題。

共用方式為