Importieren einer OpenAPI-Spezifikation

GILT FÜR: Alle API Management-Ebenen

In diesem Artikel wird gezeigt, wie Sie eine Back-End-API für die OpenAPI-Spezifikation mithilfe verschiedener Tools in Azure API Management importieren. Der Artikel zeigt außerdem, wie Sie die API in API Management testen.

In diesem Artikel werden folgende Vorgehensweisen behandelt:

• Importieren einer OpenAPI-Spezifikation über das Azure-Portal, die Azure CLI oder Azure PowerShell
• Testen der API im Azure-Portal

Hinweis

API-Importeinschränkungen sind unter API-Importeinschränkungen und bekannte Probleme dokumentiert.

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

In diesem Beispiel importieren Sie die OpenAPI-Spezifikation für die Open Source Petstore-API, aber Sie können eine OpenAPI-Spezifikation Ihrer Wahl ersetzen.

Portal

1. Navigieren Sie im Azure-Portal zu Ihrer API Management-Instanz.

2. Wählen Sie im linken Menü APIs> + API hinzufügen aus.

3. Klicken Sie unter Create from definition (Aus Definition erstellen) auf OpenAPI.

   

4. Geben Sie API-Einstellungen ein. Sie können die Werte während der Erstellung festlegen oder später über die Registerkarte Einstellungen konfigurieren. Die Einstellungen werden im Tutorial Importieren und Veröffentlichen Ihrer ersten API erläutert.

5. Klicken Sie auf Erstellen.

Azure-Befehlszeilenschnittstelle

Im folgenden Beispiel wird der Befehl az apim api import verwendet, um eine OpenAPI-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.

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

# API-specific details
APIId="swagger-petstore"
APIPath="store"
SpecificationFormat="OpenAPI"
SpecificationURL="https://petstore3.swagger.io/api/v3/openapi.json"

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

Nach dem Importieren der API können Sie die Einstellungen bei Bedarf mit dem Befehl az apim api update aktualisieren.

PowerShell

Im folgenden Beispiel wird das Azure PowerShell-Cmdlet Import-AzApiManagementApi verwendet, um eine OpenAPI-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.

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

# API-specific details
$apiId = "swagger-petstore"
$apiPath = "store"
$specificationFormat = "OpenAPI"
$specificationUrl = "https://petstore3.swagger.io/api/v3/openapi.json"

# 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

Nach dem Importieren der API können Sie die Einstellungen bei Bedarf mit dem Cmdlet Set-AzApiManagementApi aktualisieren.

Anzeigen und Bearbeiten der OpenAPI-Spezifikation

Verwenden Sie im Portal den OpenAPI-Spezifikations-Editor, um die Spezifikation für die von Ihnen importierte API anzuzeigen, zu überprüfen oder zu bearbeiten.

So verwenden Sie den OpenAPI-Spezifikations-Editor:

1. Navigieren Sie im Azure-Portal zu Ihrer API Management-Instanz.
2. Wählen Sie im linken Menü unter APIs APIs><Ihre API>>Alle Vorgänge aus.
3. Wählen Sie auf der Registerkarte Entwurf im Frontend OpenAPI-Spezifikations-Editor (Bleistiftsymbol) aus. Sie können die Spezifikation im JSON- oder YAML-Format öffnen.
4. Überprüfen oder bearbeiten Sie die Spezifikation nach Bedarf. Speichern Sie die Änderungen.

Überprüfen anhand eines OpenAPI-Spezifikationsschemas

Sie können in API Management Validierungsrichtlinien konfigurieren, um Anforderungen und Antworten (oder Elemente davon) anhand des Schemas in einer OpenAPI-Spezifikation zu überprüfen. Verwenden Sie beispielsweise die Richtlinie validate-content, um die Größe oder den Inhalt eines Anforderungs- oder Antworttexts zu überprüfen.

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.

1. Wählen Sie die API aus, die Sie im vorherigen Schritt erstellt haben.

2. Wählen Sie die Registerkarte Testen aus.

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

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

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.

1. Navigieren Sie im Azure-Portal zu Ihrer Azure API Management-Instanz.

   

2. Wählen Sie auf der Seite Übersicht oder im Menü auf der linken Seite die Option APIs aus.

   

3. Klicken Sie neben der API, die Sie an eine andere API anfügen möchten, auf ....

4. Wählen Sie im Dropdownmenü Importieren aus.

   

5. Wählen Sie einen Dienst aus, aus dem eine API importiert werden soll.

   

Zugehörige Themen

• Einschränkungen beim API-Import
• Importieren einer OpenAPI-Spezifikation
• Importieren einer SOAP-API
• Importieren einer SOAP-API und Konvertieren dieser in REST
• Importieren einer App Service-API
• Importieren einer Container-App-API
• Importieren einer WebSocket-API
• Importieren einer GraphQL-API
• Importieren eines GraphQL-Schemas und Einrichten von Feldauflösern
• Importieren einer Azure Functions-App als API
• Importieren einer Logik-App als API
• Tutorial: Integrieren von API Management in Service Fabric in Azure
• Importieren einer Azure OpenAI-API
• Importieren einer OData-API
• Importieren von SAP OData-Metadaten
• Importieren einer gRPC-API
• Bearbeiten von APIs

Nächste Schritte

• Erstellen und Veröffentlichen eines Produkts
• Transformieren und Schützen einer veröffentlichten API