Importieren einer OpenAPI-Spezifikation

GILT FÜR: Alle API Management-Ebenen

In diesem Artikel wird gezeigt, wie Sie eine OpenAPI-Spezifikations-Back-End-API mithilfe verschiedener Tools in Azure API Management importieren. Der Artikel zeigt außerdem, wie Sie die API in API Management testen. Informationen zur Unterstützung der OpenAPI-Version finden Sie unter API-Importeinschränkungen und bekannte Probleme.

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

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-Befehlszeilenschnittstelle (Azure CLI)

  • Verwenden Sie die Bash-Umgebung in Azure Cloud Shell. Weitere Informationen finden Sie unter "Erste Schritte mit 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. Um den Authentifizierungsprozess abzuschließen, führen Sie die in Ihrem Terminal angezeigten Schritte aus. Weitere Anmeldeoptionen finden Sie unter Authentifizieren bei Azure mithilfe der Azure CLI.

    • Installieren Sie die Azure CLI-Erweiterung bei der ersten Verwendung, wenn Sie dazu aufgefordert werden. Weitere Informationen zu Erweiterungen finden Sie unter Verwenden und Verwalten 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 Sie die aktuelle 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. 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

Nachdem Sie die API importiert haben, können Sie die Einstellungen mithilfe des Befehls "az apim 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

Nachdem Sie die API importiert haben, können Sie die Einstellungen mithilfe des Cmdlets Set-AzApiManagementApi aktualisieren.

Anzeigen und Bearbeiten der OpenAPI-Spezifikation

Verwenden Sie im Azure-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 APIsAPIs><Ihre API>>Alle Vorgänge aus.
3. Wählen Sie auf der Registerkarte Entwurf im FrontendOpenAPI-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 API-Verwaltungsüberprüfungsrichtlinien 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

Sie können Vorgänge direkt über das Azure-Portal aufrufen, was eine bequeme Möglichkeit zum Anzeigen und Testen der Vorgänge einer API bietet.

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 erstellen, die von verschiedenen Diensten verfügbar gemacht werden, einschließlich:

• Einer OpenAPI-Spezifikation
• Einer SOAP-API
• Einer GraphQL-API
• Eine Web-App, die in Azure App Service gehostet wird
• Azure-Funktionen
• Azure Logic Apps
• Azure Service Fabric

Hinweis

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

So fügen Sie eine API an eine vorhandene API an:

1. Wechseln Sie im Azure-Portal zu Ihrer Azure-API-Verwaltungsinstanz:

   

2. Wählen Sie auf der Seite "Übersicht"APIs aus, oder wählen Sie im Menü auf der linken Seite APIs> aus.

   

3. Wählen Sie die Ellipse (...) neben der API aus, zu der Sie eine andere API hinzufügen möchten.

4. Wählen Sie im Kontextmenü " Importieren" aus:

   

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

Verwandte Inhalte

• Einschränkungen beim API-Import
• Importieren einer OpenAPI-Spezifikation
• Importieren einer SOAP-API
• Importieren einer SOAP-API und Konvertieren 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 Feldresolvern
• Importieren einer Funktions-App-API
• Importieren einer Logik-App-API
• Tutorial: Integrieren von API Management in Service Fabric in Azure
• Importieren einer Azure AI Foundry-API
• Importieren einer Azure OpenAI-API
• Importieren einer LLM-API
• Importieren einer OData-API
• Exportieren einer REST-API als MCP-Server
• Verfügbarmachen eines vorhandenen MCP-Servers
• Importieren einer A2A-Agent-API
• Importieren von SAP OData-Metadaten
• Importieren einer gRPC-API
• Bearbeiten einer API