API 导入限制和已知问题API import restrictions and known issues

关于此列表About this list

导入 API 时,可能会遇到一些限制或识别问题,需要对其进行纠正才能成功导入。When importing an API, you might come across some restrictions or identify issues that need to be rectified before you can successfully import. 本文记录了这些限制或问题,并按照 API 的导入格式对其进行了组织。This article documents these, organized by the import format of the API.

OpenAPI/Swagger OpenAPI/Swagger

如果在导入 OpenAPI 文档时收到错误,请确保事先已对其进行了验证。If you're receiving errors importing your OpenAPI document, make sure you've validated it beforehand. 可以使用 Azure 门户中的设计器(设计 - 前端 - OpenAPI 规范编辑器)或使用第三方工具(例如 Swagger 编辑器)进行验证。You can do that either using the designer in the Azure portal (Design - Front End - OpenAPI Specification Editor), or with a third-party tool such as Swagger Editor.

常规 General

  • 路径和查询所需的参数必须具有唯一名称。Required parameters across both path and query must have unique names. (在 OpenAPI 中,参数名称只需要在一个位置内是唯一的,例如路径、查询、标头。(In OpenAPI a parameter name only needs to be unique within a location, for example path, query, header. 但是,在 API 管理中,我们允许操作通过路径和查询参数进行区分(OpenAPI 不支持此方法)。However, in API Management we allow operations to be discriminated by both path and query parameters (which OpenAPI doesn't support). 这就是要求参数名称在整个 URL 模板中是唯一的原因。)That's why we require parameter names to be unique within the entire URL template.)
  • $ref 指针不能引用外部文件。$ref pointers can't reference external files.
  • 仅支持 x-ms-pathsx-servers 扩展。x-ms-paths and x-servers are the only supported extensions.
  • 自定义扩展在导入时将被忽略,并且不会为导出保存或保留。Custom extensions are ignored on import and aren't saved or preserved for export.
  • 递归 - API 管理目前不支持以递归方式定义的定义(例如,引用自身的架构)。Recursion - API Management doesn't support definitions defined recursively (for example, schemas referring to themselves).
  • 源文件 URL(如果可用)应用于相对服务器 URL。Source file URL (if available) is applied to relative server URLs.
  • 忽略安全定义。Security definitions are ignored.
  • 不支持 API 操作的内联架构定义。Inline schema definitions for API operations are not supported. 架构定义在 API 范围内定义,可在 API 操作请求或响应范围内引用。Schema definitions are defined in the API scope and can be referenced in API operations request or response scopes.

OpenAPI 版本 2 OpenAPI version 2

  • 仅支持 JSON 格式。Only JSON format is supported.

OpenAPI 版本 3 OpenAPI version 3

  • 如果指定了多个服务器,API 管理将尝试选择第一个 HTTP URL 。If many servers are specified, API Management will try to select the first HTTPs URL. 如果不存在任何 HTTP URL,则为第一个 HTTP URL。If there aren't any HTTPs URLs - the first HTTP URL. 如果不存在任何 HTTP URL,则服务器 URL 将为空。If there aren't any HTTP URLs - the server URL will be empty.
  • 不支持“Examples”,但支持“example” 。Examples isn't supported, but example is.
  • 不支持“Multipart/form-data” 。Multipart/form-data isn't supported.


WSDL 文件用于创建 SOAP 传递和 SOAP到 REST API。WSDL files are used to create SOAP pass-through and SOAP-to-REST APIs.

  • SOAP 绑定 - 仅支持样式“文档”和“文本”编码的 SOAP 绑定。SOAP bindings -Only SOAP bindings of style ”document” and “literal” encoding are supported. 不支持“rpc”样式或 SOAP 编码。There is no support for “rpc” style or SOAP-Encoding.
  • WSDL:Import - 不支持此属性。WSDL:Import - This attribute isn't supported. 客户应将导入项合并到一个文档中。Customers should merge the imports into one document.
  • 包含多个部分的消息 - 不支持这些类型的消息。Messages with multiple parts - These types of messages aren't supported.
  • WCF wsHttpBinding - 使用 Windows Communication Foundation 创建的 SOAP 服务应使用 basicHttpBinding - 不支持 wsHttpBinding。WCF wsHttpBinding - SOAP services created with Windows Communication Foundation should use basicHttpBinding - wsHttpBinding isn't supported.
  • MTOM - 使用 MTOM 的服务可能正常工作。MTOM - Services using MTOM may work. 目前暂未提供官方支持。Official support isn't offered at this time.
  • 递归 - APIM 不支持以递归方式定义的类型(例如,引用这些类型本身的数组)。Recursion - Types that are defined recursively (for example, refer to an array of themselves) are not supported by APIM.
  • 多个命名空间 - 可以在架构中使用多个名称空间,但只能使用目标名称空间来定义消息部分。Multiple Namespaces - Multiple namespaces can be used in a schema, but only the target namespace can be used to define message parts. 不保留用于定义其他输入或输出元素的目标以外的命名空间。Namespaces other than the target which are used to define other input or output elements are not preserved. 虽然可以导入这样的 WSDL 文档,但在导出时,所有消息部分都将具有 WSDL 的目标命名空间。Although such a WSDL document can be imported, on export all message parts will have the target namespace of the WSDL.
  • 数组 - SOAP 到 REST 转换仅支持包装数组,如下例所示:Arrays - SOAP-to-REST transformation supports only wrapped arrays shown in the example below:
    <complexType name="arrayTypeName">
            <element name="arrayElementValue" type="arrayElementType" minOccurs="0" maxOccurs="unbounded"/>
    <complexType name="typeName">
            <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"/>


目前没有已知的 WADL 导入问题。Currently, there are no known WADL import issues.