Descripción general de los solucionadores de JavaScript de AWS AppSync

Con AWS AppSync puede responder a solicitudes de GraphQL efectuando operaciones en sus orígenes de datos. Para cada campo de GraphQL en el que desee ejecutar una consulta, mutación o suscripción, se debe asociar un solucionador.

Los solucionadores son los conectores entre GraphQL y un origen de datos. Indican a AWS AppSync cómo convertir una solicitud de GraphQL entrante en instrucciones para el origen de datos de backend y cómo convertir la respuesta de ese origen de datos en una respuesta de GraphQL. Con AWS AppSync, puede escribir sus solucionadores mediante JavaScript y ejecutarlos en el entorno de AWS AppSync (APPSYNC_JS).

AWS AppSync permite escribir solucionadores de unidad o solucionadores de canalización que constan de varias funciones de AWS AppSync en una canalización.

Características de la versión ejecutable compatibles

La versión ejecutable de JavaScript de AWS AppSync proporciona un subconjunto de bibliotecas, utilidades y características. Para obtener una lista completa de las características y funcionalidades compatibles con la versión ejecutable APPSYNC_JS, consulte el artículo sobre las características de la versión ejecutable de JavaScript para solucionadores y funciones.

Solucionadores de unidad

Un solucionador de unidad se compone de código que define un controlador de solicitudes y respuestas que se ejecutan con un origen de datos. El controlador de solicitudes toma un objeto de contexto como argumento y devuelve la carga de la solicitud utilizada para llamar al origen de datos. El controlador de respuestas recibe una carga útil del origen de datos con el resultado de la solicitud ejecutada. El controlador de respuestas transforma la carga útil en una respuesta de GraphQL para resolver el campo de GraphQL. En el ejemplo siguiente, un solucionador recupera un elemento de un origen de datos de DynamoDB:

import * as ddb from '@aws-appsync/utils/dynamodb'

export function request(ctx) {
  return ddb.get({ key: { id: ctx.args.id } });
}

export const response = (ctx) => ctx.result;

Anatomía de un solucionador de canalización de JavaScript

Un solucionador de canalización se compone de un código que define un controlador de solicitudes y respuestas y una lista de funciones. Cada función tiene un controlador de solicitudes y respuestas que ejecuta con un origen de datos. Puesto que un solucionador de canalización delega las ejecuciones a una lista de funciones, no está vinculado a ningún origen de datos. Las funciones y los solucionadores de unidad son primitivos que ejecutan la operación frente a los orígenes de datos.

Controlador de solicitudes del solucionador de canalización

El controlador de solicitudes de un solucionador de canalización (el paso Before (Antes)) permite crear alguna lógica de preparación antes de ejecutar las funciones definidas.

Lista de funciones

La lista de funciones de un solucionador de canalización se ejecutará de forma secuencial. El resultado de la evaluación del controlador de solicitudes del solucionador de canalización estará disponible para la primera función como ctx.prev.result. El resultado de la evaluación de cada función está disponible para la siguiente función como ctx.prev.result.

Controlador de respuestas del solucionador de canalización

El controlador de respuestas de un solucionador de canalización permite realizar alguna lógica final a partir del resultado de la última función al tipo de campo GraphQL esperado. El resultado de la última función en lista de funciones está disponible en el controlador de respuestas del solucionador de canalización como ctx.prev.result o ctx.result.

Flujo de la ejecución

Con un solucionador de canalización compuesto por dos funciones, la lista siguiente representa el flujo de ejecución cuando se invoca el solucionador:

Utilidades integradas de tiempo de ejecución APPSYNC_JS prácticas

Las siguientes utilidades pueden ayudar cuando se trabaja con solucionadores de canalización.

ctx.stash

El stash es un objeto que está disponible dentro de cada solucionador y controlador de solicitudes y respuestas de función. La misma instancia stash vive en una única ejecución de solucionador. Esto significa que puede utilizar el stash para pasar datos arbitrarios a controladores de solicitudes y respuestas, así como a las funciones de un solucionador de canalización. Puede probar el stash como un objeto de JavaScript normal.

ctx.prev.result

El ctx.prev.result representa el resultado de la operación anterior que se ha ejecutado en la canalización. Si la operación anterior era el controlador de solicitudes del solucionador de canalización, entonces ctx.prev.result estará disponible para la primera función de la cadena. Si la operación anterior era la primera función, entonces ctx.prev.result representa el resultado de la primera función y estará disponible para la segunda función de la canalización. Si la operación anterior era la última función, entonces ctx.prev.result representa el resultado de la última función y estará disponible para el controlador de respuestas del solucionador de canalización.

util.error

La utilidad util.error es útil para lanzar un error de campo. El uso de util.error dentro de un controlador de solicitudes o respuestas de función genera un error de campo inmediatamente, lo que impide que se ejecuten funciones posteriores. Para obtener información más detallada y otras firmas de util.error, visite el artículo sobre las características de la versión ejecutable de JavaScript para solucionadores y funciones.

util.appendError

El util.appendError es similar a util.error(), siendo la principal diferencia que no interrumpe la evaluación del controlador. En su lugar, indica que hubo un error con el campo, pero permite evaluar el controlador y, por tanto, devolver los datos. El uso de util.appendError dentro de una función no interrumpe el flujo de ejecución de la canalización. Para obtener información más detallada y otras firmas de util.error, visite el artículo sobre las características de la versión ejecutable de JavaScript para solucionadores y funciones.

runtime.earlyReturn

La función runtime.earlyReturn permite volver de forma prematura de cualquier función de solicitud. Al utilizar runtime.earlyReturn dentro de un controlador de solicitudes del solucionador volverá desde el solucionador. Si se llama desde un controlador de solicitudes de función de AWS AppSync volverá desde la función y continuará la ejecución a la siguiente función del controlador de respuestas del solucionador o canalización.

Escritura de solucionadores de canalización

Un solucionador de canalización también tiene un controlador de solicitudes y otro de respuestas relacionados con la ejecución de las funciones en la canalización: su controlador de solicitudes se ejecuta antes de la solicitud de la primera función y su controlador de respuestas lo hace después de la respuesta de la última función. El controlador de solicitudes del solucionador puede configurar los datos para que las funciones de la canalización los utilicen. El controlador de respuestas del solucionador es responsable de devolver los datos que se mapean al tipo de salida del campo GraphQL. En el siguiente ejemplo, un controlador de solicitudes del solucionador define allowedGroups; los datos devueltos deben pertenecer a uno de estos grupos. Las funciones del solucionador pueden utilizar este valor para solicitar datos. El controlador de respuestas del solucionador realiza una comprobación final y filtra el resultado para asegurarse de que solo se devuelvan los elementos pertenecientes a los grupos permitidos.

import { util } from '@aws-appsync/utils';

/**
 * Called before the request function of the first AppSync function in the pipeline.
 *  @param ctx the context object holds contextual information about the function invocation.
 */
export function request(ctx) {
  ctx.stash.allowedGroups = ['admin'];
  ctx.stash.startedAt = util.time.nowISO8601();
  return {};
}
/**
 * Called after the response function of the last AppSync function in the pipeline.
 * @param ctx the context object holds contextual information about the function invocation.
 */
export function response(ctx) {
  const result = [];
  for (const item of ctx.prev.result) {
    if (ctx.stash.allowedGroups.indexOf(item.group) > -1) result.push(item);
  }
  return result;
}

Escritura de las funciones de AWS AppSync

Las funciones de AWS AppSync permiten escribir lógica común que puede reutilizar en varios solucionadores de su esquema. Por ejemplo, puede tener una función de AWS AppSync llamada QUERY_ITEMS responsable de consultar los elementos de un origen de datos de Amazon DynamoDB. En el caso de los solucionadores con los que desea consultar elementos, solo tiene que añadir la función a la canalización del solucionador y proporcionar el índice de consulta que se va a usar. No es necesario volver a implementar la lógica.

Temas complementarios

Temas