Vue d’ensemble des API GraphQL dans Azure Gestion des API

Article
05/10/2024

S’APPLIQUE À : tous les niveaux de Gestion des API

Vous pouvez utiliser Gestion des API pour gérer les API GraphQL : API utilisant le langage de requête GraphQL. GraphQL fournit une description complète et compréhensible des données dans une API, permettant aux clients de récupérer efficacement les données dont ils ont besoin. En savoir plus sur GraphQL

Gestion des API vous permet d’importer, de gérer, de protéger, de tester, de publier et de surveiller les API GraphQL. Vous pouvez choisir l'un des deux modèles d’API :

GraphQL pass-through	GraphQL synthétique
▪️ API pass-through vers un point de terminaison du service GraphQL existant ▪️ Prise en charge des requêtes, des mutations et des abonnements GraphQL	▪️ API basée sur un schéma personnalisé GraphQL ▪️ Prise en charge des requêtes, mutations et abonnements GraphQL ▪️ Configurer des résolveurs personnalisés, par exemple sur des sources de données HTTP ▪️ Développer des schémas GraphQL et des clients basés sur GraphQL, tout en consommant des données provenant d’API héritées

Disponibilité

Les API GraphQL sont prises en charge à tous les niveaux de service Gestion des API
Les API GraphQL synthétiques ne sont actuellement pas prises en charge dans des espaces de travail Gestion des API
La prise en charge des abonnements GraphQL dans les API synthétiques GraphQL est actuellement en version préliminaire et n’est pas disponible dans le niveau Consommation

Qu’est-ce GraphQL ?

GraphQL est un langage de requête standard open source pour les API. Contrairement aux API de type REST conçues pour des actions sur les ressources, les API GraphQL prennent en charge un ensemble plus large de cas d’utilisation et se concentrent sur les types de données, les schémas et les requêtes.

La spécification GraphQL résout explicitement les problèmes courants rencontrés par les applications web clientes s’appuyant sur les API REST :

Un grand nombre de requêtes peut être nécessaire pour répondre aux besoins en données d’une seule page
Les API REST retournent souvent plus de données que nécessaire pour l’affichage de la page
L’application cliente doit demander pour obtenir de nouvelles informations

Grâce à une API GraphQL, l’application cliente peut spécifier les données dont elle a besoin pour afficher une page dans un document de requête envoyé comme requête unique à un service GraphQL. Une application cliente peut aussi s’abonner aux mises à jour de données envoyées depuis le service GraphQL en temps réel.

Schéma et types

Dans Gestion des API, ajoutez une API GraphQL depuis un schéma GraphQL, récupérée à partir d’un point de terminaison d’API GraphQL back-end ou chargée par vous. Un schéma GraphQL décrit :

Les types d’objets de données et champs que les clients peuvent demander à partir d’une API GraphQL
Les types d’opérations autorisés sur les données, tels que les requêtes
D’autres types, tels que les unions et les interfaces, qui offrent une flexibilité et un contrôle supplémentaires sur les données

Un schéma GraphQL de base pour les données utilisateur et une requête pour tous les utilisateurs peuvent par exemple ressembler à ceci :

type Query {
    users: [User]
}

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

Types d’opération

Le type d'opération suivant est pris en charge par Gestion des API dans les schémas GraphQL. Pour plus d’informations au sujet de ces types d’opérations, consultez la spécification GraphQL.

Requête : extrait des données, similaire à une opération GET dans REST
Mutation : modifie les données côté serveur, comme une opération PUT ou PATCH dans REST
Abonnement : permet d’informer les clients abonnés en temps réel des modifications apportées aux données sur le service GraphQL

Lorsque des données sont par exemple modifiées au travers d’une mutation GraphQL, les clients abonnés peuvent être automatiquement avertis de la modification.

Important

Gestion des API prend en charge les abonnements implémentés grâce au protocole WebSocket graphql-ws. Les requêtes et mutations ne sont pas prises en charge sur WebSocket.

Autres types

La Gestion des API prend en charge les types union et interface dans les schémas GraphQL.

Résolveurs

Les résolveurs s’occupent du mappage du schéma GraphQL vers les données back-end, en produisant les données pour chaque champ du type d’objet. Les données peuvent provenir d’une API, d’une base de données ou d’un autre service. Par exemple, une fonction de résolveur peut être responsable du retour des données pour la requête users dans l’exemple précédent.

Dans API Management, vous pouvez créer un programme de résolution pour mapper un champ dans un type d’objet à une source de données back-end. Vous configurez des résolveurs pour les champs dans les schémas d’API GraphQL synthétiques, mais vous pouvez aussi les configurer pour remplacer le champ résolveurs par défaut utilisé par les API GraphQL pass-through.

API Management prend actuellement en charge les programmes de résolution basés sur l’API HTTP, Cosmos DB et Azure SQL sources de données pour retourner les données des champs d’un schéma de GraphQL. Chaque programme de résolution est configuré à l’aide d’une stratégie personnalisée pour se connecter à la source de données et récupérer les données :

Source de données	Stratégie du programme de résolution
Source de données basée sur HTTP (API REST ou SOAP)	http-data-source
Base de données Cosmos DB	cosmosdb-data-source
Base de données Azure SQL	sql-data-source

Par exemple, un programme de résolution basé sur l’API HTTP pour la requête users précédente peut correspondre à une opération GET dans une API REST back-end :

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

Pour plus d’informations sur la configuration d’un programme de résolution, reportez-vous Configurer un programme de résolution de GraphQL.

Gérer les API GraphQL

Sécuriser les API GraphQL en appliquant à la fois des stratégies de contrôle d’accès existantes et une stratégie de validation GraphQL pour la sécurisation et la protection contre les attaques ciblant GraphQL.
Explorer le schéma GraphQL et exécuter des requêtes de test sur les API GraphQL dans le portail Azure et les portails des développeurs.

Partage via