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 perform the import. 本文将阐述这些限制,内容按照 API 的导入格式进行组织。This article documents these limitations, organized by the import format of the API. 本文还将介绍 OpenAPI 导出的工作原理。It also describes how OpenAPI export works.

OpenAPI/Swagger 导入限制 OpenAPI/Swagger import limitations

如果在导入 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.
  • 定义的 URL 参数需要是 URL 模板的一部分。A defined URL parameter needs to be part of the URL template.
  • 不支持 Produces 关键字,该关键字描述 API 返回的 MIME 类型。Produces keyword, which describes MIME types returned by an API, is not supported.

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.

OpenAPI 导入、更新和导出机制OpenAPI import, update, and export mechanisms

通过 OpenAPI 导入添加新的 APIAdd new API via OpenAPI import

对于 OpenAPI 文档中所述的每个操作,将使用 Azure 资源名称和显示名称(分别设置为 operationIdsummary)来创建新操作。For each operation found in the OpenAPI document, a new operation will be created with Azure resource name and display name set to operationId and summary respectively. 遵循下述规则规范化 operationId 值。operationId value is normalized following the rules described below. summary 值按原样导入,其长度限制为 300 个字符。summary value is imported as-is and its length is limited to 300 characters.

如果未指定 operationId(即,不存在、为 null 或为空),将会通过合并 HTTP 方法和路径模板来生成 Azure 资源名称值,例如 get-fooIf operationId isn't specified (that is, not present, null, or empty), Azure resource name value will be generated by combining HTTP method and path template, for example, get-foo.

如果未指定 summary(即,不存在、为 null 或为空),display name 值将设置为 operationIdIf summary isn't specified (that is, not present, null, or empty), display name value will set to operationId. 如果未指定 operationId,将会通过合并 HTTP 方法和路径模板来生成显示名称值,例如 Get - /fooIf operationId is not specified, display name value will be generated by combining HTTP method and path template, for example, Get - /foo.

通过 OpenAPI 导入更新现有的 APIUpdate an existing API via OpenAPI import

在导入过程中,现有的 API 将会更改,以匹配 OpenAPI 文档中所述的 API。During import existing API is changed to match API described in the OpenAPI document. 对于 OpenAPI 文档中的每个操作,会通过将其 operationId 值与现有操作的 Azure 资源名称进行比较,将其与现有的操作进行匹配。Each operation in the OpenAPI document is matched to existing operation by comparing its operationId value to Azure resource name of existing operation.

如果找到匹配项,则现有操作的属性将“就地”更新。If a match is found, existing operation’s properties will be updated "in-place".

如果找不到匹配项,将使用前面部分中所述的规则创建新操作。If a match isn't found a new operation will be created using the rules described in the section above. 对于每个新操作,导入过程会尝试从具有相同 HTTP 方法和路径模板的现有操作复制策略。For each new operation, the import will attempt to copy policies from an existing operation with the same HTTP method and path template.

所有现有的不匹配操作将被删除。All existing unmatched operations will be deleted.

若要提高导入的可预测性,请遵循以下准则:To make import more predictable please follow these guidelines:

  • 确保为每个操作指定 operationId 属性。Make sure to specify operationId property for every operation.
  • 避免在完成初始导入后更改 operationIdRefrain from changing operationId after initial import.
  • 切勿同时更改 operationId 和 HTTP 方法或路径模板。Never change operationId and HTTP method or path template at the same time.

将 API 导出为 OpenAPIExport API as OpenAPI

对于每个操作,其 Azure 资源名称将导出为 operationId,显示名称将导出为 summaryFor each operation, its Azure resource name will be exported as an operationId, and display name will be exported as a summary. operationId 的规范化规则Normalization rules for operationId

  • 转换为小写字母。Convert to lower case.
  • 将非字母数字字符的每个序列替换为一条短划线,例如,GET-/foo/{bar}?buzz={quix} 将转换为 get-foo-bar-buzz-quix-Replace each sequence of non-alphanumeric characters with a single dash, for example, GET-/foo/{bar}?buzz={quix} will be transformed into get-foo-bar-buzz-quix-.
  • 剪掉两侧的短划线,例如,get-foo-bar-buzz-quix- 将变成 get-foo-bar-buzz-quixTrim dashes on both sides, for example, get-foo-bar-buzz-quix- will become get-foo-bar-buzz-quix
  • 截断为 76 个字符:比资源名称的最大长度限制少 4 个字符。Truncate to fit 76 characters, four characters less than maximum limit for a resource name.
  • 如果需要,以 -1, -2, ..., -999 格式使用剩余的 4 个字符作为重复项删除后缀。Use remaining four characters for a deduplication suffix, if necessary, in the form of -1, -2, ..., -999.


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.