Importar a API SOAP para o Gerenciamento de API

Artigo
08/04/2023

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

Este artigo mostra como importar uma especificação WSDL, que é uma representação XML padrão da API SOAP. O artigo também mostra como testar a API do Gerenciamento de API.

Neste artigo, você aprenderá como:

Importar uma API SOAP
Testar a API no Portal do Azure

Observação

A importação do WSDL para Gerenciamento de API está sujeita a determinadas limitações. Arquivos WSDL com diretivas wsdl:import, xsd:import e xsd:include não são compatíveis. Para uma ferramenta de código aberto resolver e mesclar essas dependências em um arquivo WSDL, consulte este repositório GitHub.

Pré-requisitos

Uma instância de Gerenciamento de API. Se você ainda não tem uma, conclua o seguinte guia de início rápido: Criar uma instância de Gerenciamento de API do Azure.
CLI do Azure
- Use o ambiente Bash no Azure Cloud Shell. Para obter mais informações, confira Início Rápido para Bash no Azure Cloud Shell.
- Se preferir executar os comandos de referência da CLI localmente, instale a CLI do Azure. Para execuções no Windows ou no macOS, considere executar a CLI do Azure em um contêiner do Docker. Para obter mais informações, confira Como executar a CLI do Azure em um contêiner do Docker.
  - Se estiver usando uma instalação local, entre com a CLI do Azure usando o comando az login. Para concluir o processo de autenticação, siga as etapas exibidas no terminal. Para ver outras opções de entrada, confira Conectar-se com a CLI do Azure.
  - Quando solicitado, instale a extensão da CLI do Azure no primeiro uso. Para obter mais informações sobre extensões, confira Usar extensões com a CLI do Azure.
  - Execute az version para localizar a versão e as bibliotecas dependentes que estão instaladas. Para fazer a atualização para a versão mais recente, execute az upgrade.
PowerShell do Azure
- Se você optar por usar o Azure PowerShell localmente:
  - Instale a versão mais recente do módulo do Az PowerShell.
  - Conecte-se à sua conta do Azure usando o cmdlet Connect-AzAccount.
- Se você optar por usar o Azure Cloud Shell:
  - Confira Visão geral do Azure Cloud Shell para obter mais informações.

Importar uma API de back-end

No portal do Azure, navegue até a instância do Gerenciamento de API.
No menu à esquerda, selecione APIs >+ Adicionar API.
Em Criar com base na definição, selecione WSDL.
Na especificação WSDL, insira a URL para sua API SOAP ou clique em Selecionar um arquivo para selecionar um arquivo WSDL local.
Em Importar método, a passagem SOAP é selecionada por padrão. Com essa seleção, a API é exposta como SOAP, e os consumidores da API têm que usar regras SOAP. Se você quiser "restify" a API, siga as etapas em Import a SOAP API and convert it to REST (Importar uma API SOAP e convertê-la para REST).
As configurações de API a seguir são preenchidas automaticamente com informações da API SOAP: Nome de exibição, Nome, Descrição. As operações são preenchidas automaticamente com Nome de exibição, URL e Descriçãoe recebem um Nome gerado pelo sistema.
Insira outras configurações de API. Você pode definir os valores durante a criação ou configurá-los mais tarde, acessando a guia Configurações.

Para obter mais informações sobre configurações de API, confira o tutorial Importar e publicar sua primeira API.
Selecione Criar.

O exemplo a seguir usa o comando az apim api import para importar uma especificação WSDL da URL especificada para uma instância de Gerenciamento de API chamada apim-hello-world. Para importar usando um caminho para uma especificação em vez de uma URL, use o parâmetro --specification-path.

Para este exemplo de WSDL, o nome do serviço é OrdersAPI e um dos pontos de extremidade disponíveis (interfaces) é básico.

# API Management service-specific details
APIMServiceName="apim-hello-world"
ResourceGroupName="myResourceGroup"

# API-specific details
APIId="order-api"
APIPath="order"
SpecificationFormat="Wsdl"
SpecificationURL="https://fazioapisoap.azurewebsites.net/FazioService.svc?singleWsdl"
WsdlServiceName="OrdersAPI"
WsdlEndpointName="basic"

# Import API
az apim api import --path $APIPath --resource-group $ResourceGroupName \
    --service-name $APIMServiceName --api-id $APIId \
    --specification-format $SpecificationFormat --specification-url $SpecificationURL \
    --wsdl-service-name $WsdlServiceName --wsdl-endpoint-name $WsdlEndpointName

O exemplo a seguir usa o comando Import-AzApiManagementApi do Azure PowerShell para importar uma especificação WSDL da URL especificada para uma instância de Gerenciamento de API chamada apim-hello-world. Para importar usando um caminho para uma especificação em vez de uma URL, use o parâmetro -SpecificationPath.

Para este exemplo de WSDL, o nome do serviço é OrdersAPI e um dos pontos de extremidade disponíveis (interfaces) é básico.

# API Management service-specific details
$apimServiceName = "apim-hello-world"
$resourceGroupName = "myResourceGroup"

# API-specific det
$apiId = "orders-api"
$apiPath = "orders"
$specificationFormat = "Wsdl"
$specificationUrl = "https://fazioapisoap.azurewebsites.net/FazioService.svc?singleWsdl"
$wsdlServiceName = "OrdersAPI"
$wsdlEndpointName = "basic"

# Get context of the API Management instance. 
$context = New-AzApiManagementContext -ResourceGroupName $resourceGroupName -ServiceName $apimServiceName

# Import API
Import-AzApiManagementApi -Context $context -ApiId $apiId -SpecificationFormat $specificationFormat -SpecificationUrl $specificationUrl -Path $apiPath -WsdlServiceName $wsdlServiceName -WsdlEndpointName $wsdlEndpointName

Testar a nova API no portal

As operações podem ser chamadas diretamente do portal, que fornece uma maneira conveniente para administradores exibirem e testarem as operações de uma API.

Selecione a API que você criou na etapa anterior.
Selecione a guia Testar.
Selecione uma operação. A página exibe os campos dos parâmetros de consulta e os campos dos cabeçalhos.

Observação

No console de teste, o Gerenciamento de API preenche automaticamente um cabeçalho Ocp-Apim-Subscription-Key e configura a chave de assinatura da assinatura interna de acesso total. Essa chave permite o acesso a todas as API na instância de Gerenciamento de API. Opcionalmente, exiba o cabeçalho Ocp-Apim-Subscription-Key selecionando o ícone "olho" ao lado da Solicitação HTTP.
Dependendo da operação, insira valores de parâmetro de consulta, valores de cabeçalho ou um corpo da solicitação. Selecione Enviar.

Quando o teste é bem-sucedido, o back-end responde com um código de resposta HTTP bem-sucedido e alguns dados.

Dica

Por padrão, o console de teste envia uma solicitação para o proxy CORS do Gerenciamento de API, que encaminha a solicitação para a instância Gerenciamento de API, que a encaminha para o back-end. Esse proxy usa o endereço de IP público 13.91.254.72 e só pode alcançar pontos de extremidade públicos. Se você quiser enviar uma solicitação diretamente do navegador para o serviço Gerenciamento de API, selecione Ignorar proxy CORS. Use essa opção quando quiser usar o console de teste e o gateway do Gerenciamento de API estiver isolado na rede ou não permitir o tráfego do proxy CORS.

Para depurar uma API, confira o Tutorial: Depurar suas APIs usando o rastreamento de solicitações.

Ação de SOAP curinga

Se você precisar passar uma solicitação de SOAP que não tenha uma ação dedicada definida na API, poderá configurar uma ação de SOAP curinga. A ação curinga corresponderá a qualquer solicitação de SOAP que não está definida na API.

Para definir uma ação de SOAP curinga:

No portal, selecione a API que você criou na etapa anterior.
Na guia Design, selecione + Adicionar Operação.
Insira um Nome de exibição para a operação.
Em URL, selecione POST e insira /soapAction={any} no recurso. O parâmetro de modelo dentro dos colchetes é arbitrário e não afeta a execução.