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

  • Artigo

APLICA-SE A: todas as camadas do Gerenciamento de API

Ao importar uma API, você pode se deparar com algumas restrições ou identificar problemas que precisam ser corrigidos antes de poder importar com êxito. Neste artigo, você aprenderá o seguinte:

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

Gerenciamento de API durante a importação de OpenAPI

Durante a importação de OpenAPI, o Gerenciamento de API:

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

Se preferir que os parâmetros de consulta obrigatórios na especificação sejam convertidos em parâmetros de consulta no Gerenciamento de API, desabilite 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 as APIs – Criar ou atualizar a API REST para definir a propriedade translateRequiredQueryParameters da API como query.

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

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

Caso receba erros ao importar seu documento da OpenAPI, verifique se você o validou com antecedência por meio de uma das seguintes opções:

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

Geral

Requisitos do modelo de URL

Requisito Descrição
Nomes exclusivos dos parâmetros obrigatórios de consulta e de caminho Na OpenAPI:
  • Um nome de parâmetro só precisa ser exclusivo em uma localização, por exemplo, caminho, consulta, cabeçalho.
No Gerenciamento de API:
  • Permitimos que as operações sejam discriminadas por parâmetros de caminho e de consulta.
  • Como a OpenAPI não dá suporte a essa discriminação, exigimos que os nomes de parâmetro sejam exclusivos em todo o modelo de URL.
Parâmetro de URL definido Deve fazer parte do modelo de URL.
URL do arquivo de origem disponível Aplicado a URLs de servidor relativas.
Ponteiros \$ref Não podem referenciar arquivos externos.

Especificações da OpenAPI

Versões com suporte

O Gerenciamento de API só dá suporte a:

  • 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 Descrição
Até 4 MB Quando uma especificação OpenAPI é importada embutida para o Gerenciamento de API.
O limite de tamanho não se aplica Quando um documento OpenAPI é fornecido por meio de uma URL para um local acessível pelo serviço do Gerenciamento de API.

Extensões com suporte

As únicas extensões com suporte são:

Extensão Descrição
x-ms-paths
  • Permite que você defina caminhos que são diferenciados pelos parâmetros de consulta na URL.
  • Abordados nos documentos do AutoRest.
x-servers Um backport do objeto OpenAPI 3 serverspara OpenAPI 2.

Extensões sem suporte

Extensão Descrição
Recursion O Gerenciamento de API não dá suporte a definições definidas recursivamente.
Por exemplo, esquemas referindo-se a si mesmos.
Objeto Server Não suportado no nível de operação da API.
Palavra-chave Produces Descreve os tipos MIME retornados por uma API.
Não há suporte.

Extensões personalizadas

  • São ignoradas na importação.
  • Não são salvas ou preservadas para exportação.

Definições sem suporte

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

  • São definidos no escopo da API.
  • Podem ser referenciados nos escopos de resposta ou na solicitação 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, há suporte apenas para o método de serialização de matriz padrão (style: form, explode: true). Para obter mais detalhes sobre parâmetros de consulta nas especificações do OpenAPI, confira a especificação de serialização.

Não há suporte para os parâmetros definidos em cookies. Você ainda pode usar a política para decodificar e validar o conteúdo dos cookies.

OpenAPI versão 2

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

Não há suporte para os parâmetros de tipo "Form". Você ainda pode usar a política para decodificar e validar os conteúdos application/x-www-form-urlencoded e application/form-data.

OpenAPI versão 3.x

O Gerenciamento de API dá suporte às seguintes versões de especificação:

URLs de HTTPS

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

Com suporte

  • example

Sem suporte

Os seguintes campos estão incluídos no OpenAPI versão 3.0.x ou no OpenAPI versão 3.1.x, mas não há suporte para eles:

Objeto Campo
OpenAPI externalDocs
Informações 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 do OpenAPI

Geral

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

  • Destinada, principalmente, a aplicativos externos que precisem chamar a API hospedada no serviço de Gerenciamento de API.
  • Não destinadas a serem importadas novamente para o mesmo serviço, ou para serviço diferente, do Gerenciamento de API.

Para o gerenciamento de configuração de definições de API em diferentes serviços/ambientes, veja a documentação sobre como usar o serviço de Gerenciamento de API com o Git.

Adicionar nova API por meio da importação de OpenAPI

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

  • Nome de recurso do Azure definido como operationId.

    • O valor operationId é normalizado.
    • Se operationId não estiver especificado (não estiver presente, null ou estiver vazio), o valor do nome do recurso do Azure será gerado combinando o método HTTP e o modelo de caminho.
      • Por exemplo, get-foo.

  • Nome de exibição definido como summary.

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

Regras de normalização para operationId

  • Converter para letras minúsculas.
  • Substituir 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-.
  • Cortar os traços nos dois lados.
    • Por exemplo, get-foo-bar-buzz-quix- passa a ser get-foo-bar-buzz-quix
  • Truncar para se ajustar a 76 caracteres, com quatro caracteres a menos que o limite máximo para um nome de recurso.
  • Usar 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 por meio da importação do OpenAPI

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

  • Altera-se para corresponder à API descrita no documento da OpenAPI.
  • Corresponde a uma operação no documento da OpenAPI, comparando seu valor operationId com o nome de recurso do Azure da operação existente.
    • Se uma correspondência é encontrada, as propriedades da operação existente são atualizadas "in-loco".
    • Se não for encontrada uma correspondência:
      • Uma 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 os mesmos método HTTP e modelo de caminho.

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

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

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

Regras de normalização para operationId

  • Converter para letras minúsculas.
  • Substituir 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-.
  • Cortar os traços nos dois lados.
    • Por exemplo, get-foo-bar-buzz-quix- passa a ser get-foo-bar-buzz-quix
  • Truncar para se ajustar a 76 caracteres, com quatro caracteres a menos que o limite máximo para um nome de recurso.
  • Usar 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

Em cada operação, isso é:

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

Observe que a normalização de operationId é feita na importação, não na exportação.

WSDL

É possível criar a passagem SOAP e as APIs SOAP para REST com arquivos WSDL.

Associações SOAP

  • Há suporte apenas para associações SOAP de estilo de codificação "document" e "literal".
  • Sem suporte para estilo "rpc" ou SOAP-Encoding.

Importa e inclui

  • As diretivas wsdl:import, xsd:import e xsd:include não têm suporte. Em vez disso, mescle as dependências em um documento.

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

Especificações WS-*

Não há suporte para arquivos WSDL que incorporam especificações WS-*.

Mensagens com várias partes

Esse tipo de mensagem não possui suporte.

WCF wsHttpBinding

  • Serviços SOAP criados com o Windows Communication Foundation deverão usar basicHttpBinding.
  • Não há suporte para wsHttpBinding.

MTOM

  • Serviços que usam MTOMpodem funcionar.
  • No momento, não oferecemos suporte oficial.

Recursão

  • Não há suporte para os tipos definidos recursivamente no Gerenciamento de API.
  • Por exemplo, referenciar a uma matriz de si mesmo.

Vários namespaces

Enquanto vários namespaces podem ser usados em um esquema, apenas 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.

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

Vários pontos de extremidade

Os arquivos WSDL podem definir vários serviços e pontos de extremidade (portas) por um ou mais elementos wsdl:service e wsdl:port. No entanto, o gateway de Gerenciamento de API é capaz de importar e proxy 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.

Dica

Se você quiser fazer o balanceamento de carga das solicitações em vários serviços e pontos de extremidade, configure um pool de back-end com balanceamento de carga.

matrizes

A transformação SOAP para REST dá suporte apenas a matrizes empacotadas mostradas no seguinte exemplo:

    <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 de importação de WADL conhecidos.