Importare l'API SOAP in Gestione API

Articolo
03/25/2024

SI APPLICA A: Tutti i livelli di Gestione API

Questo articolo illustra come importare una specifica WSDL, che è una rappresentazione XML standard di un'API SOAP. Viene inoltre descritto come testare l'API in Gestione API.

In questo articolo vengono illustrate le operazioni seguenti:

Importare un'API SOAP
Testare l'API nel portale di Azure

Nota

L'importazione WSDL in Gestione API è soggetta a determinate limitazioni. I file WSDL con direttive wsdl:import, xsd:import e xsd:include non sono supportati. Per fare in modo che uno strumento open source risolva e unisca le dipendenze in un file WSDL, vedere questo repository GitHub.

Prerequisiti

Un'istanza di Gestione API. Se non è già disponibile, completare l’avvio rapido seguente: Creare un'istanza di Gestione API di Azure.
Interfaccia della riga di comando di Azure
- Usare l'ambiente Bash in Azure Cloud Shell. Per altre informazioni, vedere la Avvio rapido di Bash in Azure Cloud Shell.
- Se si preferisce eseguire i comandi di riferimento dell'interfaccia della riga di comando in locale, installare l'interfaccia della riga di comando di Azure. Per l'esecuzione in Windows o macOS, è consigliabile eseguire l'interfaccia della riga di comando di Azure in un contenitore Docker. Per altre informazioni, vedere Come eseguire l'interfaccia della riga di comando di Azure in un contenitore Docker.
  - Se si usa un'installazione locale, accedere all'interfaccia della riga di comando di Azure con il comando az login. Per completare il processo di autenticazione, seguire la procedura visualizzata nel terminale. Per altre opzioni di accesso, vedere Accedere tramite l'interfaccia della riga di comando di Azure.
  - Quando richiesto, al primo utilizzo installare l'estensione dell'interfaccia della riga di comando di Azure. Per altre informazioni sulle estensioni, vedere Usare le estensioni con l'interfaccia della riga di comando di Azure.
  - Eseguire az version per trovare la versione e le librerie dipendenti installate. Per eseguire l'aggiornamento alla versione più recente, eseguire az upgrade.
Azure PowerShell
- Se si sceglie di usare Azure PowerShell in locale:
  - Installare la versione più recente del modulo Az di PowerShell.
  - Connettersi all'account Azure con il cmdlet Connect-AzAccount.
- Se si sceglie di usare Azure Cloud Shell:
  - Vedere Panoramica di Azure Cloud Shell per altre informazioni.

Importare un'API back-end

Nel portale di Azure accedere all'istanza di Gestione API.
Nel menu a sinistra selezionare API >+ Aggiungi API.
In Crea da definizione, selezionare WSDL.
Nella specifica WSDL, immettere l'URL dell'API SOAP oppure fare clic su Seleziona un file per selezionare un file WSDL locale.
In Metodo di importazione, il pass-through SOAP è selezionato per impostazione predefinita. Con questa selezione, l'API viene esposta come SOAP e i consumer di API devono usare le regole SOAP. Se si vuole convertire l'API in REST, seguire la procedura descritta in Importare un'API SOAP e convertirla in REST.
Le impostazioni API seguenti vengono compilate automaticamente in base alle informazioni dell'API SOAP: Nome visualizzato, Nome, Descrizione. Le operazioni vengono compilate automaticamente con Nome visualizzato, URL e Descrizione e ricevono un Nome generato dal sistema.
Immettere altre impostazioni API. È possibile impostare i valori durante la creazione o configurarli successivamente passando alla scheda Impostazioni.

Per altre informazioni sulle impostazioni API, vedere Importare e pubblicare la prima esercitazione sull'API.
Seleziona Crea.

L'esempio seguente usa il comando az apim api import per importare una specifica WSDL dall'URL specificato in un'istanza di Gestione API denominata apim-hello-world. Per eseguire l’importazione usando il percorso di una specifica anziché un URL, usare il parametro --specification-path.

Per questo esempio WSDL, il nome del servizio è OrdersAPI e uno degli endpoint disponibili (interfacce) è base.

# 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

L'esempio seguente usa il cmdlet Import-AzApiManagementApi Azure PowerShell per importare una specifica WSDL dall'URL specificato in un'istanza di Gestione API denominata apim-hello-world. Per eseguire l’importazione usando il percorso di una specifica anziché un URL, usare il parametro -SpecificationPath.

Per questo esempio WSDL, il nome del servizio è OrdersAPI e uno degli endpoint disponibili (interfacce) è base.

# 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

Testare la nuova API nel portale

È possibile chiamare le operazioni direttamente dal portale, il che consente agli amministratori di visualizzare e testare facilmente le operazioni di un'API.

Selezionare l'API creata nel passaggio precedente.
Selezionare la scheda Test.
Selezionare un'operazione. La pagina visualizza campi per le intestazioni e campi per i parametri di query.

Nota

Nella console di test, Gestione API popola automaticamente un'intestazione Ocp-Apim-Subscription-Key e configura la chiave di sottoscrizione della sottoscrizione all-access integrata. Questa chiave consente l'accesso a ogni API nell'istanza di Gestione API. Facoltativamente, visualizzare l'intestazione Ocp-Apim-Subscription-Key selezionando l'icona "occhio" accanto alla richiesta HTTP.
A seconda dell'operazione, immettere i valori dei parametri di query, i valori di intestazione o il corpo della richiesta. Selezionare Invia.

Quando il test ha esito positivo, il back-end risponde con un codice di risposta HTTP corretto e alcuni dati.

Suggerimento

Per impostazione predefinita, la console di test invia una richiesta al proxy CORS di Gestione API, che inoltra la richiesta all'istanza di Gestione API, che a sua volta la inoltra al back-end. Questo proxy usa l'indirizzo IP pubblico 13.91.254.72 e può raggiungere solo gli endpoint pubblici. Per inviare una richiesta direttamente dal browser al servizio Gestione API, selezionare Ignora proxy CORS. Questa opzione è utile quando si vuole usare la console di test e il gateway di Gestione API è isolato dalla rete o non consente il traffico dal proxy CORS.

Per eseguire il debug di un’API, vedere Esercitazione: Eseguire il debug delle API usando la traccia delle richieste.

Azione SOAP con caratteri jolly

Se è necessario passare una richiesta SOAP che non dispone di un'azione dedicata definita nell'API, è possibile configurare un'azione SOAP con caratteri jolly. L'azione con caratteri jolly corrisponderà a qualsiasi richiesta SOAP non definita nell'API.

Per definire un'azione SOAP con caratteri jolly:

Nel portale, selezionare l'API creata nel passaggio precedente.
Nella scheda Progettazione selezionare + Aggiungi operazione.
Immettere un nome visualizzato per l'operazione.
Nell'URL, selezionare POST e immettere /soapAction={any} nella risorsa. Il parametro del modello all'interno delle parentesi graffe è arbitrario e non influisce sull'esecuzione.