Información general sobre la plantilla de mapeo de - AWS AppSync

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Información general sobre la plantilla de mapeo de

AWSAppSync le permite responder a solicitudes de GraphQL realizando operaciones en sus recursos. Para cada campo de GraphQL en el que desee ejecutar una consulta o mutación, se debe asociar un solucionador a fin de comunicarse con un origen de datos. La comunicación se realiza normalmente a través de parámetros u operaciones que son exclusivos para cada origen de datos.

Los solucionadores son los conectores entre GraphQL y un origen de datos. DicenAWSAppSync 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 solucionadores 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 conviértala 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 uno o másfuncionesque se realizan en orden secuencial. Cada función incluye una plantilla de solicitud y una plantilla de respuesta. Un solucionador de canalizaciones también tiene unanteplantilla ydespuésplantilla que rodea la secuencia de funciones que contiene la plantilla. LadespuésLa plantilla se mapea al tipo de resultado del campo GraphQL. Los solucionadores de canalización difieren de los solucionadores de unidades en la forma en que la plantilla de respuesta asigna la salida. Un solucionador de canalizaciones puede asignarse a cualquier salida que desee, incluida la entrada de otra función o eldespuésPlantilla del solucionador de canalización.

Solucionador de canalizaciónfuncionespermite escribir lógica común que puede volver a utilizar en varios solucionadores del esquema. Las funciones 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.

El siguiente diagrama muestra el flujo de proceso de un solucionador de unidades a la izquierda y un solucionador de canalizaciones a la derecha.


            Diagrama de un solucionador de unidades que se comunica con un único origen de datos y un diagrama de un solucionador de canalizaciones que se comunica con varias fuentes de datos.

Los solucionadores de canalización contienen un superconjunto de la funcionalidad que admiten los solucionadores de unidad, entre otros, a costa de un poco más de complejidad.

Ejemplo de plantilla de de

Por ejemplo, supongamos que tiene un origen de datos de DynamoDB y un objetoUnidadsolucionador en un campo denominadogetPost(id:ID!)que devuelve un objetoPostescriba con la siguiente consulta de GraphQL:

getPost(id:1){ id title content }

La plantilla del solucionador puede ser parecida a la siguiente:

{ "version" : "2018-05-29", "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" : "2018-05-29", "operation" : "GetItem", "key" : { "id" : { "S" : "1" } } }

AWSAppSync utiliza esta plantilla para generar instrucciones para comunicarse con DynamoDB y obtener datos (o realizar otras operaciones, según corresponda). Una vez devueltos los datos,AWSAppSync lo ejecuta a través de 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:

$util.toJson($context.result)

Para las listas, la transferencia suele ser:

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

Para ver más ejemplos de solucionadores de unidad y canalización, consulteTutoriales de solucionador.

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

Las plantillas de asignación se evalúan en función de una cadena. EnAWSAppSync, la cadena de resultado 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": "2018-05-29", "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": "2018-05-29", "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.