Importieren der SOAP-API in API Management

Artikel
11/05/2024

GILT FÜR: Alle API Management-Ebenen

Dieser Artikel zeigt, wie Sie eine WSDL-Spezifikation (eine standardmäßige XML-Darstellung einer SOAP-API) importieren. Der Artikel zeigt außerdem, wie Sie die API in API Management testen.

In diesem Artikel werden folgende Vorgehensweisen behandelt:

Importieren einer SOAP-API
Testen der API im Azure-Portal

Hinweis

Der WSDL-Import in API Management unterliegt bestimmten Einschränkungen. WSDL-Dateien mit den Anweisungen wsdl:import, xsd:import und xsd:include werden nicht unterstützt. Ein Open-Source-Tool zum Auflösen und Zusammenführen dieser Abhängigkeiten in einer WSDL-Datei finden Sie in diesem GitHub-Repository.

Voraussetzungen

Eine API Management-Instanz. Falls Sie nicht bereits über einen API Management-Dienst verfügen, arbeiten Sie die folgende Schnellstartanleitung durch: Erstellen einer Azure API Management-Instanz.
Azure CLI
- Verwenden Sie die Bash-Umgebung in Azure Cloud Shell. Weitere Informationen finden Sie unter Schnellstart für Bash in Azure Cloud Shell.
- Wenn Sie CLI-Referenzbefehle lieber lokal ausführen, installieren Sie die Azure CLI. Wenn Sie Windows oder macOS ausführen, sollten Sie die Azure CLI in einem Docker-Container ausführen. Weitere Informationen finden Sie unter Ausführen der Azure CLI in einem Docker-Container.
  - Wenn Sie eine lokale Installation verwenden, melden Sie sich mithilfe des Befehls az login bei der Azure CLI an. Führen Sie die in Ihrem Terminal angezeigten Schritte aus, um den Authentifizierungsprozess abzuschließen. Informationen zu anderen Anmeldeoptionen finden Sie unter Anmelden mit der Azure CLI.
  - Installieren Sie die Azure CLI-Erweiterung beim ersten Einsatz, wenn Sie dazu aufgefordert werden. Weitere Informationen zu Erweiterungen finden Sie unter Verwenden von Erweiterungen mit der Azure CLI.
  - Führen Sie az version aus, um die installierte Version und die abhängigen Bibliotheken zu ermitteln. Führen Sie az upgrade aus, um das Upgrade auf die aktuelle Version durchzuführen.
Azure PowerShell
- Bei lokaler Verwendung von Azure PowerShell:
  - Installieren der aktuellen Version des Az PowerShell-Moduls.
  - Stellen Sie eine Verbindung mit Ihrem Azure-Konto mit dem Cmdlet Connect-AzAccount her.
- Bei Verwendung von Azure Cloud Shell:
  - Weitere Informationen finden Sie in der Übersicht über Azure Cloud Shell.

Importieren einer Back-End-API

Navigieren Sie im Azure-Portal zu Ihrer API Management-Instanz.
Wählen Sie im linken Menü APIs> + API hinzufügen aus.
Wählen Sie unter Create from definition (Aus Definition erstellen) die Option WSDL aus.
Geben Sie unter WSDL-Spezifikation die URL zu Ihrer SOAP-API ein, oder klicken Sie auf Datei auswählen, um eine lokale WSDL-Datei auszuwählen.
Unter Importmethode ist standardmäßig SOAP-Passthrough ausgewählt. Bei dieser Auswahl wird die API als SOAP verfügbar gemacht, und API-Consumer müssen SOAP-Regeln verwenden. Wenn Sie die API „korrigieren“ möchten, führen Sie die Schritte in Importieren einer SOAP-API und Konvertieren dieser in REST aus.
Die folgenden API-Einstellungen werden automatisch anhand der Informationen aus der SOAP-API aufgefüllt: Anzeigename, Name, Beschreibung. Vorgänge werden automatisch mit Anzeigename, URL und Beschreibung ausgefüllt und erhalten einen vom System generierten Namen.
Geben Sie weitere API-Einstellungen ein. Sie können die Werte während der Erstellung festlegen oder später über die Registerkarte Einstellungen konfigurieren.

Weitere Informationen zu API-Einstellungen finden Sie im Tutorial Importieren und Veröffentlichen Ihrer ersten API.
Klicken Sie auf Erstellen.

Im folgenden Beispiel wird der Befehl az apim api import verwendet, um eine WSDL-Spezifikation aus der angegebenen URL in eine API Management-Instanz namens apim-hello-world zu importieren. Verwenden Sie den Parameter --specification-path, um für den Import statt einer URL einen Pfad zu einer Spezifikation zu verwenden.

In diesem WSDL-Beispiel lautet der Dienstname OrdersAPI, und einer der verfügbaren Endpunkte (Schnittstellen) ist basic.

# 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

Im folgenden Beispiel wird das Azure PowerShell-Cmdlet Import-AzApiManagementApi verwendet, um eine WSDL-Spezifikation aus der angegebenen URL in eine API Management-Instanz namens apim-hello-world zu importieren. Verwenden Sie den Parameter -SpecificationPath, um für den Import statt einer URL einen Pfad zu einer Spezifikation zu verwenden.

In diesem WSDL-Beispiel lautet der Dienstname OrdersAPI, und einer der verfügbaren Endpunkte (Schnittstellen) ist basic.

# 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

Testen der neuen API im Portal

Vorgänge können direkt aus dem Portal aufgerufen werden. Dies ist für Administratoren eine einfache Möglichkeit, die Vorgänge einer API anzuzeigen und zu testen.

Wählen Sie die API aus, die Sie im vorherigen Schritt erstellt haben.
Wählen Sie die Registerkarte Testen aus.
Wählen Sie einen Vorgang aus. Die Seite zeigt Felder für Abfrageparameter und Felder für die Header.

Hinweis

In der Testkonsole füllt API Management automatisch einen Ocp-Apim-Subscription-Key-Header auf und konfiguriert den Abonnementschlüssel des integrierten All-Access-Abonnements. Dieser Schlüssel ermöglicht den Zugriff auf jede API in der API Management-Instanz. Optional können Sie den Ocp-Apim-Subscription-Key-Header anzeigen, indem Sie das Augensymbol neben der HTTP-Anforderung auswählen.
Geben Sie je nach Vorgang Abfrageparameterwerte, Headerwerte oder einen Anforderungstext ein. Wählen Sie Senden aus.

Wenn der Test erfolgreich ist, antwortet das Back-End mit einem erfolgreichen HTTP-Antwortcode und einigen Daten.

Tipp

Standardmäßig sendet die Testkonsole eine Anforderung an den CORS-Proxy von API Management, der die Anforderung an die API Management-Instanz weiterleitet, die sie dann an das Back-End weiterleitet. Dieser Proxy verwendet die öffentliche IP-Adresse 13.91.254.72 und kann nur öffentliche Endpunkte erreichen. Wenn Sie eine Anforderung direkt vom Browser an den API Management-Dienst senden möchten, wählen Sie CORS-Proxy umgehen aus. Verwenden Sie diese Option, wenn Sie die Testkonsole verwenden möchten und Ihr API Management-Gateway vom Netzwerk isoliert ist oder keinen Datenverkehr vom CORS-Proxy zulässt.

Informationen zum Debuggen einer API finden Sie unter Tutorial: Debuggen von APIs mit der Anforderungsablaufverfolgung.

SOAP-Platzhalteraktion

Wenn Sie eine SOAP-Anforderung übergeben müssen, für die in der API keine dedizierte Aktion definiert ist, können Sie eine SOAP-Platzhalteraktion konfigurieren. Die Platzhalteraktion stimmt mit jeder SOAP-Anforderung überein, die nicht in der API definiert ist.

So definieren Sie eine SOAP-Platzhalteraktion:

Wählen Sie im Portal die API aus, die Sie im vorherigen Schritt erstellt haben.
Wählen Sie auf der Registerkarte Entwurf die Option + Vorgang hinzufügen aus.
Geben Sie einen Anzeigenamen für den Vorgang ein.
Wählen Sie unter URL die Option POST aus, und geben Sie in der Ressource /?soapAction={any} ein. Der Vorlagenparameter in den eckigen Klammern ist willkürlich festgelegt und wirkt sich nicht auf die Ausführung aus.

Hinweis

Verwenden Sie nicht den OpenAPI-Spezifikations-Editor auf der Registerkarte Entwurf, um eine SOAP-API zu ändern.

Anfügen weiterer APIs

Sie können eine API aus APIs zusammensetzen, die von verschiedenen Diensten verfügbar gemacht werden, u. a.:

Eine OpenAPI-Spezifikation
SOAP-API
Eine GraphQL-API
In Azure App Service gehostete Web-App
Azure-Funktionen-App
Azure Logic Apps
Azure Service Fabric

Führen Sie zum Anfügen einer anderen API an eine vorhandene API die folgenden Schritte aus.

Hinweis

Wenn Sie eine andere API importieren, werden die Vorgänge an Ihre aktuelle API angefügt.

Navigieren Sie im Azure-Portal zu Ihrer Azure API Management-Instanz.
Wählen Sie auf der Seite Übersicht oder im Menü auf der linken Seite die Option APIs aus.
Klicken Sie neben der API, die Sie an eine andere API anfügen möchten, auf ....
Wählen Sie im Dropdownmenü Importieren aus.
Wählen Sie einen Dienst aus, aus dem eine API importiert werden soll.