Configurer un programme de résolution GraphQL

Article
12/09/2023

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

Configurez un programme de résolution pour récupérer ou définir des données pour un champs GraphQL dans un type d’objet spécifié au sein d’un schéma GraphQL. Le schéma doit être importé dans Gestion des API en tant qu’API GraphQL.

Actuellement, Gestion des API prend en charge les programmes de résolution qui peuvent accéder aux sources de données suivantes :

Source de données basée sur HTTP (API REST ou SOAP)
Base de données Cosmos DB
Base de données Azure SQL

À savoir

Un programme de résolution est une ressource contenant une définition de stratégie qui est appelée uniquement lorsqu’un type et un champ d’objet correspondants sont exécutés dans le schéma.
Chaque programme de résolution résout les données d’un seul champ. Pour résoudre les données de plusieurs champs, configurez un programme de résolution distinct pour chacun d’eux.
Les stratégies à l’échelle de programme de résolution sont évaluées après toute stratégie inbound et backend dans le pipeline d’exécution de stratégie. Elles n’héritent pas de stratégies d’autres échelles. Pour plus d’informations, consultez Abonnements dans Gestion des API.
Vous pouvez configurer des stratégies étendues à l’API pour une API GraphQL, indépendamment des stratégies étendues au programme de résolution. Par exemple, ajoutez une stratégie validate-graphql-request à l’étendue inbound pour valider la requête avant l’appel du programme de résolution. Configurez des stratégies étendues à l’API sous l’onglet Stratégies d’API pour l’API.

Prérequis

Disposer d’une instance d’API Management. Si vous ne l’avez pas déjà fait, créez-en un.
Importez une API GraphQL directe ou synthétique.

Créer un programme de résolution

Les étapes suivantes créent un programme de résolution à l’aide d’une source de données HTTP. Les étapes générales sont similaires pour tout programme de résolution qui utilise une source de données prise en charge.

Dans le portail Azure, accédez à votre instance APIM.
Dans le menu de gauche, sélectionnez API, puis le nom de votre API GraphQL.
Sous l’onglet Schéma, passez en revue le schéma d’un champ d’un type d’objet pour lequel vous souhaitez configurer un programme de résolution.
1. Sélectionnez un champ, puis, dans la marge gauche, pointez avec le curseur.
2. Sélectionnez + Ajouter un programme de résolution.
Sur la page Créer un programme de résolution :
1. Mettez à jour la propriété Nom si vous le souhaitez, entrez éventuellement une Description et confirmez ou mettez à jour les sélections Type et Champ.
2. Sélectionnez la source de données du programme de résolution. Pour cet exemple, sélectionnez API HTTP.
Dans l’éditeur de stratégie du programme de résolution, mettez à jour la stratégie http-data-source avec des éléments enfants pour votre scénario.
1. Mettez à jour l’élément http-request requis avec des stratégies pour transformer l’opération GraphQL en requête HTTP.
2. Ajoutez éventuellement un élément http-response et ajoutez des stratégies enfants pour transformer la réponse HTTP du programme de résolution. Si l’élément http-response n’est pas spécifié, la réponse est retournée sous forme de chaîne brute.
3. Sélectionnez Create (Créer).
Le programme de résolution est attaché au champ et s’affiche sous l’onglet Programmes de résolution.

Gérer les programmes de résolution

Répertoriez et gérez les programmes de résolutions d’une API GraphQL sous l’onglet Programmes de résolution de l’API.

Sous l’onglet Programmes de résolution :

La colonne Lié indique si le programme de résolution est configuré ou non pour un champ qui se trouve actuellement dans le schéma GraphQL. Si un programme de résolution n’est pas lié, il ne peut pas être appelé.
Dans le menu contextuel (...) d’un programme de résolution, recherchez les commandes pour Cloner, Modifier ou Supprimer un programme de résolution. Clonez un programme de résolution répertorié pour créer rapidement un programme de résolution similaire qui cible un type et un champ différents.
Vous pouvez créer un programme de résolution en sélectionnant + Créer.

Modifier et tester un programme de résolution

Lorsque vous modifiez un programme de résolution unique, la page Modifier le programme de résolution s’ouvre. Vous pouvez :

Mettez à jour la stratégie du programme de résolution et éventuellement la source de données. La modification de la source de données remplace la stratégie du programme de résolution actuelle.
Modifiez le type et le champ que le programme de résolution cible.
Testez et déboguez la configuration du programme de résolution. Lorsque vous modifiez la stratégie du programme de résolution, sélectionnez Exécuter le test pour vérifier la sortie de la source de données, que vous pouvez valider par rapport au schéma. Si des erreurs se produisent, la réponse inclut des informations sur la résolution des problèmes.

Contexte GraphQL

Le contexte de la requête et de la réponse du programme de résolution (si elle est spécifiée) diffère du contexte de la demande d’API de la passerelle d’origine :
- Les propriétés context.GraphQL sont définies sur les arguments (Arguments) et l’objet parent (Parent) pour l’exécution actuelle du programme de résolution.
- Le contexte de la requête contient des arguments transmis dans le corps de la requête GraphQL.
- Le contexte de la réponse correspond à la réponse de l’appel indépendant effectué par le programme de résolution, et non au contexte de la réponse complète à la demande de la passerelle. La variable context transmise via le pipeline de requête et de réponse est augmentée avec le contexte GraphQL lorsqu’elle est utilisée avec un programme de résolution GraphQL.

context.GraphQL.parent

context.GraphQL.parent est défini sur l’objet parent pour l’exécution actuelle du programme de résolution. Prenons en considération le schéma partiel suivant :

type Comment {
    id: ID!
    owner: string!
    content: string!
}

type Blog {
    id: ID!
    title: string!
    content: string!
    comments: [Comment]!
    comment(id: ID!): Comment
}

type Query {
    getBlog(): [Blog]!
    getBlog(id: ID!): Blog
}

Considérez également une requête GraphQL pour toutes les informations d’un blog spécifique :

query {
    getBlog(id: 1) {
        title
        content
        comments {
            id
            owner
            content
        }
    }
}

Si vous définissez un programme de résolution pour le champ comments dans le type Blog, vous devez savoir quel ID de blog utiliser. Vous pouvez obtenir l’ID du blog à l’aide du context.GraphQL.Parent["id"] du programme de résolution suivant :

<http-data-source>
    <http-request>
        <set-method>GET</set-method>
        <set-url>@($"https://data.contoso.com/api/blog/{context.GraphQL.Parent["id"]}")
        </set-url>
    </http-request>
</http-data-source>

context.GraphQL.Arguments

Les arguments d’une requête GraphQL paramétrée sont ajoutés à context.GraphQL.Arguments. Par exemple, prenons en considération les deux requêtes suivantes.

query($id: Int) {
    getComment(id: $id) {
        content
    }
}

query {
    getComment(id: 2) {
        content
    }
}

Ces requêtes sont deux façons d’appeler le programme de résolution getComment. GraphQL envoie la charge utile JSON suivante :

{
    "query": "query($id: Int) { getComment(id: $id) { content } }",
    "variables": { "id": 2 }
}

{
    "query": "query { getComment(id: 2) { content } }"
}

Vous pouvez définir le programme de résolution comme suit :

<http-data-source>
    <http-request>
        <set-method>GET</set-method>
        <set-url>@($"https://data.contoso.com/api/comment/{context.GraphQL.Arguments["id"]}")</set-url>
    </http-request>
</http-data-source>

Étapes suivantes

Pour plus d’exemples de programme de résolution, consultez :