Importieren einer GraphQL-API

GILT FÜR: Alle API Management-Ebenen

In API Management können Sie eine GraphQL-API in einem von zwei Modellen hinzufügen: Passthrough an einen vorhandenen GraphQL-Endpunkt oder Import eines GraphQL-Schemas und Erstellung einer synthetischen GraphQL-API mit benutzerdefinierten Feld-Resolvern. Weitere Informationen finden Sie in der GraphQL-Übersicht.

In diesem Artikel führen Sie Folgendes durch:

• Hinzufügen einer Passthrough-GraphQL-API zu Ihrer API Management-Instanz.
• Testen Ihrer GraphQL-API

Wenn Sie ein GraphQL-Schema importieren und Feldlöser einrichten möchten, die REST- oder SOAP-API-Endpunkte verwenden, lesen Sie "Importieren eines GraphQL-Schemas und Einrichten von Feldlösern".

Voraussetzungen

• Eine API Management-Instanz. Erstellen Sie eine, falls nicht schon geschehen.

• Azure CLI, wenn Sie sie zum Importieren der API verwenden möchten.

  • 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, wenn Sie sie zum Importieren der API verwenden möchten.

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

Hinzufügen einer GraphQL-API

Portal

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

2. Wählen Sie im linken BereichAPIs>aus.

3. Wählen Sie "API hinzufügen" aus.

4. Wählen Sie unter "Neue API definieren" die GraphQL-Kachel aus.

   

5. Wählen Sie im resultierenden Dialogfeld "Vollständig" aus, und geben Sie dann Werte in die erforderlichen Felder ein, wie in der folgenden Tabelle beschrieben.

   

   Wert	BESCHREIBUNG
   Anzeigename	Das ist der Name, mit dem Ihre GraphQL-API angezeigt wird.
   Name	Der rohe Name der GraphQL-API. Er wird automatisch ausgefüllt, wenn Sie den Anzeigenamen eingeben.
   GraphQL-Typ	Wählen Sie Passthrough-GraphQL, um aus einem vorhandenen GraphQL-API-Endpunkt zu importieren.
   GraphQL-API-Endpunkt	Das ist die Basis-URL mit dem Namen Ihres GraphQL-API-Endpunkts. Beispiel: https://example.com/your-GraphQL-name. Sie können auch einen gemeinsamen SWAPI GraphQL-Endpunkt wie https://swapi-graphql.azure-api.net/graphql zur Demonstration verwenden.
   Schema hochladen	Optional können Sie Ihre Schemadatei hochladen, um das Schema, sofern vorhanden, zu ersetzen, das vom GraphQL-Endpunkt abgerufen wird.
   Beschreibung	Fügen Sie eine Beschreibung Ihrer API hinzu.
   URL-Schema	Wählen Sie ein Schema basierend auf Ihrem GraphQL-Endpunkt aus. Wählen Sie eine der Optionen aus, die ein WebSocket-Schema (WS oder WSS) enthält, wenn Ihre GraphQL-API den Abonnementtyp einschließt. Die Standardauswahl ist HTTP(S).
   API-URL-Suffix	Fügen Sie ein URL-Suffix hinzu, um die spezifische API in der API-Verwaltungsinstanz zu identifizieren. Sie muss in der API-Verwaltungsinstanz eindeutig sein.
   Basis-URL	Unbearbeitbares Feld, in dem Ihre API-Basis-URL angezeigt wird.
   Stichwörter	Ordnen Sie optional Ihre GraphQL-API neuen oder vorhandenen Tags zu.
   Produkte	Ordnen Sie Ihre GraphQL-API einem Produkt zu, um sie zu veröffentlichen.
   Versionsverwaltung für diese API?	Aktivieren Sie das Kontrollkästchen, um ein Versionsverwaltungsschema auf Ihre GraphQL-API anzuwenden.

6. Klicken Sie auf Erstellen.

7. Überprüfen oder ändern Sie das Schema auf der Registerkarte "Schema ", nachdem die API erstellt wurde.

Azure-Befehlszeilenschnittstelle

Im folgenden Beispiel wird der Befehl az apim api import verwendet, um eine Passthrough-API von GraphQL aus der angegebenen URL in eine API Management-Instanz namens apim-hello-world zu importieren.

# Details specific to API Management instance.
APIMServiceName="apim-hello-world"
ResourceGroupName="myResourceGroup"

# API-specific details.
APIId="my-graphql-api"
APIPath="myapi"
DisplayName="MyGraphQLAPI"
SpecificationFormat="GraphQL"
SpecificationURL="<GraphQL backend endpoint>"

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

Nach dem Importieren der API können Sie die Einstellungen mithilfe des Az APIM-Aktualisierungsbefehls aktualisieren, falls erforderlich.

PowerShell

Im folgenden Beispiel wird das Azure PowerShell-Cmdlet Import-AzApiManagementApi verwendet, um eine Passthrough-API von GraphQL aus der angegebenen URL in eine API Management-Instanz namens apim-hello-world zu importieren.

# Details specific to API Management instance.
$apimServiceName = "apim-hello-world"
$resourceGroupName = "myResourceGroup"

# API-specific details.
$apiId = "my-graphql-api"
$apiPath = "myapi"
$specificationFormat = "GraphQL"
$specificationUrl = "<GraphQL backend endpoint>"

# 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 mithilfe des Cmdlets Set-AzApiManagementApi aktualisieren, falls erforderlich.

Testen Ihrer GraphQL-API

1. Wechseln Sie zu Ihrer API-Verwaltungsinstanz.

2. Wählen Sie im linken Bereich im Abschnitt APIs, APIs aus.

3. Wählen Sie unter Alle APIs Ihre GraphQL-API aus.

4. Wählen Sie die Registerkarte Test aus, um auf die Testkonsole zuzugreifen.

5. Unter Header:

   1. Wählen Sie die Kopfzeile aus dem Menü "Name " aus.
   2. Geben Sie den Wert in das Feld "Wert " ein.
   3. Fügen Sie weitere Kopfzeilen hinzu, indem Sie "Kopfzeile hinzufügen" auswählen.
   4. Löschen Sie Header mithilfe der Papierkorbschaltfläche.

6. Wenn Sie Ihrer GraphQL-API ein Produkt hinzugefügt haben, fügen Sie einen Produktbereich unter "Produktbereich anwenden" hinzu.

7. Führen Sie im Abfrage-Editor eine der folgenden Aktionen aus:

   1. Wählen Sie mindestens ein Feld oder Unterfeld aus der Liste im Menü links neben dem Editor aus. Die von Ihnen ausgewählten Felder und Unterfelder werden im Abfrage-Editor angezeigt.

   2. Beginnen Sie mit der Eingabe im Abfrage-Editor, um eine Abfrage zu erstellen.

      

8. Fügen Sie unter Abfragevariablen Variablen hinzu, um eine Abfrage oder Mutation wiederzuverwenden und unterschiedliche Werte zu übergeben.

9. Wählen Sie Senden aus.

10. Zeigen Sie die Antwort an.

    

11. Wiederholen Sie die vorstehenden Schritte, um verschiedene Nutzlasten zu testen.

12. Wenn Sie mit dem Testen fertig sind, beenden Sie die Testkonsole.

Testen eines Abonnements

Wenn Ihre GraphQL-API ein Abonnement unterstützt, können Sie es in der Testkonsole testen.

1. Stellen Sie sicher, dass Ihre API ein WebSocket-URL-Schema (WS oder WSS) zulässt, das für Ihre API geeignet ist. Sie können diese Einstellung auf der Registerkarte Einstellungen aktivieren.

2. Richten Sie eine Abonnementabfrage im Abfrage-Editor ein. Wählen Sie dann Verbinden aus, um eine WebSocket-Verbindung mit dem Back-End-Dienst herzustellen.

   

3. Überprüfen Sie die Verbindungsdetails im Bereich Abonnement.

   

4. Abonnierte Ereignisse werden im Bereich Abonnement angezeigt. Die WebSocket-Verbindung wird beibehalten, bis Sie sie trennen oder eine Verbindung mit einem neuen WebSocket-Abonnement herstellen.

   

Schützen Ihrer GraphQL-API

Schützen Sie Ihre GraphQL-API vor GraphQL-spezifischen Angriffen durch das Anwenden vorhandener Authentifizierungs- und Autorisierungsrichtlinien und einer GraphQL-Validierungsrichtlinie.

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