API 导入限制和已知问题

项目
08/14/2024

适用于：所有 API 管理层级

导入 API 时，你可能会遇到一些限制或需要识别并纠正问题，然后才能成功导入。本文内容：

OpenAPI 导入期间的 API 管理行为。
OpenAPI 导入限制及 OpenAPI 导出的工作原理。
WSDL 和 WADL 导入的要求和限制。

OpenAPI 导入期间的 API 管理

在 OpenAPI 导入期间，API 管理会执行以下操作：

专门检查标记为必需的查询字符串参数。
默认将必需的查询字符串参数转换为必需的模板参数。

如果希望将规范中的必需查询参数转换为 API 管理中的查询参数，请在门户中创建 API 时禁用“在操作模板中包含查询参数”设置。也可以通过使用 API - 创建或更新REST API 将 API的 translateRequiredQueryParameters 属性设置为 query 来实现此目的。

对于 GET、HEAD 和 OPTIONS 操作，如果在 OpenAPI 规范中定义 API 管理，则 API 管理会放弃请求正文参数。

OpenAPI/Swagger 导入限制

如果在导入 OpenAPI 文档时收到错误，请确保事先已通过以下方式之一对该文档进行验证：

使用 Azure 门户中的设计器（“设计”>“前端”>“OpenAPI 规范编辑器”）或
使用第三方工具（例如 Swagger 编辑器）。

常规

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 资源管理器 API 请求大小	通过 URL 将 OpenAPI 文档提供给可从 API 管理服务访问的位置时。请参阅 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 3.1.x 版中，但不受支持：

对象	字段
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 定义的配置管理，请参阅有关将 API 管理服务与 Git 结合使用的文档。

通过 OpenAPI 导入添加新的 API

对于在 OpenAPI 文档中找到的每个操作，将创建一个新操作，其中：

将 Azure 资源名称设置为 operationId。
- operationId 值已规范化。
- 如果未指定 operationId（不存在、为 null 或为空），则会通过合并 HTTP 方法和路径模板来生成 Azure 资源名称值。
  - 例如，get-foo。
将显示名称设置为 summary。
- summary 值：
  - 按原样导入。
  - 长度不得超过 300 个字符。
- 如果未指定 summary（不存在、为 null 或为空），显示名称值将设置为 operationId。

的规范化规则

转换为小写字母。
将非字母数字字符的每个序列替换为一条短划线。
- 例如，GET-/foo/{bar}?buzz={quix} 将转换为 get-foo-bar-buzz-quix-。
剪裁掉两侧的短划线。
- 例如，get-foo-bar-buzz-quix- 变为 get-foo-bar-buzz-quix
截断为 76 个字符：比资源名称的最大长度限制少 4 个字符。
如果需要，以 -1, -2, ..., -999 格式使用剩余的 4 个字符作为“重复项删除”后缀。

通过 OpenAPI 导入更新现有的 API

在导入期间，现有的 API 操作：

将会更改，以匹配 OpenAPI 文档中所述的 API。
通过将 OpenAPI 文档中操作的 operationId 值与现有操作的 Azure 资源名称进行比较，以便与该文档中的操作匹配。
- 如果找到匹配项，则现有操作的属性将“就地”更新。
- 如果找不到匹配项：
  - 通过合并 HTTP 方法和路径模板来创建新操作，例如 get-foo。
  - 对于每个新操作，导入过程会尝试从具有相同 HTTP 方法和路径模板的现有操作复制策略。

所有现有的不匹配操作会被删除。

若要提高导入的可预测性，请遵循以下准则：

为每个操作指定 operationId 属性。
避免在完成初始导入后更改 operationId。
切勿同时更改 operationId 和 HTTP 方法或路径模板。

的规范化规则

转换为小写字母。
将非字母数字字符的每个序列替换为一条短划线。
- 例如，GET-/foo/{bar}?buzz={quix} 将转换为 get-foo-bar-buzz-quix-。
剪裁掉两侧的短划线。
- 例如，get-foo-bar-buzz-quix- 变为 get-foo-bar-buzz-quix
截断为 76 个字符：比资源名称的最大长度限制少 4 个字符。
如果需要，以 -1, -2, ..., -999 格式使用剩余的 4 个字符作为“重复项删除”后缀。

将 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 的服务可能会正常工作。
目前暂未提供官方支持。

递归

API 管理不支持以递归方式定义的类型。
例如，引用这些类型本身的数组。

多个命名空间

虽然可以在架构中使用多个命名空间，但只能使用目标命名空间来定义消息部分。这些命名空间用于定义其他输入或输出元素。

在导出时不会保留除目标以外的命名空间。虽然你可以导入一个 WSDL 文档，用于定义具有其他命名空间的消息部分，但所有消息部分在导出时都会有 WSDL 目标命名空间。

多个终结点

WSDL 文件可以通过一个或多个 wsdl:service 和 wsdl:port 元素来定义多个服务和终结点（端口）。但是，API 管理网关只能将请求导入和代理到单个服务和终结点。如果在 WSDL 文件中定义了多个服务或终结点，请在导入 API 时使用 wsdlSelector 属性标识目标服务名称和终结点。

提示

若要跨多个服务和终结点对请求进行负载均衡，请考虑配置负载均衡的后端池。

数组

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 导入问题。

通过