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 管理时。
大小限制不适用 通过 URL 将 OpenAPI 文档提供给可从 API 管理服务访问的位置时。

支持的扩展

只有以下扩展受支持:

分机 说明
x-ms-paths
  • 你可以定义通过 URL 中的查询参数区分的路径。
  • AutoRest 文档中涵盖了此内容。
x-servers 针对 OpenAPI 2 的 OpenAPI 3 servers 对象的向后移植。

不支持的扩展

分机 说明
Recursion API 管理不支持以递归方式指定的定义。
例如,引用本身的架构。
Server 对象 在 API 操作级别不支持。
Produces 关键字 描述 API 返回的 MIME 类型。
不支持。

自定义扩展插件

  • 在导入时被忽略。
  • 不会保存或保留以供导出。

不支持的定义

不支持 API 操作的内联架构定义。 架构定义:

  • 在 API 范围内定义。
  • 可在 API 操作请求或响应范围内引用。

忽略的定义

忽略安全定义。

定义限制

导入查询参数时,仅支持默认数组序列化方法(style: formexplode: true)。 有关 OpenAPI 规范中的查询参数的更多详细信息,请参阅序列化规范

不支持在 Cookie 中定义的参数。 仍然可以使用策略来解码和验证 Cookie 的内容。

OpenAPI 版本 2

OpenAPI 版本 2 支持仅限于 JSON 格式。

不支持“表单”类型参数。 仍然可以使用策略来解码和验证 application/x-www-form-urlencodedapplication/form-data 有效负载。

OpenAPI 版本 3.x

API 管理支持以下规范版本:

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:importxsd:importxsd:include 指令不受支持。 而是将依赖项合并到一个文档中。

  • 如需用于解析和合并 WSDL 文件中的 wsdl:importxsd:importxsd:include 依赖项的开源工具,请参阅 GitHub 存储库

WS-* 规范

不支持合并 WS-* 规范的 WSDL 文件。

包含多个部分的消息

不支持此消息类型。

WCF wsHttpBinding

  • 使用 Windows Communication Foundation 创建的 SOAP 服务应使用 basicHttpBinding
  • 不支持 wsHttpBinding

MTOM

  • 使用 MTOM 的服务可能会正常工作。
  • 目前暂未提供官方支持。

递归

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

多个命名空间

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

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

多个终结点

WSDL 文件可以通过一个或多个 wsdl:servicewsdl: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 导入问题。