Restricciones de importación de API y problemas conocidos

  • Artículo

SE APLICA A: todos los niveles de API Management

Al importar una API, podría encontrarse con algunas restricciones o tener que identificar y corregir problemas antes de realizar esta operación correctamente. En este artículo, aprenderá lo siguiente:

  • El comportamiento de API Management durante la importación de OpenAPI.
  • Limitaciones de importación de OpenAPI y funcionamiento de la exportación de OpenAPI.
  • Requisitos y limitaciones para la importación de WSDL y WADL.

API Management durante la importación de OpenAPI

Durante la importación de OpenAPI, API Management:

  • Comprueba específicamente los parámetros de la cadena de consulta marcados como obligatorios.
  • De forma predeterminada, convierte los parámetros de cadena de consulta necesarios en los parámetros de plantilla necesarios.

Si prefiere que los parámetros de consulta necesarios en la especificación se traduzcan a parámetros de consulta en API Management, deshabilite la opción Incluir parámetros de consulta en las plantillas de operación al crear la API en el portal. También puede hacerlo mediante la API de REST API: crear o actualizar para establecer la propiedad translateRequiredQueryParameters de la API en query.

Para las operaciones GET, HEAD y OPTIONS, API Management descarta un parámetro del cuerpo de la solicitud si se define en la especificación de OpenAPI.

Limitaciones de la importación de OpenAPI/Swagger

Si recibe errores al importar el documento de OpenAPI, asegúrese de haberlo validado con antelación. Para ello:

  • Use el diseñador de Azure Portal (Diseño > Front-end > Editor de especificaciones OpenAPI) o
  • Una herramienta de terceros como Swagger Editor.

General

Requisitos de plantilla de dirección URL

Requisito Descripción
Nombres únicos de los parámetros de consulta y ruta de acceso necesarios En OpenAPI:
  • Un nombre de parámetro solo debe ser único dentro de una ubicación; por ejemplo, ruta de acceso, consulta, encabezado.
En API Management:
  • Se permite que los parámetros tanto de la ruta de acceso como de la consulta discriminen las operaciones.
  • OpenAPI no admite esta discriminación, por lo que es necesario que los nombres de parámetro sean únicos en toda la plantilla de URL.
Parámetro de dirección URL definido Debe formar parte de la plantilla de dirección URL.
Dirección URL del archivo de origen disponible Se aplica a las direcciones URL de servidor relativas.
Punteros \$ref No pueden hacer referencia a archivos externos.

Especificaciones de OpenAPI

Versiones compatibles

API Management solo admite:

  • OpenAPI versión 2.
  • OpenAPI versión 3.0.x (hasta la versión 3.0.3).
  • OpenAPI versión 3.1 (solo importación)

Limitaciones de tamaño

Límite de tamaño Descripción
Hasta 4 MB/s Cuando una especificación de OpenAPI se importa en línea a API Management.
Tamaño de solicitud de API de Azure Resource Manager Cuando se proporciona un documento de OpenAPI a través de una dirección URL a una ubicación a la que se puede acceder desde el servicio API Management. Consulte Límites de suscripción de Azure.

Extensiones admitidas

Las únicas extensiones que se admiten son:

Extensión Descripción
x-ms-paths
  • Permite definir rutas de acceso diferenciadas por parámetros de consulta en la dirección URL.
  • Se trata en la documentación de AutoRest.
x-servers Un backport del objeto servers de OpenAPI 3 para OpenAPI 2.

Extensiones no admitidas

Extensión Descripción
Recursion API Management no admite las definiciones establecidas de forma recursiva.
Por ejemplo, esquemas que hacen referencia a sí mismos.
Objeto Server No se admite en el nivel de operación de API.
Palabra clave Produces Describe los tipos MIME devueltos por una API.
No se admite.

Extensiones personalizadas

  • Se omiten en la importación.
  • No se guardan ni se conservan para la exportación.

Definiciones no admitidas

No se admiten las definiciones de esquemas alineadas para las operaciones de API. Definiciones de esquema:

  • Se definen en el ámbito de la API.
  • Se puede hacer referencia a estas en los ámbitos de solicitud o respuesta de las operaciones de API.

Definiciones omitadas

Se omiten las definiciones de seguridad.

Restricciones de definición

Al importar parámetros de consulta, solo se admite el método de serialización de matriz predeterminado (style: form, explode: true). Para obtener más información sobre los parámetros de consulta en las especificaciones de OpenAPI, consulte la especificación de serialización.

No se admiten los parámetros definidos en las cookies. Todavía puede usar la directiva para descodificar y validar el contenido de las cookies.

OpenAPI versión 2

La compatibilidad con OpenAPI versión 2 se limita solo al formato JSON.

No se admiten parámetros de tipo "Form". Todavía puede usar la directiva para descodificar y validar las cargas de trabajo application/x-www-form-urlencoded y application/form-data.

OpenAPI versión 3.x

API Management admite las siguientes versiones de especificación:

Direcciones URL HTTPS

  • Si se especifican varios servers, API Management usará la primera dirección URL HTTPS que encuentre.
  • Si no hay ninguna URL de HTTPS, la dirección URL del servidor estará vacía.

Compatible

  • example

No compatible

Los campos siguientes se incluyen tanto en OpenAPI versión 3.0.x como OpenAPI versión 3.1.x, pero no se admiten:

Object Campo
OpenAPI externalDocs
Información summary
Componentes
  • responses
  • parameters
  • examples
  • requestBodies
  • headers
  • securitySchemes
  • links
  • callbacks
PathItem
  • trace
  • servers
operación
  • externalDocs
  • callbacks
  • security
  • servers
Parámetro
  • allowEmptyValue
  • style
  • explode
  • allowReserved

OpenAPI mecanismos de importación, actualización y exportación

General

Las definiciones de API que se exportan desde un servicio API Management:

  • Están pensadas principalmente para aplicaciones externas que tienen que llamar a la API hospedada en el servicio API Management.
  • No están destinadas a importarse en este u otro servicio de API Management.

Para más información sobre la administración de la configuración de las definiciones de API en los diferentes servicios o entornos, consulte la documentación relativa al uso del servicio API Management con Git.

Incorporación de una nueva API a través de OpenAPI Import

Para cada operación que se encuentra en el documento de OpenAPI, se crea una nueva operación con:

  • Nombre del recurso de Azure establecido en operationId.

    • El valor operationId se normaliza.
    • Si no se especifica operationId (no está presente, es null, o está vacío), el valor del nombre del recurso de Azure se genera mediante la combinación del método HTTP y la plantilla de ruta de acceso.
      • Por ejemplo, get-foo.

  • Nombre para mostrar establecido en summary.

    • Valor summary:
      • Se importa tal y como está.
      • La longitud está limitada a 300 caracteres.
    • Si no se especifica summary (no está presente, es null o está vacío), el valor del nombre para mostrar se establecerá en operationId.

Reglas de normalización para operationId

  • Convertir en minúsculas.
  • Reemplace cada secuencia de caracteres no alfanuméricos por un único guion.
    • Por ejemplo, GET-/foo/{bar}?buzz={quix} se transforma en get-foo-bar-buzz-quix-.
  • Recorte los guiones en ambos lados.
    • Por ejemplo, get-foo-bar-buzz-quix- se convierte en get-foo-bar-buzz-quix
  • Se trunca para ajustar 76 caracteres, cuatro caracteres menos que el límite máximo de un nombre de recurso.
  • Utilice los cuatro caracteres restantes para un sufijo de desduplicación, si es necesario, con el formato -1, -2, ..., -999.

Actualización de una API existente a través de la importación de OpenAPI

Durante la importación, la operación de API existente:

  • Cambia para coincidir con la API descrita en el documento de OpenAPI.
  • Coincide con una operación en el documento de OpenAPI comparando su valor operationId con el nombre del recurso de Azure de la operación existente.
    • Si se encuentra una coincidencia, las propiedades de la operación existente se actualizan "en contexto".
    • Si no se encuentra una coincidencia:
      • Se crea una operación mediante la combinación del método HTTP y la plantilla de ruta de acceso, por ejemplo, get-foo.
      • Para cada nueva operación, la importación intentará copiar las directivas de una operación existente con el mismo método HTTP y la misma plantilla de ruta de acceso.

Se eliminan todas las operaciones no coincidentes existentes.

Para hacer que la importación sea más predecible, siga estas instrucciones:

  • Especifique la propiedad operationId para cada operación.
  • Absténgase de cambiar operationId después de la importación inicial.
  • Nunca cambie operationId y la plantilla del método HTTP o de la ruta de acceso al mismo tiempo.

Reglas de normalización para operationId

  • Convertir en minúsculas.
  • Reemplace cada secuencia de caracteres no alfanuméricos por un único guion.
    • Por ejemplo, GET-/foo/{bar}?buzz={quix} se transforma en get-foo-bar-buzz-quix-.
  • Recorte los guiones en ambos lados.
    • Por ejemplo, get-foo-bar-buzz-quix- se convierte en get-foo-bar-buzz-quix
  • Se trunca para ajustar 76 caracteres, cuatro caracteres menos que el límite máximo de un nombre de recurso.
  • Utilice los cuatro caracteres restantes para un sufijo de desduplicación, si es necesario, con el formato -1, -2, ..., -999.

Exportar API como OpenAPI

Para cada operación, es:

  • El nombre del recurso de Azure de la operación se exporta como operationId.
  • El nombre para mostrar se exporta como summary.

Tenga en cuenta que la normalización de operationId se realiza en la importación, no en la exportación.

WSDL

Puede crear API de tránsito de SOAP y de SOAP a REST con archivos WSDL.

Enlaces SOAP

  • Solo se admiten enlaces SOAP de "documento" y estilo de codificación "literal".
  • No se admiten las codificaciones de estilo "rpc" o SOAP.

Importaciones e inclusión

  • No se admiten las directivas wsdl:import, xsd:import y xsd:include. En su lugar, combine las dependencias en un documento.

  • Para obtener una herramienta de código abierto para resolver y combinar dependencias wsdl:import, xsd:import y xsd:include en un archivo WSDL, consulte este repositorio de GitHub.

Especificaciones de WS-*

No se admiten los archivos WSDL que incorporan especificaciones WS-*.

Mensajes con varias partes

No se admite este tipo de mensaje.

WCF wsHttpBinding

  • Los servicios SOAP creados con Windows Communication Foundation deben usar basicHttpBinding.
  • wsHttpBinding no se admite.

MTOM

  • Los servicios que usan MTOMMTOM funcionar.
  • No se ofrece soporte técnico oficial en este momento.

Recursividad

  • Los tipos definidos de forma recursiva no son compatibles con API Management.
  • Por ejemplo, una referencia a una matriz de ellos mismos.

Varios espacios de nombres

Aunque en un esquema se pueden usar varios espacios de nombres, el único que se puede usar para definir las partes del mensaje es el de destino. Estos espacios de nombres se usan para definir otros elementos de entrada o salida.

En la exportación no se conservan los espacios de nombres que no sean los de destino. Aunque puede importar un documento WSDL que defina los elementos de mensaje con otros espacios de nombres, todos los elementos de mensaje tendrán el espacio de nombres de destino WSDL en la exportación.

Varios puntos de conexión

Los archivos WSDL pueden definir varios servicios y puntos de conexión (puertos) mediante uno o varios elementos wsdl:service y wsdl:port. Sin embargo, la puerta de enlace de API Management puede importar y redirigir mediante proxy solicitudes a un único servicio y punto de conexión. Si se definen varios servicios o puntos de conexión en el archivo WSDL, identifique el nombre del servicio de destino y el punto de conexión al importar la API mediante la propiedad wsdlSelector.

Sugerencia

Si desea equilibrar la carga de las solicitudes entre varios servicios y puntos de conexión, considere la posibilidad de configurar un grupo de back-end con equilibrio de carga.

Matrices

La transformación de SOAP a REST admite solo las matrices encapsuladas que se muestran en el siguiente ejemplo:

    <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

Actualmente, no hay ningún problema de importación conocido de WADL.