Información general sobre las plantillas de mapeo de solucionador - AWS AppSync

Información general sobre las plantillas de mapeo de solucionador

Con AWS AppSync puede responder a solicitudes de GraphQL efectuando operaciones en sus recursos. Para cada campo de GraphQL que desee ejecutar, como, por ejemplo, una consulta o mutación, se debe asociar un solucionador a fin de comunicarse con un origen de datos. Normalmente, la comunicación se realiza a través de parámetros u operaciones que son exclusivos para cada origen de datos.

Las plantillas de mapeo son una forma de indicar a AWS AppSync cómo convertir una solicitud de GraphQL entrante en instrucciones para el origen de datos y cómo convertir la respuesta de ese origen de datos en un respuesta de GraphQL. Están escritas en Apache Velocity Template Language (VTL), que toma su solicitud como entrada y genera una salida en forma de documento JSON con las instrucciones para el solucionador. Puede utilizar plantillas de mapeo para instrucciones sencillas, como transferencias en argumentos de campos de GraphQL, o para instrucciones más complejas, como bucles que recorran argumentos para crear un elemento antes de insertarlo en DynamoDB. Existen dos tipos de solucionadores en AppSync que aprovechan las plantillas de mapeo de maneras ligeramente distintas: solucionadores de unidad y de canalización.

Solucionadores de unidad

Los solucionadores de unidad son entidades autónomas que incluyen solo una plantilla de solicitud y respuesta. Utilícelos para operaciones sencillas y únicas, como enumerar elementos de un único origen de datos.

  • Plantillas de solicitud: Toman la solicitud entrante después de analizar una operación de GraphQL y la convierten en una configuración de solicitud para la operación del origen de datos seleccionado.

  • Plantillas de respuesta: Interpretan respuestas del origen de datos y las mapean a la forma del tipo de resultado del campo GraphQL.

Solucionadores de canalización

Los solucionadores de canalización contienen una o varias funciones que se ejecutan en orden. Cada función incluye una plantilla de solicitud y respuesta, y opera de forma similar, pero no exactamente del mismo modo que los solucionadores de unidad. La diferencia es que la plantilla de respuesta puede mapearse a cualquier resultado que desee, lo que podría ser la entrada de otra función o la plantilla Después del solucionador de canalización. El solucionador de canalización también tiene una plantilla Antes y Después alrededor de la secuencia de ejecución de funciones. La plantilla Después se mapea al tipo de salida del campo GraphQL. Los solucionadores de canalización contienen un superconjunto de la funcionalidad que ofrecen los solucionadores de unidad, entre otros, por el costo de un poco más de complejidad.

Las funciones permiten escribir lógica común para su reutilización en varios solucionadores de su esquema. Están asociadas directamente a un origen de datos y, como un solucionador de unidad, contienen el mismo formato de plantilla de mapeo de solicitud y respuesta.

A continuación se muestra un diagrama paralelo de solucionadores de unidad (izquierda) y de canalización (derecha).

Ejemplo de plantilla

Por ejemplo, supongamos que tiene un origen de datos de DynamoDB y un solucionador de unidad para un campo llamado getPost(id:ID!) que devuelve un tipo Post con la consulta de GraphQL siguiente:

getPost(id:1){ id title content }

La plantilla del solucionador puede ser parecida a la siguiente:

{ "version" : "2017-02-28", "operation" : "GetItem", "key" : { "id" : $util.dynamodb.toDynamoDBJson($ctx.args.id) } }

Esto sustituiría el valor 1 del parámetro de entrada id para ${ctx.args.id} y generaría el siguiente JSON:

{ "version" : "2017-02-28", "operation" : "GetItem", "key" : { "id" : { "S" : "1" } } }

AWS AppSync utiliza esta plantilla para generar instrucciones para comunicarse con DynamoDB y obtener datos (o realizar otras operaciones, según corresponda). Una vez que se devuelven los datos, AWS AppSync los pasa por una plantilla de mapeo de respuesta opcional que puede utilizar para dar forma los datos o efectuar operaciones lógicas. Por ejemplo, cuando se obtienen los resultados de DynamoDB podrían tener este aspecto:

{ "id" : 1, "theTitle" : "AWS AppSync works offline!", "theContent-part1" : "It also has realtime functionality", "theContent-part2" : "using GraphQL" }

Puede elegir unir dos de los campos en uno solo con la siguiente plantilla de mapeo de respuesta:

{ "id" : $util.toJson($context.data.id), "title" : $util.toJson($context.data.theTitle), "content" : $util.toJson("${context.data.theContent-part1} ${context.data.theContent-part2}") }

Esta es la forma de los datos después de aplicarles la plantilla:

{ "id" : 1, "title" : "AWS AppSync works offline!", "content" : "It also has realtime functionality using GraphQL" }

Estos datos se entregan como respuesta al cliente de este modo:

{ "data": { "getPost": { "id" : 1, "title" : "AWS AppSync works offline!", "content" : "It also has realtime functionality using GraphQL" } } }

Observe que, en la mayoría de los casos, las plantillas de mapeo de respuesta simplemente transfieren los datos, y en ellas la máxima diferencia consiste en devolver un elemento individual o una lista de elementos. En el caso de un elemento individual la transferencia es:

$utils.toJson($context.result)

Para las listas, la transferencia suele ser:

$utils.toJson($context.result.items)

Para ver más ejemplos de solucionadores de unidad y canalización, consulte los tutoriales de solucionadores.

Reglas de deserialización de plantillas de asignación evaluadas

Las plantillas de asignación se evalúan en función de una cadena. En AWS AppSync, la cadena resultante debe seguir una estructura JSON para ser válida.

Además, se aplican las siguientes reglas de deserialización.

No se permiten claves duplicadas en objetos JSON

Si la cadena de la plantilla de asignación evaluada representa un objeto JSON o contiene un objeto con claves duplicadas, la plantilla de asignación devuelve el siguiente mensaje de error:

Duplicate field 'aField' detected on Object. Duplicate JSON keys are not allowed.

Ejemplo de una clave duplicada en una plantilla de asignación de solicitudes evaluada:

{ "version": "2017-02-28", "operation": "Invoke", "payload": { "field": "getPost", "postId": "1", "field": "getPost" ## key 'field' has been redefined } }

Para corregir este error, no redefina las claves en objetos JSON.

No se permiten caracteres finales en objetos JSON

Si la cadena de la plantilla de asignación evaluada representa un objeto JSON y contiene caracteres extraños al final, la plantilla de asignación devuelve el siguiente mensaje de error:

Trailing characters at the end of the JSON string are not allowed.

Ejemplo de caracteres finales en una plantilla de asignación de solicitudes evaluada:

{ "version": "2017-02-28", "operation": "Invoke", "payload": { "field": "getPost", "postId": "1", } }extraneouschars

Para corregir este error, asegúrese de que las plantillas evaluadas se evalúen estrictamente en función de JSON.