Partilhar via

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

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ê aprende sobre:

  • 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 da 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 essa configuração 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 ele estiver 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 validá-lo previamente:

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

Geral

Requisitos do modelo de URL

Requisito Descrição
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 âmbito do 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. Os nomes não são sensíveis a maiúsculas ou minúsculas.
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.
Comprimento máximo do URL O URL da API deve ter menos de 128 caracteres.

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 Descrição
Até 4 MB Quando uma especificação OpenAPI é importada em linha para o Gerenciamento de API.
Tamanho da solicitação da API do Azure Resource Manager 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. Consulte Limites de subscrição do Azure.

Extensões suportadas

As únicas extensões suportadas são:

Extensão Descrição
x-ms-paths
  • Permite definir caminhos diferenciados por parâmetros de consulta na URL.
  • Mencionado nas documentações do AutoRest.
x-servers Um backport do servers para OpenAPI 2.

Extensões não suportadas

Extensão Descrição
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

Quando você importa parâmetros de consulta, somente o método de serialização de matriz padrão (style: form, explode: true) é suportado. Para obter mais informações 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 e application/form-data cargas.

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:

Objeto Campo
OpenAPI externalDocs
Informação 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 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 para 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 hífen.
    • Por exemplo, GET-/foo/{bar}?buzz={quix} é transformado em get-foo-bar-buzz-quix-.
  • Remova traços de ambos os lados.
    • Por exemplo, get-foo-bar-buzz-quix- passa a 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 desduplicaçã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".
    • Caso não seja encontrada uma correspondência:
      • 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 tenta 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 propriedade para cada operação.
  • Abster-se de mudar operationId após a importação inicial.
  • Nunca altere operationId e 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 hífen.
    • Por exemplo, GET-/foo/{bar}?buzz={quix} é transformado em get-foo-bar-buzz-quix-.
  • Remova traços de 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 desduplicaçã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 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

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 oferece suporte para o estilo RPC ou a codificação SOAP.

Importa e inclui

  • As diretivas wsdl:import, xsd:import e 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 basicHttpBinding.
  • wsHttpBinding não é suportado.

MTOM

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

Recursão

  • O Gerenciamento de API não oferece suporte a tipos definidos recursivamente.
  • 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 pontos finais

Os ficheiros 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 Gestão de API é capaz de importar APIs e encaminhar 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 .

Gorjeta

Se pretender distribuir a carga das solicitações por vários serviços e endpoints, 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 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 conhecidos de importação de WADL.

  • Last updated on