Pruebas y depuración de solucionadores en AWS AppSync (VTL)

AWS AppSync ejecuta solucionadores en un campo de GraphQL con respecto a un origen de datos. Como se describe en Resolver mapping template overview, los solucionadores se comunican con los orígenes de datos mediante un lenguaje de plantillas. Esto permite personalizar el comportamiento y aplicar lógica y condiciones antes y después de comunicarse con el origen de datos. Encontrará una guía de programación introductoria similar a un tutorial para escribir solucionadores en Resolver mapping template programming guide.

A fin de ayudar a los desarrolladores a escribir, probar y depurar estos solucionadores, la consola de AWS AppSync también proporciona herramientas para crear una solicitud y una respuesta de GraphQL con datos simulados, incluso hasta llegar al solucionador de cada campo individual. Además, puede realizar consultas, mutaciones y suscripciones en la consola de AWS AppSync y ver un flujo de registro detallado de toda la solicitud desde Amazon CloudWatch. Esto incluye los resultados del origen de datos.

Prueba con datos simulados

Cuando se invoca a un solucionador de GraphQL, este contiene un objeto context que incluye información sobre la solicitud. Por ejemplo, contiene los argumentos de un cliente, información de identidad y datos del campo principal de GraphQL. También contiene los resultados del origen de datos, que puede usar en la plantilla de respuesta. Si desea más información acerca de esta estructura y las utilidades auxiliares disponibles para programar, consulte la Referencia del contexto de las plantillas de mapeo de solucionador.

Al escribir o editar un solucionador, puede pasar un objeto simulado o de contexto de prueba al editor de la consola. Esto le permite ver cómo se evalúan la plantillas de solicitud y de respuesta sin que se utilice en realidad ningún origen de datos. Por ejemplo, puede transferir un argumento firstname: Shaggy de prueba y ver cómo se evalúa cuando utiliza $ctx.args.firstname en el código de la plantilla. También puede probar la evaluación de cualquier utilidad auxiliar, como $util.autoId() o util.time.nowISO8601().

Prueba de solucionadores

En este ejemplo, se utilizará la consola de AWS AppSync para probar los solucionadores.

Veamos un ejemplo más práctico. Imagine que tiene una aplicación que almacena un tipo de GraphQL llamado Dog, que genera automáticamente un identificador para los objetos y los almacena en Amazon DynamoDB. También desea escribir algunos valores tomándolos de los argumentos de una mutación de GraphQL y permitir que solo determinados usuarios vean la respuesta. El esquema podría tener el siguiente aspecto:

type Dog {
  breed: String
  color: String
}

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

Al añadir un solucionador para la mutación addDog, puede rellenar un objeto de contexto como el que aparece en el ejemplo a continuación. Se incluyen argumentos del cliente como name y age, así como un username rellenado en el objeto 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"
    }
}

Puede probarlo utilizando las siguientes plantillas de mapeo de solicitud y de respuesta:

Plantilla de solicitud

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

Plantilla de respuesta

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

La plantilla evaluada tiene los datos del objeto de contexto de prueba y el valor generado por $util.autoId(). Además, si cambia el username por un valor distinto de Nadia, no se devolverán resultados, porque la comprobación de autorización daría error. Para obtener más información acerca del control de acceso preciso, consulte Casos de uso de autorizaciones.

Prueba de plantillas de mapeo con las API de AWS AppSync

Puede usar el comando de API EvaluateMappingTemplate para probar las plantillas de mapeo de forma remota con datos simulados. Para empezar a usar el comando, asegúrese de haber añadido el permiso appsync:evaluateMappingTemplate a su política. Por ejemplo:

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

Puede utilizar el comando mediante la AWS CLI o los SDK de AWS. Tomemos como ejemplo el esquema Dog y sus plantillas de mapeo de solicitudes/respuestas de la sección anterior. Con la CLI de la estación local, guarde la plantilla de solicitudes en un archivo denominado request.vtl y, a continuación, guarde el objeto context en un archivo denominado context.json. Ejecute el siguiente comando desde el intérprete de comandos:

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

El comando devuelve la siguiente respuesta:

{
  "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"
}

evaluationResultContiene los resultados de la prueba de la plantilla proporcionada con el context proporcionado. También puede probar sus plantillas con los SDK de AWS. A continuación, se muestra un ejemplo del uso del SDK de AWS para JavaScript V2:

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

Cuando se utiliza el SDK, puede incorporar fácilmente pruebas de su conjunto de pruebas favorito para validar el comportamiento de la plantilla. Recomendamos crear pruebas con el marco de pruebas Jest, pero cualquier conjunto de pruebas funciona. En el siguiente fragmento de código se muestra una ejecución de validación hipotética. Tenga en cuenta que esperamos que la respuesta de la evaluación sea un JSON válido, por lo que utilizamos JSON.parse para recuperar el JSON de la respuesta de cadena:

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

Esto produce el siguiente resultado:

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

Depuración de una consulta en tiempo real

No hay nada que pueda reemplazar a una prueba de extremo a extremo y el registro para depurar una aplicación de producción. AWS AppSync permite registrar los errores y todos los detalles de cada solicitud mediante Amazon CloudWatch. Además, puede utilizar la consola de AWS AppSync para probar las consultas, mutaciones y suscripciones de GraphQL y enviar los datos de registro de cada solicitud al editor de consultas para depurarlas en tiempo real. Para las suscripciones, los registros muestran la información del tiempo de conexión.

Para ello, debe haber habilitado previamente los registros de Amazon CloudWatch como se describe en Monitoreo y registro. A continuación, en la consola de AWS AppSync, elija la pestaña Consultas y escriba en una consulta de GraphQL válida. En la sección inferior derecha, haga clic y arrastre la ventana Registros para abrir la vista de registros. Utilice el icono de flecha de reproducción de la parte superior de la página para ejecutar la consulta de GraphQL. Al cabo de unos momentos, los registros completos de la solicitud y la respuesta de la operación se enviarán a esta sección y podrá verlos en la consola.