Übersicht über GraphQL-APIs in Azure API Management

GILT FÜR: Alle API Management-Ebenen

Sie können API Management verwenden, um GraphQL-APIs zu verwalten. Dies sind Anwendungsprogrammierschnittstellen, die auf der GraphQL-Abfragesprache basieren. GraphQL bietet eine umfassende und verständliche Beschreibung der Daten in einer API, sodass Clients genau die Daten effizient abrufen können, die sie benötigen. Weitere Informationen zu GraphQL

API Management hilft Ihnen beim Importieren, Verwalten, Schützen, Testen, Veröffentlichen und Überwachen von GraphQL-APIs. Sie können zwischen zwei API-Modellen wählen:

Passthrough-GraphQL GraphQL (synthetisch)
▪️ Passthrough-API für vorhandenen GraphQL-Dienstendpunkt

▪️ Unterstützung für GraphQL-Abfragen, Mutationen und Abonnements
▪️ API basierend auf einem benutzerdefinierten GraphQL-Schema

▪️ Unterstützung für GraphQL-Abfragen, Mutationen und Abonnements

▪️ Konfigurieren von benutzerdefinierten Resolvern, z. B. für HTTP-Datenquellen

▪️ Entwickeln von GraphQL-Schemas und GraphQL-basierten Clients beim Verarbeiten von Daten aus Legacy-APIs

Verfügbarkeit

  • GraphQL-APIs werden in allen API Management-Dienstebenen unterstützt.
  • Synthetische GraphQL-APIs werden in API Management Arbeitsbereichen derzeit nicht unterstützt
  • Unterstützung für GraphQL-Abonnements in synthetischen GraphQL-APIs befindet sich derzeit in der Vorschauphase und ist im Tarif „Verbrauch“ nicht verfügbar.

Was ist GraphQL?

GraphQL ist eine Open-Source-Abfragesprache für APIs, die dem Branchenstandard entspricht. Im Gegensatz zu REST-basierten APIs, die auf Aktionen für Ressourcen ausgerichtet sind, unterstützen GraphQL-APIs mehr Anwendungsfälle und konzentrieren sich auf Datentypen, Schemas und Abfragen.

Die GraphQL-Spezifikation löst insbesondere häufige Probleme von Client-Web-Apps, die auf REST-APIs zurückgreifen:

  • Es kann eine große Anzahl von Anforderungen erforderlich sein, um die Datenanforderungen für lediglich eine einzelne Seite zu erfüllen.
  • REST-APIs geben häufig mehr Daten zurück, als die gerenderte Seite benötigt.
  • Die Client-App muss eine Abfrage durchführen, um neue Informationen zu erhalten.

Mithilfe einer GraphQL-API kann die Client-App die Daten, die sie zum Rendern einer Seite benötigt, in einem Abfragedokument angeben, das als einzelne Anforderung an einen GraphQL-Dienst gesendet wird. Eine Client-App kann auch Datenupdates abonnieren, die vom GraphQL-Dienst in Echtzeit gepusht werden.

Schema und Typen

Fügen Sie in API Management eine GraphQL-API aus einem GraphQL-Schema hinzu, die entweder von einem GraphQL-Back-End-Endpunkt abgerufen oder von Ihnen hochgeladen wurde. Ein GraphQL-Schema beschreibt Folgendes:

  • Datenobjekttypen und Felder, die Clients von einer GraphQL-API anfordern können
  • Für die Daten zulässige Vorgangstypen, z. B. Abfragen
  • Andere Typen, z. B. Vereinigungen und Schnittstellen, die zusätzliche Flexibilität und Kontrolle über die Daten bieten

Ein einfaches GraphQL-Schema für Benutzerdaten und eine Abfrage für alle Benutzer können beispielsweise folgendermaßen aussehen:

type Query {
    users: [User]
}

type User {
    id: String!
    name: String!
}

Vorgangstypen

API Management unterstützt die folgenden Vorgangstypen in GraphQL-Schemas. Weitere Informationen zu diesen Vorgangstypen finden Sie in der GraphQL-Spezifikation.

  • Abfrage: Ruft Daten ab (vergleichbar mit einem „GET“-Vorgang in REST)

  • Mutation: Ändert serverseitige Daten (vergleichbar mit einem „PUT“- oder „PATCH“-Vorgang in REST)

  • Abonnement: Ermöglicht die Benachrichtigung abonnierter Clients über Änderungen an Daten im GraphQL-Dienst in Echtzeit

    Wenn Daten beispielsweise über eine GraphQL-Mutation geändert werden, können abonnierte Clients automatisch über die Änderung benachrichtigt werden.

    Wichtig

    API Management unterstützt Abonnements, die mithilfe des WebSocket-Protokolls graphql-ws implementiert werden. Abfragen und Mutationen über WebSocket werden nicht unterstützt.

Andere Typen

Die API-Verwaltung unterstützt die Typen Vereinigung und Schnittstelle in GraphQL-Schemata.

Resolver

Resolver sorgen für die Zuordnung des GraphQL-Schemas zu Back-End-Daten und erzeugen die Daten für jedes Feld in einem Objekttyp. Die Datenquelle kann eine API, eine Datenbank oder ein anderer Dienst sein. Beispielsweise wäre für die Rückgabe von Daten für die Abfrage „users“ im vorherigen Beispiel eine Resolverfunktion verantwortlich.

In API Management können Sie einen Resolver erstellen, um ein Feld in einem Objekttyp einer Back-End-Datenquelle zuzuordnen. Sie konfigurieren Resolver für Felder in synthetischen GraphQL-API-Schemas, können sie aber auch so konfigurieren, dass sie die standardmäßigen Feldresolver überschreiben, die von Passthrough-GraphQL-APIs verwendet werden.

API Management unterstützt derzeit Resolver, die auf HTTP API-, Cosmos DB- und Azure SQL-Datenquellen basieren, um Felddaten in einem GraphQL-Schema zurückzugeben. Jeder Resolver wird mithilfe einer maßgeschneiderten Richtlinie konfiguriert, um eine Verbindung mit der Datenquelle herzustellen und die Daten abzurufen:

Datenquelle Resolverrichtlinie
HTTP-basierte Datenquelle (REST oder SOAP API) http-data-source
Cosmos DB-Datenbank cosmosdb-data-source
Azure SQL-Datenbank sql-data-source

Beispielsweise kann ein HTTP API-basierter Resolver für die vorherige Abfrage „users“ einem „GET“-Vorgang in einer Back-End-REST-API zugeordnet werden:

<http-data-source>
	<http-request>
		<set-method>GET</set-method>
		<set-url>https://myapi.contoso.com/api/users</set-url>
	</http-request>
</http-data-source>

Weitere Informationen zum Einrichten eines Resolvers finden Sie unter Konfigurieren eines GraphQL Resolvers.

Verwalten von GraphQL-APIs

  • Schützen Sie GraphQL-APIs vor GraphQL-spezifischen Angriffen durch Anwenden vorhandener Zugriffssteuerungsrichtlinien und einer GraphQL-Validierungsrichtlinie.
  • Erkunden Sie die GraphQL-Schemas und führen Sie Testabfragen für GraphQL-APIs im Azure-Portal und im Entwicklerportal durch.

Nächste Schritte