Restrições de importação de APIs e problemas conhecidos

  • Artigo

APLICA-SE A: Todas as camadas de gerenciamento de API

Ao importar uma API, você pode encontrar algumas restrições ou precisar identificar e corrigir problemas antes de poder importar com êxito. Neste artigo, você aprenderá:

  • Comportamento do Gerenciamento de API durante a importação do OpenAPI.
  • Limitações de importação da OpenAPI e como funciona a exportação da OpenAPI.
  • Requisitos e limitações para importação de WSDL e WADL.

Gerenciamento de API durante a importação de OpenAPI

Durante a importação do OpenAPI, a Gestão de API:

  • Verifica especificamente os parâmetros da cadeia de consulta marcados como necessários.
  • Por padrão, converte os parâmetros de cadeia de caracteres de consulta necessários em parâmetros de modelo necessários.

Se preferir que os parâmetros de consulta necessários na especificação sejam convertidos em parâmetros de consulta no Gerenciamento de API, desative a configuração Incluir parâmetros de consulta em modelos de operação ao criar a API no portal. Você também pode fazer isso usando APIs - Criar ou Atualizar API REST para definir a propriedade da translateRequiredQueryParameters API como query.

Para operações GET, HEAD e OPTIONS, o Gerenciamento de API descarta um parâmetro de corpo de solicitação se definido na especificação OpenAPI.

Limitações de importação do OpenAPI/Swagger

Se você receber erros ao importar seu documento OpenAPI, certifique-se de tê-lo validado previamente:

  • Usando o designer no portal do Azure (Design > Front End > OpenAPI Specification Editor) ou
  • Com uma ferramenta de terceiros, como o Swagger Editor.

Geral

Requisitos do modelo de URL

Requisito Description
Nomes exclusivos para os parâmetros de caminho e consulta necessários Em OpenAPI:
  • Um nome de parâmetro só precisa ser exclusivo dentro de um local, por exemplo, caminho, consulta, cabeçalho.
No Gerenciamento de API:
  • Permitimos que as operações sejam discriminadas por parâmetros de caminho e consulta.
  • A OpenAPI não suporta essa discriminação, por isso exigimos que os nomes dos parâmetros sejam exclusivos dentro de todo o modelo de URL.
Parâmetro de URL definido Deve fazer parte do modelo de URL.
URL do ficheiro de origem disponível Aplicado a URLs de servidor relativas.
\$ref ponteiros Não é possível fazer referência a arquivos externos.

Especificações OpenAPI

Versões suportadas

O Gerenciamento de API suporta apenas:

  • OpenAPI versão 2.
  • OpenAPI versão 3.0.x (até a versão 3.0.3).
  • OpenAPI versão 3.1 (somente importação)

Limitações de tamanho

Limite de tamanho Description
Até 4 MB Quando uma especificação OpenAPI é importada em linha para o Gerenciamento de API.
O limite de tamanho não se aplica Quando um documento OpenAPI é fornecido através de uma URL para um local acessível a partir do seu serviço de Gerenciamento de API.

Extensões suportadas

As únicas extensões suportadas são:

Extensão Description
x-ms-paths
  • Permite definir caminhos diferenciados por parâmetros de consulta na URL.
  • Coberto nos documentos do AutoRest.
x-servers Um backport do objeto OpenAPI 3 servers para OpenAPI 2.

Extensões não suportadas

Extensão Description
Recursion O Gerenciamento de API não suporta definições definidas recursivamente.
Por exemplo, esquemas que se referem a si mesmos.
Server objeto Não suportado no nível de operação da API.
Produces palavra-chave Descreve os tipos MIME retornados por uma API.
Não suportado.

Extensões personalizadas

  • São ignorados na importação.
  • Não são guardados ou preservados para exportação.

Definições não suportadas

Não há suporte para definições de esquema embutido para operações de API. Definições de esquema:

  • São definidos no escopo da API.
  • Pode ser referenciado em escopos de solicitação ou resposta de operações de API.

Definições ignoradas

As definições de segurança são ignoradas.

Restrições de definição

Ao importar parâmetros de consulta, somente o método de serialização de matriz padrão (style: form, explode: true) é suportado. Para obter mais detalhes sobre parâmetros de consulta nas especificações OpenAPI, consulte a especificação de serialização.

Os parâmetros definidos nos cookies não são suportados. Você ainda pode usar a política para decodificar e validar o conteúdo dos cookies.

OpenAPI versão 2

O suporte à OpenAPI versão 2 é limitado apenas ao formato JSON.

Os parâmetros de tipo "Formulário" não são suportados. Você ainda pode usar a política para decodificar e validar application/x-www-form-urlencoded cargas application/form-data úteis.

OpenAPI versão 3.x

O Gerenciamento de API suporta as seguintes versões de especificação:

HTTPS URLs

  • Se vários servers forem especificados, o Gerenciamento de API usará a primeira URL HTTPS encontrada.
  • Se não houver URLs HTTPS, a URL do servidor estará vazia.

Suportado

  • example

Não suportado

Os seguintes campos estão incluídos no OpenAPI versão 3.0.x ou OpenAPI versão 3.1.x, mas não são suportados:

Object Campo
OpenAPI externalDocs
Informação summary
Componentes
  • responses
  • parameters
  • examples
  • requestBodies
  • headers
  • securitySchemes
  • links
  • callbacks
PathItem
  • trace
  • servers
Operação
  • externalDocs
  • callbacks
  • security
  • servers
Parâmetro
  • allowEmptyValue
  • style
  • explode
  • allowReserved

Mecanismos de importação, atualização e exportação OpenAPI

Geral

As definições de API exportadas de um serviço de Gerenciamento de API são:

  • Destina-se principalmente a aplicativos externos que precisam chamar a API hospedada no serviço de Gerenciamento de API.
  • Não se destina a ser importado para o mesmo ou diferente serviço de Gerenciamento de API.

Para obter o gerenciamento de configuração de definições de API em diferentes serviços/ambientes, consulte a documentação sobre o uso do serviço de Gerenciamento de API com o Git.

Adicionar nova API via importação OpenAPI

Para cada operação encontrada no documento OpenAPI, uma nova operação é criada com:

  • Nome do recurso do Azure definido como operationId.

    • operationId valor é normalizado.
    • Se operationId não for especificado (não presente nullou vazio), o valor do nome do recurso do Azure é gerado pela combinação do método HTTP e do modelo de caminho.
      • Por exemplo, get-foo.

  • Nome para exibição definido como summary.

    • summary Valor:
      • Importado no estado em que se encontra.
      • O comprimento é limitado a 300 caracteres.
    • Se summary não for especificado (não presente nullou vazio), o valor do nome de exibição será definido como operationId.

Regras de normalização para operationId

  • Converter em minúsculas.
  • Substitua cada sequência de caracteres não alfanuméricos por um único traço.
    • Por exemplo, GET-/foo/{bar}?buzz={quix} é transformado em get-foo-bar-buzz-quix-.
  • Corte traços em ambos os lados.
    • Por exemplo, get-foo-bar-buzz-quix- torna-se get-foo-bar-buzz-quix
  • Truncar para caber 76 caracteres, quatro caracteres a menos do que o limite máximo para um nome de recurso.
  • Use os quatro caracteres restantes para um sufixo de eliminação de duplicação, se necessário, na forma de -1, -2, ..., -999.

Atualizar uma API existente através da importação OpenAPI

Durante a importação, a operação de API existente:

  • Alterações para corresponder à API descrita no documento OpenAPI.
  • Corresponde a uma operação no documento OpenAPI comparando seu operationId valor com o nome do recurso do Azure da operação existente.
    • Se uma correspondência for encontrada, as propriedades da operação existente serão atualizadas "in-loco".
    • Se uma correspondência não for encontrada:
      • Uma nova operação é criada combinando o método HTTP e o modelo de caminho, por exemplo, get-foo.
      • Para cada nova operação, a importação tentará copiar políticas de uma operação existente com o mesmo método HTTP e modelo de caminho.

Todas as operações incomparáveis existentes são excluídas.

Para tornar a importação mais previsível, siga estas diretrizes:

  • Especifique operationId a propriedade para cada operação.
  • Abster-se de mudar operationId após a importação inicial.
  • Nunca altere operationId o método HTTP ou o modelo de caminho ao mesmo tempo.

Regras de normalização para operationId

  • Converter em minúsculas.
  • Substitua cada sequência de caracteres não alfanuméricos por um único traço.
    • Por exemplo, GET-/foo/{bar}?buzz={quix} é transformado em get-foo-bar-buzz-quix-.
  • Corte traços em ambos os lados.
    • Por exemplo, get-foo-bar-buzz-quix- torna-se get-foo-bar-buzz-quix
  • Truncar para caber 76 caracteres, quatro caracteres a menos do que o limite máximo para um nome de recurso.
  • Use os quatro caracteres restantes para um sufixo de eliminação de duplicação, se necessário, na forma de -1, -2, ..., -999.

Exportar API como OpenAPI

Para cada operação, é:

  • O nome do recurso do Azure é exportado como um operationIdarquivo .
  • O nome de exibição é exportado como um summaryarquivo .

Note-se que a normalização do operationId é feita na importação, não na exportação.

WSDL

Você pode criar APIs SOAP pass-through e SOAP-to-REST com arquivos WSDL.

Ligações SOAP

  • Somente ligações SOAP de estilo de codificação "documento" e "literal" são suportadas.
  • Não há suporte para o estilo "rpc" ou codificação SOAP.

Importa e inclui

  • As wsdl:importdiretivas , xsd:importe xsd:include não são suportadas. Em vez disso, mescle as dependências em um documento.

  • Para obter uma ferramenta de código aberto para resolver e mesclar wsdl:import, xsd:importe xsd:include dependências em um arquivo WSDL, consulte este repositório GitHub.

Especificações WS-*

Arquivos WSDL que incorporam especificações WS-* não são suportados.

Mensagens com várias partes

Este tipo de mensagem não é suportado.

WCF wsHttpBinding

  • Os serviços SOAP criados com o Windows Communication Foundation devem usar basicHttpBindingo .
  • wsHttpBinding não é suportado.

MTOM

  • Os serviços que utilizam MTOMpodem funcionar.
  • O suporte oficial não é oferecido no momento.

Recursão

  • Os tipos definidos recursivamente não são suportados pelo Gerenciamento de API.
  • Por exemplo, refere-se a uma matriz de si mesmos.

Vários namespaces

Embora vários namespaces possam ser usados em um esquema, somente o namespace de destino pode ser usado para definir partes da mensagem. Esses namespaces são usados para definir outros elementos de entrada ou saída.

Namespaces diferentes do destino não são preservados na exportação. Embora você possa importar um documento WSDL definindo partes de mensagem com outros namespaces, todas as partes de mensagem terão o namespace de destino WSDL na exportação.

Vários parâmetros de avaliação

Os arquivos WSDL podem definir vários serviços e pontos de extremidade (portas) por um ou mais wsdl:servicewsdl:port elementos. No entanto, o gateway de Gerenciamento de API é capaz de importar e fazer proxy de solicitações para apenas um único serviço e ponto de extremidade. Se vários serviços ou pontos de extremidade forem definidos no arquivo WSDL, identifique o nome do serviço de destino e o ponto de extremidade ao importar a API usando a propriedade wsdlSelector .

Gorjeta

Se você quiser balancear a carga de solicitações em vários serviços e pontos de extremidade, considere configurar um pool de back-end com balanceamento de carga.

Matrizes

A transformação SOAP-to-REST suporta apenas matrizes encapsuladas mostradas no exemplo abaixo:

    <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

Atualmente, não há problemas conhecidos de importação de WADL.