Résolveurs de test et de débogage (VTL)

Note

Nous prenons désormais principalement en charge le runtime APPSYNC_JS et sa documentation. Pensez à utiliser le runtime APPSYNC_JS et ses guides ici.

AWS AppSync exécute des résolveurs sur un champ GraphQL par rapport à une source de données. Comme décrit dans la section Présentation du modèle de mappage Resolver, les résolveurs communiquent avec les sources de données à l'aide d'un langage de modélisation. Cela vous permet de personnaliser le comportement et d'appliquer une logique et des conditions avant et après la communication avec la source de données. Pour un guide de programmation de type didacticiel d'introduction à l'écriture de résolveurs, consultez le guide de programmation du modèle de mappage Resolver.

Pour aider les développeurs à écrire, tester et déboguer ces résolveurs, la AWS AppSync console fournit également des outils permettant de créer une requête et une réponse GraphQL avec des données fictives jusqu'au résolveur de champs individuel. En outre, vous pouvez effectuer des requêtes, des mutations et des abonnements dans la AWS AppSync console et consulter un flux de journal détaillé de l'intégralité CloudWatch de la demande provenant d'Amazon. Cela inclut les résultats d'une source de données.

Tester avec des données fictives

Lorsqu'un résolveur GraphQL est invoqué, il contient un context objet contenant des informations sur la demande. Ces informations incluent les arguments d'un client, les informations d'identité et les données du champ GraphQL parent. Il contient également les résultats de la source de données, qui peuvent être utilisés dans le modèle de réponse. Vous trouverez plus de détails sur cette structure et les utilitaires d'annotations disponibles à utiliser lors de la programmation dans le document Référence du contexte du modèle de mappage des résolveurs.

Lorsque vous écrivez ou modifiez un résolveur, vous pouvez transmettre un objet de contexte fictif ou de test dans l'éditeur de console. Cela vous permet de voir comment les deux modèles de la demande et de la réponse évaluent, sans réellement s'exécuter par rapport à une source de données. Par exemple, vous pouvez transmettre un argument de test firstname: Shaggy et voir comment il est analysé lors de l'utilisation de $ctx.args.firstname dans votre modèle de code. Vous pouvez également tester l'évaluation de n'importe quelle annotation d'utilitaire telle que $util.autoId() ou util.time.nowISO8601().

Tester les résolveurs

Cet exemple utilisera la AWS AppSync console pour tester les résolveurs.

1. Connectez-vous à AWS Management Console et ouvrez la console AppSync.

   1. Dans le tableau de bord des API, choisissez votre API GraphQL.

   2. Dans la barre latérale, choisissez Schema.

2. Si ce n'est pas déjà fait, sous le type et à côté du champ, choisissez Joindre pour ajouter votre résolveur.

   Pour plus d'informations sur la création d'un résolveur complet, voir Configuration des résolveurs.

   Sinon, sélectionnez le résolveur qui se trouve déjà dans le champ.

3. En haut de la page Modifier le résolveur, choisissez Sélectionner le contexte de test, puis Créer un nouveau contexte.

4. Sélectionnez un exemple d'objet de contexte ou renseignez le JSON manuellement dans la fenêtre de contexte d'exécution ci-dessous.

5. Entrez un nom de contexte de texte.

6. Choisissez le bouton Enregistrer.

7. En haut de la page Modifier le résolveur, sélectionnez Exécuter le test.

Pour un exemple plus pratique, supposons que vous disposiez d'une application stockant un type GraphQL Dog qui utilise la génération automatique d'identifiants pour les objets et les stocke dans Amazon DynamoDB. Il se peut aussi que vous souhaitiez écrire certaines valeurs des arguments d'une mutation GraphQL et permettre uniquement à des utilisateurs spécifiques de voir une réponse. Le schéma pourrait s'apparenter à ce qui suit :

type Dog {
  breed: String
  color: String
}

type Mutation {
  addDog(firstname: String, age: Int): Dog
}

Lorsque vous ajoutez un résolveur pour la addDog mutation, vous pouvez renseigner un objet de contexte comme dans l'exemple suivant. Le suivant possède les arguments name et age du client, ainsi qu'un username renseigné dans l'objet identity :

{
    "arguments" : {
        "firstname": "Shaggy",
        "age": 4
    },
    "source" : {},
    "result" : {
        "breed" : "Miniature Schnauzer",
        "color" : "black_grey"
    },
    "identity": {
        "sub" : "uuid",
        "issuer" : " https://cognito-idp.{region}.amazonaws.com/{userPoolId}",
        "username" : "Nadia",
        "claims" : { },
        "sourceIp" :[  "x.x.x.x" ],
        "defaultAuthStrategy" : "ALLOW"
    }
}

Vous pouvez effectuer le test en utilisant les modèles de mappage de demande et de réponse suivants :

Modèle de demande

{
    "version" : "2017-02-28",
    "operation" : "PutItem",
    "key" : {
        "id" : { "S" : "$util.autoId()" }
    },
    "attributeValues" : $util.dynamodb.toMapValuesJson($ctx.args)
}

Modèle de réponse

#if ($context.identity.username == "Nadia")
  $util.toJson($ctx.result)
#else
  $util.unauthorized()
#end

Le modèle évalué possède les données de votre objet de contexte du test et la valeur générée à partir de $util.autoId(). De plus, si vous deviez modifier username avec une valeur autre que Nadia, les résultats ne seront pas renvoyés, car le contrôle d'autorisation échouerait. Pour plus d'informations sur le contrôle d'accès détaillé, consultez la section Cas d'utilisation des autorisations.

Tester des modèles de mappage avec AWS AppSync les API

Vous pouvez utiliser la commande EvaluateMappingTemplate API pour tester à distance vos modèles de mappage avec des données simulées. Pour commencer à utiliser la commande, assurez-vous d'avoir ajouté l'appsync:evaluateMappingTemplateautorisation à votre politique. Par exemple :

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "appsync:evaluateMappingTemplate",
            "Resource": "arn:aws:appsync:<region>:<account>:*"
        }
    ]
}

Vous pouvez tirer parti de la commande à l'aide des AWSSDK AWS CLIou. Prenons par exemple le Dog schéma et ses modèles de mappage de demande/réponse de la section précédente. À l'aide de la CLI de votre station locale, enregistrez le modèle de demande dans un fichier nommérequest.vtl, puis enregistrez l'contextobjet dans un fichier nommécontext.json. Depuis votre shell, exécutez la commande suivante :

aws appsync evaluate-mapping-template --template file://request.vtl --context file://context.json

La commande renvoie la réponse suivante :

{
  "evaluationResult": "{\n    \"version\" : \"2017-02-28\",\n    \"operation\" : \"PutItem\",\n    \"key\" : {\n        \"id\" : { \"S\" : \"afcb4c85-49f8-40de-8f2b-248949176456\" }\n    },\n    \"attributeValues\" : {\"firstname\":{\"S\":\"Shaggy\"},\"age\":{\"N\":4}}\n}\n"
}

evaluationResultIl contient les résultats du test de votre modèle fourni avec le modèle fournicontext. Vous pouvez également tester vos modèles à l'aide des AWS SDK. Voici un exemple d'utilisation du AWS SDK pour la JavaScript version 2 :

const AWS = require('aws-sdk')
const client = new AWS.AppSync({ region: 'us-east-2' })

const template = fs.readFileSync('./request.vtl', 'utf8')
const context = fs.readFileSync('./context.json', 'utf8')

client
  .evaluateMappingTemplate({ template, context })
  .promise()
  .then((data) => console.log(data))

À l'aide du SDK, vous pouvez facilement intégrer les tests de votre suite de tests préférée pour valider le comportement de votre modèle. Nous vous recommandons de créer des tests à l'aide du Jest Testing Framework, mais toutes les suites de tests fonctionnent. L'extrait suivant montre une exécution de validation hypothétique. Notez que nous nous attendons à ce que la réponse d'évaluation soit un JSON valide. Nous utilisons donc JSON.parse pour récupérer le JSON à partir de la réponse sous forme de chaîne :

const AWS = require('aws-sdk')
const fs = require('fs')
const client = new AWS.AppSync({ region: 'us-east-2' })

test('request correctly calls DynamoDB', async () => {
  const template = fs.readFileSync('./request.vtl', 'utf8')
  const context = fs.readFileSync('./context.json', 'utf8')
  const contextJSON = JSON.parse(context)
  
  const response = await client.evaluateMappingTemplate({ template, context }).promise()
  const result = JSON.parse(response.evaluationResult)
  
  expect(result.key.id.S).toBeDefined()
  expect(result.attributeValues.firstname.S).toEqual(contextJSON.arguments.firstname)
})

Cela donne le résultat suivant :

Ran all test suites.
> jest

PASS ./index.test.js
✓ request correctly calls DynamoDB (543 ms)

Test Suites: 1 passed, 1 total
Tests: 1 passed, 1 total
Snapshots: 0 total
Time: 1.511 s, estimated 2 s

Débogage d'une requête en direct

Rien ne remplace un end-to-end test et une journalisation pour déboguer une application de production. AWS AppSync vous permet de consigner les erreurs et de fournir les détails complets des demandes à l'aide d'Amazon CloudWatch. De plus, vous pouvez utiliser la console AWS AppSync pour tester les requêtes, les mutations et les abonnements GraphQL, ainsi que les données de journalisation des flux en direct de chaque demande dans l'éditeur de requête afin de déboguer en temps réel. Pour les abonnements, les journaux affichent les informations de temps de connexion.

Pour ce faire, vous devez activer Amazon CloudWatch Logs à l'avance, comme décrit dans Surveillance et journalisation. Ensuite, dans la console AWS AppSync , choisissez l'onglet Requêtes et saisissez une requête GraphQL valable. Dans la section inférieure droite, cliquez et faites glisser la fenêtre Logs pour ouvrir la vue des logs. À l'aide de la flèche « Play » en haut de la page, exécutez votre requête GraphQL. Dans quelques instants, vos journaux complets de demande et de réponse pour l'opération sont diffusés vers cette section et vous pouvez les voir dans la console.