Compartir vía

Restricciones de importación de API y problemas conocidos

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 realizar este ajuste mediante la API de REST API: crear o actualizar para establecer la propiedad translateRequiredQueryParameters de la API en query.

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

Limitaciones de la importación de OpenAPI/Swagger

Si recibe errores al importar su documento OpenAPI, asegúrese de validarlo previamente.

  • 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. Los nombres no distinguen mayúsculas de minúsculas.
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.
\$ref (punteros) No pueden hacer referencia a archivos externos.
Longitud máxima de la dirección URL La dirección URL de la API debe tener menos de 128 caracteres.

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.
Server (objecto) No se admite en el nivel de operación de API.
Produces (palabra clave) Describe los tipos MIME devueltos por una API.
No compatible.

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 usa la primera dirección URL HTTPS que encuentra.
  • 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:

Objeto Campo
OpenAPI externalDocs
Info summary
Componentes
  • responses
  • parameters
  • examples
  • requestBodies
  • headers
  • securitySchemes
  • links
  • callbacks
PathItem
  • trace
  • servers
operación
  • externalDocs
  • callbacks
  • security
  • servers
  • deprecated
Parámetro
  • allowEmptyValue
  • style
  • explode
  • allowReserved
  • deprecated
Plantillas de servidor
  • API Server and Base URL

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 summary no se especifica (no está presente, nullo está vacío), el valor de nombre para mostrar se establece 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.
  • Use los cuatro caracteres restantes para un sufijo de desduplicación, si es necesario, en forma de -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 intenta copiar directivas de una operación existente con el mismo método HTTP y 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.
  • Use los cuatro caracteres restantes para un sufijo de desduplicación, si es necesario, en forma de -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.

La normalización del 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 estilo de codificación "document" y "literal".
  • No se admite el estilo "rpc" ni la codificación 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

Este tipo de mensaje no se admite.

WCF wsHttpBinding

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

MTOM

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

Recursividad

  • API Management no admite tipos que se definen de forma recursiva.
  • 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 API y solicitudes de proxy 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 quiere equilibrar la carga de las solicitudes entre varios servicios y puntos de conexión, considere la posibilidad de configurar un grupo back-end con equilibrio de carga.

Matrices

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

    <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.

  • Last updated on