Visão geral dos resolvedores de JavaScript do AWS AppSync

O AWS AppSync permite responder a solicitações do GraphQL executando operações nas suas fontes de dados. Para cada campo do GraphQL em que você deseja executar uma consulta, mutação ou assinatura, um resolvedor deve ser anexado.

Os resolvedores são os conectores entre o GraphQL e uma fonte de dados. Eles indicam ao AWS AppSync como traduzir uma solicitação do GraphQL recebida em instruções para a fonte de dados back-end e como traduzir a resposta da fonte de dados de volta em uma resposta do GraphQL. Com o AWS AppSync, você pode escrever seus resolvedores usando JavaScript e executá-los no ambiente do AWS AppSync (APPSYNC_JS).

O AWS AppSync permite que você escreva resolvedores de unidade ou de pipeline compostos por várias funções do AWS AppSync em um pipeline.

Atributos compatíveis de runtime

O runtime de JavaScript do AWS AppSync fornece um subconjunto de bibliotecas, utilitários e atributos de JavaScript. Para obter uma lista completa dos atributos e funcionalidades suportados pelo runtime APPSYNC_JS, consulte Atributos de runtime do JavaScript para resolvedores e funções.

Resolvedores de unidade

Um resolvedor de unidade é composto de código que define um único manipulador de solicitação e resposta que é executado em uma fonte de dados. O manipulador da solicitação usa um objeto de contexto como argumento e retorna o payload da solicitação usado para chamar sua fonte de dados. O manipulador de respostas recebe uma payload da fonte de dados com o resultado da solicitação executada. O manipulador de resposta transforma o payload em uma resposta do GraphQL para resolver o campo GraphQL. No exemplo abaixo, um resolvedor recupera um item de uma fonte de dados do 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;

Anatomia de um resolvedor de pipeline do JavaScript

Um resolvedor de pipeline é composto de código que define um manipulador de solicitação e resposta e uma lista de funções. Cada função possui um manipulador de solicitação e resposta que é executado em uma fonte de dados. Como um resolvedor de pipeline delega a execução a uma lista de funções, ele não está vinculado a nenhuma fonte de dados. Os resolvedores de unidade e funções que executam a operação mediante fontes de dados são primitivos.

Manipulador de solicitações do resolvedor de pipeline

O manipulador de solicitação de um resolvedor de pipeline, ou etapa Anterior, permite executar uma lógica de preparação antes de executar as funções definidas.

Lista de funções

A lista de funções que um resolvedor de pipeline executará em sequência. O resultado do manipulador da solicitação do resolvedor de pipeline é disponibilizado para a primeira função como ctx.prev.result. Cada resultado da avaliação da função está disponível para a próxima função como ctx.prev.result.

Manipulador de resposta do resolvedor de pipeline

O modelo de resposta de um resolvedor de pipeline permite executar uma lógica final na saída da última função para o tipo de campo do GraphQL esperado. A saída da última função na lista de funções está disponível no manipulador de resposta do resolvedor de pipeline, como ctx.prev.result ou ctx.result.

Fluxo de execução

Considerando um resolvedor de pipeline composto de duas funções, a lista abaixo representa o fluxo de execução quando o resolvedor é invocado:

Utilitários integrados úteis do runtime APPSYNC_JS

Os utilitários a seguir podem ajudá-lo quando você estiver trabalhando com resolvedores de pipeline.

ctx.stash

O stash é um objeto disponibilizado dentro de cada manipulador de resposta e solicitação de resolvedor e função. A mesma instância stash passa por uma única execução do resolvedor. Isso significa que é possível usar o stash para enviar dados arbitrários entre os manipuladores de solicitações e respostas e entre as funções em um resolvedor de pipeline. Você pode testar o stash como um objeto JavaScript normal.

ctx.prev.result

O ctx.prev.result representa o resultado da operação anterior que foi executada no pipeline. Se a operação anterior foi o manipulador de solicitações do resolvedor de pipeline, ctx.prev.result será disponibilizado para a primeira função no encadeamento. Se a operação anterior foi a primeira função, ctx.prev.result representa a saída da primeira função e será disponibilizado para a segunda função no pipeline. Se a operação anterior foi a última função, ctx.prev.result representa a saída da última função e será disponibilizado para o manipulador de resposta do resolvedor de pipeline.

util.error

O utilitário util.error é útil para gerar um erro de campo. Usar util.error dentro de um manipulador de solicitação ou resposta de função gera um erro de campo imediatamente, o que impede que funções subsequentes sejam executadas. Para obter mais detalhes e outras assinaturas util.error, visite os atributos de runtime do JavaScript para resolvedores e funções.

util.appendError

O util.appendError é semelhante a util.error(), com a principal distinção de que ele não interrompe a avaliação do manipulador. Em vez disso, ele sinaliza que ocorreu um erro com o campo, mas permite que o manipulador seja avaliado e, consequentemente, retorne dados. Usar util.appendError dentro de uma função não interromperá o fluxo de execução do pipeline. Para obter mais detalhes e outras assinaturas util.error, visite Atributos de runtime do JavaScript para resolvedores e funções.

runtime.earlyReturn

A função runtime.earlyReturn permite que você gere resultados prematuramente para qualquer função de solicitação. Usar runtime.earlyReturn em um manipulador de solicitações do resolvedor retornará resultados do resolvedor. Chamá-lo em um manipulador de solicitação de função AWS AppSync retornará resultados a partir da função e continuará a execução até a próxima função no pipeline ou o manipulador de resposta do resolvedor.

Escrever resolvedores de pipeline

Um resolvedor de pipeline também tem um manipulador de solicitação e resposta para a execução das funções no pipeline: o manipulador de solicitação é executado antes da solicitação da primeira função, e o manipulador de resposta é executado após a resposta da última função. O manipulador de solicitação do resolvedor pode configurar dados para serem usados pelas funções no pipeline. O manipulador de resposta do resolvedor é responsável por retornar dados que são mapeados para o tipo de saída do campo GraphQL. No exemplo abaixo, um manipulador de solicitação do resolvedor define allowedGroups; os dados retornados devem pertencer a um desses grupos. Esse valor pode ser usado pelas funções do resolvedor para solicitar dados. O manipulador de resposta do resolvedor realiza uma verificação final e filtra o resultado para garantir que somente os itens que pertencem aos grupos permitidos sejam retornados.

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

Escrever funções AWS AppSync

As funções do AWS AppSync permitem que você escreva uma lógica comum que pode ser reutilizada em vários resolvedores no seu esquema. Por exemplo, você pode ter uma função do AWS AppSync chamada QUERY_ITEMS que é responsável por consultar itens de uma fonte de dados do Amazon DynamoDB. Para resolvedores com os quais você gostaria de consultar itens, basta adicionar a função ao pipeline do resolvedor e fornecer o índice de consulta a ser usado. A lógica não precisa ser reimplementada.

Tópicos complementares

Tópicos