Compartilhar via

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

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á sobre:

  • 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 essa configuração usando a API REST - Criar ou Atualizar para definir a propriedade translateRequiredQueryParameters como query da API.

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

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

Se você receber erros ao importar seu documento OpenAPI, verifique se o validou com antecedência:

  • O uso do 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 Descrição
Nomes exclusivos para os parâmetros obrigatórios de caminho e de consulta 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. Os nomes são insensíveis a diferenciações de maiúsculas e minúsculas.
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.
\$ref ponteiros Não podem referenciar arquivos externos.
Comprimento máximo da URL A URL da API deve ter menos de 128 caracteres.

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 diretamente no Gerenciamento de API.
Tamanho da solicitação da API do Azure Resource Manager Quando um documento OpenAPI é fornecido por meio de uma URL para um local acessível pelo serviço do Gerenciamento de API. Confira Limites de assinatura do Azure.

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

Quando você importa 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 informações sobre parâmetros de consulta nas especificações do OpenAPI, consulte 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 as cargas 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 encontrada.
  • 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
  • deprecated
Parâmetro
  • allowEmptyValue
  • style
  • explode
  • allowReserved
  • deprecated
Modelagem de servidor
  • API Server and Base URL

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 devem ser importadas no mesmo serviço de Gerenciamento de API ou em um serviço diferente.

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 for especificado (não presente ou nullvazio), o valor do nome de exibição será definido como operationId.

Regras de normalização para operationId

  • Converter para letras 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-.
  • Cortar os traços nos dois lados.
    • Por exemplo, get-foo-bar-buzz-quix- se tornará 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.
  • Use os quatro caracteres restantes para um sufixo de deduplicaçã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 for encontrada, as propriedades da operação existente serã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 tenta copiar políticas de uma operação existente com o mesmo 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.
  • 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-.
  • 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.
  • Use os quatro caracteres restantes para um sufixo de deduplicaçã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.

A normalização do 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 nos estilos de codificação "document" e "literal".
  • Não há suporte para estilo "rpc" ou codificação SOAP.

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

Não há suporte para esse tipo de mensagem.

WCF wsHttpBinding

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

MTOM

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

Recursão

  • O Gerenciamento de API não dá suporte a tipos definidos recursivamente.
  • 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 APIs e solicitações de proxy 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 encapsuladas mostradas no exemplo a seguir:

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

  • Last updated on