As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# Estruturação de uma API GraphQL (em branco ou importada) APIs
Antes de criar sua API GraphQL a partir de um modelo em branco, leia os conceitos sobre o GraphQL. Há três componentes fundamentais de uma API GraphQL:
1. O **esquema** é o arquivo que contém a forma e a definição dos seus dados. Quando uma solicitação é feita por um cliente ao seu serviço do GraphQL, os dados retornados seguem a especificação do esquema. Para obter mais informações, consulte [Esquemas do GraphQL](schema-components.md#aws-appsync-schema-components).
1. A **fonte de dados** é anexada ao seu esquema. Quando uma solicitação é feita, os dados são recuperados e modificados. Para obter mais informações, consulte [Fontes de dados](data-source-components.md#aws-appsync-data-source-components).
1. O **resolvedor** fica entre o esquema e a fonte de dados. Quando uma solicitação é feita, o resolvedor executa a operação nos dados da fonte e retorna o resultado como resposta. Para obter mais informações, consulte [Resolvedores](resolver-components.md#aws-appsync-resolver-components).
![\[GraphQL API architecture showing schema, resolvers, and data sources connected via AppSync.\]](http://docs.aws.amazon.com/pt_br/appsync/latest/devguide/images/appsync-architecture-graphql-api.png)
AWS AppSync gerencia você, APIs permitindo que você crie, edite e armazene o código para seus esquemas e resolvedores. Suas fontes de dados serão provenientes de repositórios externos, como bancos de dados, tabelas do DynamoDB e funções do Lambda. Se você estiver usando um AWS serviço para armazenar seus dados ou estiver planejando fazer isso, AWS AppSync oferece uma experiência quase perfeita ao associar dados de suas contas AWS ao seu GraphQL. APIs
Na próxima seção, você aprenderá a criar cada um desses componentes usando o AWS AppSync serviço.
**Topics**
+ [Como projetar seu esquema GraphQL](designing-your-schema.md)
+ [Como anexar uma fonte de dados](attaching-a-data-source.md)
+ [Configuração de resolvedores do AWS AppSync](resolver-config-overview.md)
+ [Usando APIs com o CDK](using-your-api.md)
# Como projetar seu esquema GraphQL
O esquema GraphQL é a base de qualquer implementação de servidor de GraphQL. Cada API GraphQL é definida por um **único** esquema que contém tipos e campos que descrevem como os dados das solicitações serão preenchidos. Os dados que fluem pela sua API e as operações realizadas devem ser validados com base no esquema.
O [sistema do tipo GraphQL](https://graphql.org/learn/schema/#type-system) descreve os recursos de um servidor de GraphQL e é usado para determinar se uma consulta é válida. Um sistema de tipo de servidor geralmente é chamado de esquema e pode consistir em diferentes tipos de objetos, escalares, entradas, entre outros. O GraphQL é declarativo e fortemente tipificado, o que significa que os tipos serão bem definidos no runtime e retornarão somente o que foi especificado.
AWS AppSync permite que você defina e configure esquemas do GraphQL. A seção a seguir descreve como criar esquemas do GraphQL do zero usando AWS AppSync os serviços da.
## Estruturar um esquema do GraphQL
**dica**
Consulte a seção [Schemas](https://docs.aws.amazon.com//appsync/latest/devguide/schema-components.html) antes de continuar.
O GraphQL é uma ferramenta poderosa para implementar serviços de API. A descrição (em tradução livre) no [site do GraphQL](https://graphql.org/) é a seguinte:
“O *GraphQL é uma linguagem de consulta APIs e um tempo de execução para atender essas consultas com seus dados existentes. O GraphQL fornece uma descrição completa e compreensível dos dados em sua API, dá aos clientes o poder de pedir exatamente o que precisam e nada mais, facilita a evolução ao APIs longo do tempo e habilita ferramentas poderosas para desenvolvedores.* “
Esta seção aborda a primeira parte da sua implementação do GraphQL, o esquema. De acordo com a citação acima, um esquema “fornece uma descrição completa e clara dos dados em sua API”. Em outras palavras, um esquema do GraphQL é uma representação textual dos dados, das operações e das relações entre eles referentes ao seu serviço. O esquema é considerado o principal ponto de entrada para a implementação do serviço do GraphQL. Não é de surpreender que muitas vezes seja uma das primeiras coisas que você faz em seu projeto. Consulte a seção [Schemas](https://docs.aws.amazon.com//appsync/latest/devguide/schema-components.html) antes de continuar.
Citando a seção [Schemas](https://docs.aws.amazon.com//appsync/latest/devguide/schema-components.html), os esquemas do GraphQL são escritos em *Schema Definition Language* (SDL). O SDL é composto por tipos e campos com uma estrutura estabelecida:
+ **Tipos**: os tipos são como o GraphQL define a forma e o comportamento dos dados. O GraphQL é compatível com uma infinidade de tipos que serão explicados ainda nesta seção. Cada um dos tipos definidos em seu esquema terá um escopo próprio. Dentro do escopo, um ou mais campos vão apresentar um valor ou lógica que será usada em seu serviço do GraphQL. Os tipos têm muitas funções diferentes, sendo as mais comuns objetos ou escalares (tipos de valores primitivos).
+ **Campos**: os campos existem dentro do escopo de um tipo e contêm o valor solicitado do serviço do GraphQL. Eles são muito semelhantes às variáveis de outras linguagens de programação. A forma dos dados que você define em seus campos determinará como os dados são estruturados em uma request/response operação. Isso permite que os desenvolvedores prevejam o que será retornado sem saber como o back-end do serviço é implementado.
Os esquemas mais simples conterão três categorias de dados:
1. **Raízes do esquema**: as raízes definem os pontos de entrada do seu esquema. Elas apontam para os campos que realizarão alguma operação nos dados, como adicionar, excluir ou modificar algo.
1. **Tipos**: esses são tipos básicos usados para representar o formato dos dados. Eles são muito semelhantes a objetos ou representações abstratas de algo com características definidas. Por exemplo, você pode criar um objeto `Person` que represente uma pessoa em um banco de dados. As características de cada pessoa serão definidas dentro de `Person` como campos. Eles podem ser qualquer dado da pessoa, como o nome, a idade, o emprego, o endereço etc.
1. **Tipos de objetos especiais**: esses são os tipos que definem o comportamento das operações em seu esquema. Cada tipo de objeto especial é definido uma vez por esquema. Eles são colocados primeiro na raiz do esquema e, em seguida, definidos no corpo do esquema. Cada campo em um tipo de objeto especial define uma única operação a ser implementada pelo seu solucionador.
Para entender melhor, imagine que você esteja criando um serviço que armazena dados de autores de livros e suas obras. Cada autor tem um nome e uma série de livros escritos. Cada livro tem um nome e uma lista de autores associados. Além disso, queremos adicionar ou recuperar livros e autores. Uma representação UML simples desse relacionamento pode ser como esta:
![\[UML diagram showing Author and Book classes with attributes and methods, linked by association.\]](http://docs.aws.amazon.com/pt_br/appsync/latest/devguide/images/GraphQL-UML-1.png)
No GraphQL, as entidades `Author` e `Book` representam dois tipos diferentes de objetos em seu esquema:
```
type Author {
}
type Book {
}
```
`Author` contém `authorName` e `Books`, enquanto `Book` contém `bookName` e `Authors`. Eles podem ser representados como os campos dentro do escopo de seus tipos:
```
type Author {
authorName: String
Books: [Book]
}
type Book {
bookName: String
Authors: [Author]
}
```
Como você pode ver, as representações de tipo estão muito próximas do diagrama. No entanto, os métodos são os pontos mais complexos. Eles serão colocados em um dos poucos tipos de objetos especiais como um campo. A categorização como objeto especial depende do comportamento dele. O GraphQL contém três tipos fundamentais de objetos especiais: consultas, mutações e assinaturas. Para obter mais informações, consulte [Special objects](https://docs.aws.amazon.com//appsync/latest/devguide/graphql-types.html#special-object-components).
Como `getAuthor` e `getBook` estão solicitando dados, eles serão colocados em um tipo de objeto especial de `Query`:
```
type Author {
authorName: String
Books: [Book]
}
type Book {
bookName: String
Authors: [Author]
}
type Query {
getAuthor(authorName: String): Author
getBook(bookName: String): Book
}
```
As operações são vinculadas à consulta, que por sua vez está vinculada ao esquema. Adicionar uma raiz de esquema definirá o tipo de objeto especial (neste caso, `Query`) como um dos seus pontos de entrada. Isso pode ser feito usando a palavra-chave `schema`:
```
schema {
query: Query
}
type Author {
authorName: String
Books: [Book]
}
type Book {
bookName: String
Authors: [Author]
}
type Query {
getAuthor(authorName: String): Author
getBook(bookName: String): Book
}
```
Analisando os últimos dois métodos, `addAuthor` e `addBook` estão adicionando informações ao seu banco de dados para que sejam definidos em um tipo de objeto especial `Mutation`. No entanto, na página [Tipos](https://docs.aws.amazon.com/appsync/latest/devguide/graphql-types.html#input-components), não é permitido usar entradas que fazem referência direta a objetos, porque são tipos de saída. Nesse caso, não podemos usar `Author` nem `Book`, então precisamos criar um tipo de entrada com os mesmos campos. Neste exemplo, adicionamos `AuthorInput` e `BookInput`, que aceitam os mesmos campos de seus respectivos tipos. Em seguida, criamos nossa mutação usando as entradas como nossos parâmetros:
```
schema {
query: Query
mutation: Mutation
}
type Author {
authorName: String
Books: [Book]
}
input AuthorInput {
authorName: String
Books: [BookInput]
}
type Book {
bookName: String
Authors: [Author]
}
input BookInput {
bookName: String
Authors: [AuthorInput]
}
type Query {
getAuthor(authorName: String): Author
getBook(bookName: String): Book
}
type Mutation {
addAuthor(input: [BookInput]): Author
addBook(input: [AuthorInput]): Book
}
```
Vamos analisar o que acabamos de fazer:
1. Criamos um esquema com os tipos `Author` e `Book` para representar nossas entidades.
1. Adicionamos os campos contendo as características de nossas entidades.
1. Adicionamos uma consulta para recuperar essas informações do banco de dados.
1. Adicionamos uma mutação para manipular dados no banco de dados.
1. Adicionamos tipos de entrada para substituir nossos parâmetros de objeto na mutação para cumprir as regras do GraphQL.
1. Adicionamos a consulta e a mutação ao nosso esquema raiz para que a implementação do GraphQL identifique a localização do tipo raiz.
Como você pode notar, o processo de criação de um esquema usa muitos conceitos da modelagem de dados (especialmente da modelagem de banco de dados) em geral. Podemos dizer que o esquema se ajusta à forma dos dados da fonte. Ele também serve como o modelo que o solucionador implementará. Nas seções a seguir, você aprenderá como criar um esquema usando várias ferramentas e AWS serviços suportados.
**nota**
Os exemplos nas seções a seguir não devem ser executados em uma aplicação real. Eles apenas mostram os comandos para que você crie suas próprias aplicações.
## Criar esquemas
Seu esquema estará em um arquivo chamado`schema.graphql`. AWS AppSync permite que os usuários criem novos esquemas para seu APIs GraphQL usando vários métodos. Neste exemplo, criaremos uma API em branco junto com um esquema em branco.
------
#### [ Console ]
1. Faça login no Console de gerenciamento da AWS e abra o [AppSyncconsole](https://console.aws.amazon.com/appsync/).
1. No **Painel**, escolha **Criar API**.
1. **Em **Opções de API**, escolha **GraphQL APIs**, **Design from scratch** e Next.**
1. Para o **nome da API**, troque o nome pré-preenchido algo que seja necessário para a aplicação.
1. Para **obter detalhes de contato**, você pode inserir um ponto de contato para identificar um gerente para a API. Esse é um campo opcional.
1. Em **Configuração da API privada**, é possível habilitar os atributos da API privada. Uma API privada só pode ser acessada de um endpoint da VPC (VPCE) configurado. Para obter mais informações, consulte [Privado APIs](https://docs.aws.amazon.com/appsync/latest/devguide/using-private-apis.html).
Não recomendamos habilitar esse atributo para este exemplo. Após analisar suas entradas, selecione **Próximo**.
1. Em **Criar um tipo de GraphQL**, você pode criar uma tabela do DynamoDB para usar como fonte de dados ou ignorar e fazer isso depois.
Para este exemplo, escolha **Criar recursos do GraphQL mais tarde**. Vamos criar um recurso em uma seção separada.
1. Revise suas entradas e selecione **Criar API**.
1. Você estará no painel da sua API específica. É possível identificar o nome da API na parte superior do painel. Se esse não for o caso, você pode selecionar **APIs**na **barra lateral** e escolher sua API no **APIs painel**.
1. Na **barra lateral** abaixo do nome da sua API, escolha **Esquema**.
1. Você pode configurar seu arquivo `schema.graphql` no **editor de esquemas**. Ele pode estar vazio ou preenchido com tipos gerados a partir de um modelo. À direita, você tem a seção **Solucionadores** para anexar solucionadores aos campos do esquema. Não examinaremos os solucionadores nesta seção.
------
#### [ CLI ]
**nota**
Ao usar a CLI, verifique se você tem as permissões certas para acessar e criar recursos no serviço. Considere definir políticas de [privilégio mínimo](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege) para usuários não administradores que precisam acessar o serviço. Para obter mais informações sobre AWS AppSync políticas, consulte [Gerenciamento de identidade e acesso para AWS AppSync](https://docs.aws.amazon.com//appsync/latest/devguide/security-iam.html).
Além disso, recomendamos primeiro ler a versão do console.
1. Caso ainda não tenha feito isso, [instale](https://docs.aws.amazon.com//cli/latest/userguide/cli-chap-getting-started.html) e configure o AWS CLI e adicione sua [configuração](https://docs.aws.amazon.com//cli/latest/userguide/cli-configure-quickstart.html).
1. Crie um objeto da API GraphQL executando o comando [https://docs.aws.amazon.com/cli/latest/reference/appsync/create-graphql-api.html](https://docs.aws.amazon.com/cli/latest/reference/appsync/create-graphql-api.html).
Você precisará digitar dois parâmetros para esse comando específico:
1. O `name` da sua API.
1. O `authentication-type`, ou o tipo de credencial usado para acessar a API (IAM, OIDC etc.).
**nota**
Outros parâmetros, como `Region` devem ser configurados, mas geralmente usam como padrão os valores de configuração da CLI.
Veja um exemplo de comando:
```
aws appsync create-graphql-api --name testAPI123 --authentication-type API_KEY
```
Uma saída será retornada na CLI. Veja um exemplo abaixo:
```
{
"graphqlApi": {
"xrayEnabled": false,
"name": "testAPI123",
"authenticationType": "API_KEY",
"tags": {},
"apiId": "abcdefghijklmnopqrstuvwxyz",
"uris": {
"GRAPHQL": "https://zyxwvutsrqponmlkjihgfedcba.appsync-api.us-west-2.amazonaws.com/graphql",
"REALTIME": "wss://zyxwvutsrqponmlkjihgfedcba.appsync-realtime-api.us-west-2.amazonaws.com/graphql"
},
"arn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz"
}
}
```
1.
**nota**
Esse é um comando opcional que carrega um esquema existente no serviço do AWS AppSync usando um blob Base64. Não usaremos esse comando para preservar este exemplo.
Execute o comando [https://docs.aws.amazon.com/cli/latest/reference/appsync/start-schema-creation.html](https://docs.aws.amazon.com/cli/latest/reference/appsync/start-schema-creation.html).
Você precisará digitar dois parâmetros para esse comando específico:
1. Seu `api-id` da etapa anterior.
1. O esquema `definition` é um blob binário codificado com Base64.
Veja um exemplo de comando:
```
aws appsync start-schema-creation --api-id abcdefghijklmnopqrstuvwxyz --definition "aa1111aa-123b-2bb2-c321-12hgg76cc33v"
```
Uma saída será retornada:
```
{
"status": "PROCESSING"
}
```
Esse comando não retornará a saída final depois do processamento. Você deve usar um comando separado, [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/get-schema-creation-status.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/get-schema-creation-status.html), para ver o resultado. Esses dois comandos são assíncronos, portanto, você pode verificar o status da saída mesmo durante a criação do esquema.
------
#### [ CDK ]
**dica**
[Antes de usar o CDK, recomendamos revisar a [documentação oficial](https://docs.aws.amazon.com/cdk/v2/guide/home.html) do CDK junto com AWS AppSync a referência do CDK.](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_appsync-readme.html)
As etapas listadas abaixo mostram apenas um exemplo geral do trecho usado para adicionar um recurso específico. Isso **não** é uma solução funcional para seu código de produção. Também presumimos que você já tenha uma aplicação em funcionamento.
1. O ponto de partida do CDK é um pouco diferente. O ideal é que seu arquivo `schema.graphql` já tenha sido criado. Você só precisa criar um novo arquivo com a extensão `.graphql`. Ele pode ser um arquivo vazio.
1. Em geral, talvez seja necessário adicionar a diretiva de importação ao serviço que você está usando. Por exemplo, estas são as possíveis formas:
```
import * as x from 'x'; # import wildcard as the 'x' keyword from 'x-service'
import {a, b, ...} from 'c'; # import {specific constructs} from 'c-service'
```
Para adicionar uma API GraphQL, seu arquivo de pilha precisa importar o serviço: AWS AppSync
```
import * as appsync from 'aws-cdk-lib/aws-appsync';
```
**nota**
Isso significa que estamos importando todo o serviço com a palavra-chave `appsync`. Para usar isso em seu aplicativo, suas AWS AppSync construções usarão o formato`appsync.construct_name`. Por exemplo, se quiséssemos criar uma API GraphQL, teríamos um `new appsync.GraphqlApi(args_go_here)`. A etapa a seguir mostra isso.
1. A API mais básica do GraphQL incluirá um `name` para a API e o caminho do `schema`.
```
const add_api = new appsync.GraphqlApi(this, 'API_ID', {
name: 'name_of_API_in_console',
schema: appsync.SchemaFile.fromAsset(path.join(__dirname, 'schema_name.graphql')),
});
```
**nota**
Vamos analisar o que esse trecho faz. Dentro do escopo da `api`, estamos criando uma nova API GraphQL chamando o `appsync.GraphqlApi(scope: Construct, id: string, props: GraphqlApiProps)`. O escopo é `this`, que se refere ao objeto atual. O id é*API\$1ID*, que será o nome do recurso da sua API GraphQL CloudFormation quando ela for criada. O `GraphqlApiProps` contém o `name` da sua API GraphQL e o `schema`. `schema`Isso gerará um esquema (`SchemaFile.fromAsset`) pesquisando o caminho absoluto (`__dirname`) do `.graphql` arquivo (*schema\$1name.graphql*). Em um cenário real, seu arquivo de esquema provavelmente estará na aplicação do CDK.
Para usar as alterações feitas na sua API GraphQL, você precisará reimplantar a aplicação.
------
## Adicionar tipos aos esquemas
Agora que você adicionou seu esquema, pode começar a adicionar os tipos de entrada e saída. Os tipos aqui não devem ser usados em código real; eles são apenas exemplos para ajudar você a entender o processo.
Primeiro, vamos criar um tipo de objeto. No código real, não é necessário começar com esses tipos. Você pode criar o tipo que preferir a qualquer momento, desde que siga as regras e a sintaxe do GraphQL.
**nota**
As próximas seções usarão o **editor de esquemas**, portanto, mantenha-o aberto.
------
#### [ Console ]
+ Você pode criar um tipo de objeto usando a palavra-chave `type` junto com o nome do tipo:
```
type Type_Name_Goes_Here {}
```
Dentro do escopo do tipo, você pode adicionar campos que representam as características do objeto:
```
type Type_Name_Goes_Here {
# Add fields here
}
```
Veja um exemplo abaixo:
```
type Obj_Type_1 {
id: ID!
title: String
date: AWSDateTime
}
```
**nota**
Nesta etapa, adicionamos um tipo de objeto genérico com um campo obrigatório `id` armazenado como `ID`, um campo `title` armazenado como `String`, e um campo `date` armazenado como `AWSDateTime`. Para visualizar uma lista de tipos e campos e o que eles fazem, consulte [Schemas](https://docs.aws.amazon.com//appsync/latest/devguide/schema-components.html). Para visualizar uma lista de escalares e o que eles fazem, consulte a [Type reference](https://docs.aws.amazon.com/appsync/latest/devguide/type-reference.html).
------
#### [ CLI ]
**nota**
Recomendamos que seja feita a leitura da versão do console primeiro.
+ Você pode criar um tipo de objeto executando o comando [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/create-type.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/create-type.html).
Você precisará inserir alguns parâmetros para esse comando específico:
1. O `api-id` da sua API.
1. A `definition`, ou o conteúdo do seu tipo. No exemplo do console, tínhamos:
```
type Obj_Type_1 {
id: ID!
title: String
date: AWSDateTime
}
```
1. O `format` da sua entrada. Neste exemplo, usamos o `SDL`.
Veja um exemplo de comando:
```
aws appsync create-type --api-id abcdefghijklmnopqrstuvwxyz --definition "type Obj_Type_1{id: ID! title: String date: AWSDateTime}" --format SDL
```
Uma saída será retornada na CLI. Veja um exemplo abaixo:
```
{
"type": {
"definition": "type Obj_Type_1{id: ID! title: String date: AWSDateTime}",
"name": "Obj_Type_1",
"arn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz/types/Obj_Type_1",
"format": "SDL"
}
}
```
**nota**
Nesta etapa, adicionamos um tipo de objeto genérico com um campo obrigatório `id` armazenado como `ID`, um campo `title` armazenado como `String`, e um campo `date` armazenado como `AWSDateTime`. Para visualizar uma lista de tipos e campos e o que eles fazem, consulte [Schemas](https://docs.aws.amazon.com//appsync/latest/devguide/schema-components.html). Para visualizar uma lista de escalares e o que eles fazem, consulte [Type reference](https://docs.aws.amazon.com/appsync/latest/devguide/type-reference.html).
Além disso, inserir a definição diretamente funciona para tipos menores, mas é inviável para adicionar tipos maiores ou vários tipos. Você pode adicionar tudo em um arquivo `.graphql` e depois [transmiti-lo como a entrada](https://docs.aws.amazon.com/cli/latest/userguide/cli-usage-parameters-file.html).
------
#### [ CDK ]
**dica**
[Antes de usar o CDK, recomendamos revisar a [documentação oficial](https://docs.aws.amazon.com/cdk/v2/guide/home.html) do CDK junto com AWS AppSync a referência do CDK.](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_appsync-readme.html)
As etapas listadas abaixo mostram apenas um exemplo geral do trecho usado para adicionar um recurso específico. Isso **não** é uma solução funcional para seu código de produção. Também presumimos que você já tenha uma aplicação em funcionamento.
Para adicionar um tipo, você precisa adicioná-lo ao seu arquivo `.graphql`. Por exemplo, o exemplo do console foi:
```
type Obj_Type_1 {
id: ID!
title: String
date: AWSDateTime
}
```
Você pode adicionar seus tipos diretamente ao esquema, como qualquer outro arquivo.
**nota**
Para usar as alterações feitas na sua API GraphQL, você precisará reimplantar a aplicação.
------
O [tipo de objeto](https://graphql.org/learn/schema/#object-types-and-fields) tem campos que são [tipos escalares](https://graphql.org/learn/schema/#scalar-types), como cadeias de caracteres e números inteiros. AWS AppSync também permite que você use tipos escalares aprimorados, como `AWSDateTime` adição aos escalares básicos do GraphQL. Qualquer campo que termine com um ponto de exclamação é um campo obrigatório.
O tipo de escalar `ID` é um identificador exclusivo que pode ser `String` ou `Int`. É possível controlar isso nos modelos de mapeamento do solucionador para atribuição automática.
Há semelhanças entre tipos de objetos especiais de `Query` e tipos de objetos “comuns”, como no exemplo acima, pois ambos usam a palavra-chave `type` e são considerados objetos. No entanto, para os tipos de objetos especiais (`Query`, `Mutation` e`Subscription`), o comportamento deles é muito diferente porque eles são expostos como pontos de entrada da sua API. Eles também priorizam a modelagem de operações em vez dos dados. Para obter mais informações, consulte [The query and mutation types](https://graphql.org/learn/schema/#the-query-and-mutation-types).
No tópico dos tipos de objetos especiais, a próxima etapa pode ser adicionar um ou mais deles para realizar operações nos dados modelados. Em um cenário real, todo esquema do GraphQL deve ter pelo menos um tipo de consulta-raiz para solicitar dados. Você pode pensar na consulta como um dos pontos de entrada (ou endpoints) do seu servidor do GraphQL. Vamos adicionar uma consulta como exemplo.
------
#### [ Console ]
+ Para criar uma consulta, basta adicioná-la ao arquivo do esquema como qualquer outro tipo. Uma consulta exigiria um tipo de `Query` e uma entrada na raiz como esta:
```
schema {
query: Name_of_Query
}
type Name_of_Query {
# Add field operation here
}
```
Observe que *Name\$1of\$1Query* em um ambiente de produção simplesmente será chamado `Query` na maioria dos casos. Recomendamos manter esse valor baixo. Dentro do tipo de consulta, você pode adicionar campos. Cada campo executará uma operação na solicitação. Como resultado, a maioria desses campos, se não todos, serão anexados a um solucionador. No entanto, não vamos abordar esse assunto nesta seção. Em relação ao formato da operação do campo, ela pode ser como esta:
```
Name_of_Query(params): Return_Type # version with params
Name_of_Query: Return_Type # version without params
```
Veja um exemplo abaixo:
```
schema {
query: Query
}
type Query {
getObj: [Obj_Type_1]
}
type Obj_Type_1 {
id: ID!
title: String
date: AWSDateTime
}
```
**nota**
Nesta etapa, adicionamos um tipo de `Query` e o definimos na raiz do nosso `schema`. Nosso tipo de `Query` definiu um campo `getObj` que retorna uma lista de objetos `Obj_Type_1`. Esse `Obj_Type_1` é o objeto da etapa anterior. No código de produção, suas operações de campo normalmente trabalharão com dados moldados por objetos como `Obj_Type_1`. Além disso, campos como `getObj` normalmente terão um solucionados para executar a lógica de negócios. Isso será abordado em outra seção.
Como observação adicional, adiciona AWS AppSync automaticamente uma raiz do esquema durante as exportações, então, tecnicamente, você não precisa adicioná-la diretamente ao esquema. Nosso serviço processará esquemas duplicados de maneira automática. Essa é uma prática recomendada.
------
#### [ CLI ]
**nota**
Recomendamos que seja feita a leitura da versão do console primeiro.
1. Crie um `schema` raiz com uma definição da `query` executando o comando [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/create-type.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/create-type.html).
Você precisará inserir alguns parâmetros para esse comando específico:
1. O `api-id` da sua API.
1. A `definition`, ou o conteúdo do seu tipo. No exemplo do console, tínhamos:
```
schema {
query: Query
}
```
1. O `format` da sua entrada. Neste exemplo, usamos o `SDL`.
Veja um exemplo de comando:
```
aws appsync create-type --api-id abcdefghijklmnopqrstuvwxyz --definition "schema {query: Query}" --format SDL
```
Uma saída será retornada na CLI. Veja um exemplo abaixo:
```
{
"type": {
"definition": "schema {query: Query}",
"name": "schema",
"arn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz/types/schema",
"format": "SDL"
}
}
```
**nota**
Se você tiver cometido um erro no comando `create-type`, poderá atualizar a raiz do esquema (ou qualquer tipo no esquema) executando o comando [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/update-type.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/update-type.html). Neste exemplo, alteraremos temporariamente a raiz do esquema para conter uma definição de `subscription`.
Você precisará inserir alguns parâmetros para esse comando específico:
O `api-id` da sua API.
O `type-name` do seu tipo. No exemplo do console, tínhamos `schema`.
A `definition`, ou o conteúdo do seu tipo. No exemplo do console, tínhamos:
```
schema {
query: Query
}
```
O esquema após a adição de um `subscription` será semelhante a este:
```
schema {
query: Query
subscription: Subscription
}
```
O `format` da sua entrada. Neste exemplo, usamos o `SDL`.
Veja um exemplo de comando:
```
aws appsync update-type --api-id abcdefghijklmnopqrstuvwxyz --type-name schema --definition "schema {query: Query subscription: Subscription}" --format SDL
```
Uma saída será retornada na CLI. Veja um exemplo abaixo:
```
{
"type": {
"definition": "schema {query: Query subscription: Subscription}",
"arn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz/types/schema",
"format": "SDL"
}
}
```
Adicionar arquivos pré-formatados ainda funcionará neste exemplo.
1. Crie uma `Query` executando o comando [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/create-type.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/create-type.html).
Você precisará inserir alguns parâmetros para esse comando específico:
1. O `api-id` da sua API.
1. A `definition`, ou o conteúdo do seu tipo. No exemplo do console, tínhamos:
```
type Query {
getObj: [Obj_Type_1]
}
```
1. O `format` da sua entrada. Neste exemplo, usamos o `SDL`.
Veja um exemplo de comando:
```
aws appsync create-type --api-id abcdefghijklmnopqrstuvwxyz --definition "type Query {getObj: [Obj_Type_1]}" --format SDL
```
Uma saída será retornada na CLI. Veja um exemplo abaixo:
```
{
"type": {
"definition": "Query {getObj: [Obj_Type_1]}",
"name": "Query",
"arn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz/types/Query",
"format": "SDL"
}
}
```
**nota**
Nesta etapa, adicionamos um tipo de `Query` e o definimos na raiz do seu `schema`. Nosso tipo de `Query` definiu um campo `getObj` que retornou uma lista de objetos `Obj_Type_1`.
Na `query: Query` do código-raiz do `schema`, a parte `query:` indica que uma consulta foi definida em seu esquema, enquanto a parte `Query` representa o nome real do objeto especial.
------
#### [ CDK ]
**dica**
[Antes de usar o CDK, recomendamos revisar a [documentação oficial](https://docs.aws.amazon.com/cdk/v2/guide/home.html) do CDK junto com AWS AppSync a referência do CDK.](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_appsync-readme.html)
As etapas listadas abaixo mostram apenas um exemplo geral do trecho usado para adicionar um recurso específico. Isso **não** é uma solução funcional para seu código de produção. Também presumimos que você já tenha uma aplicação em funcionamento.
Você precisará adicionar sua consulta e a raiz do esquema ao arquivo do `.graphql`. Nosso exemplo se parece com o exemplo abaixo, mas considere substituí-lo pelo código do seu esquema real:
```
schema {
query: Query
}
type Query {
getObj: [Obj_Type_1]
}
type Obj_Type_1 {
id: ID!
title: String
date: AWSDateTime
}
```
Você pode adicionar seus tipos diretamente ao esquema, como qualquer outro arquivo.
**nota**
A atualização da raiz do esquema é opcional. Nós a adicionamos a esse exemplo como uma prática recomendada.
Para usar as alterações feitas na sua API GraphQL, você precisará reimplantar a aplicação.
------
Mostramos um exemplo de criação de objetos comuns e objetos especiais (consultas). Também abordamos como eles se interconectam para descrever dados e operações. Pode haver esquemas apenas com a descrição dos dados e uma ou mais consultas. No entanto, gostaríamos de adicionar outra operação para incluir dados na fonte de dados. Adicionaremos outro tipo de objeto especial chamado `Mutation` que modifica os dados.
------
#### [ Console ]
+ Uma mutação será chamada de `Mutation`. Como a `Query`, as operações de campo em `Mutation` descrevem uma operação e serão anexadas a um solucionador. Além disso, precisamos defini-lo na raiz do `schema` porque é um tipo de objeto especial. Veja um exemplo de mutação abaixo:
```
schema {
mutation: Name_of_Mutation
}
type Name_of_Mutation {
# Add field operation here
}
```
Uma mutação típica será listada na raiz como uma consulta. A mutação é definida usando a `type` palavra-chave junto com o nome. *Name\$1of\$1Mutation*normalmente serão chamados`Mutation`, por isso recomendamos que continue assim. Cada campo também executará uma operação. Em relação ao formato da operação do campo, ela pode ser como esta:
```
Name_of_Mutation(params): Return_Type # version with params
Name_of_Mutation: Return_Type # version without params
```
Veja um exemplo abaixo:
```
schema {
query: Query
mutation: Mutation
}
type Obj_Type_1 {
id: ID!
title: String
date: AWSDateTime
}
type Query {
getObj: [Obj_Type_1]
}
type Mutation {
addObj(id: ID!, title: String, date: AWSDateTime): Obj_Type_1
}
```
**nota**
Nesta etapa, adicionamos um tipo de `Mutation` com um campo `addObj`. Vamos resumir o que esse campo faz:
```
addObj(id: ID!, title: String, date: AWSDateTime): Obj_Type_1
```
O `addObj` usa o objeto `Obj_Type_1` para realizar uma operação. Isso é evidente ao observar os campos, mas a sintaxe prova isso no tipo de retorno `: Obj_Type_1`. Em `addObj`, os campos `id`, `title` e `date` do objeto `Obj_Type_1` como parâmetros. Como podemos notar, ela se parece muito com uma declaração de método. No entanto, ainda não descrevemos o comportamento do nosso método. Conforme mencionado anteriormente, o esquema só existe para definir quais serão os dados e as operações e não a forma como operam. A implementação da lógica de negócios real será abordada quando criarmos nossos primeiros solucionadores.
Depois de concluir o esquema, há uma opção para exportá-lo como um arquivo `schema.graphql`. No **Editor de esquemas**, você pode escolher **Exportar esquema** para fazer download do arquivo em um formato compatível.
Como observação adicional, adiciona AWS AppSync automaticamente uma raiz do esquema durante as exportações, então, tecnicamente, você não precisa adicioná-la diretamente ao esquema. Nosso serviço processará esquemas duplicados de maneira automática. Essa é uma prática recomendada.
------
#### [ CLI ]
**nota**
Recomendamos que seja feita a leitura da versão do console primeiro.
1. Atualize seu esquema-raiz executando o comando [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/update-type.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/update-type.html).
Você precisará inserir alguns parâmetros para esse comando específico:
1. O `api-id` da sua API.
1. O `type-name` do seu tipo. No exemplo do console, tínhamos `schema`.
1. A `definition`, ou o conteúdo do seu tipo. No exemplo do console, tínhamos:
```
schema {
query: Query
mutation: Mutation
}
```
1. O `format` da sua entrada. Neste exemplo, usamos o `SDL`.
Veja um exemplo de comando:
```
aws appsync update-type --api-id abcdefghijklmnopqrstuvwxyz --type-name schema --definition "schema {query: Query mutation: Mutation}" --format SDL
```
Uma saída será retornada na CLI. Veja um exemplo abaixo:
```
{
"type": {
"definition": "schema {query: Query mutation: Mutation}",
"arn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz/types/schema",
"format": "SDL"
}
}
```
1. Crie uma `Mutation` executando o comando [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/create-type.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/create-type.html).
Você precisará inserir alguns parâmetros para esse comando específico:
1. O `api-id` da sua API.
1. A `definition`, ou o conteúdo do seu tipo. No exemplo do console, tínhamos
```
type Mutation {
addObj(id: ID!, title: String, date: AWSDateTime): Obj_Type_1
}
```
1. O `format` da sua entrada. Neste exemplo, usamos o `SDL`.
Veja um exemplo de comando:
```
aws appsync create-type --api-id abcdefghijklmnopqrstuvwxyz --definition "type Mutation {addObj(id: ID! title: String date: AWSDateTime): Obj_Type_1}" --format SDL
```
Uma saída será retornada na CLI. Veja um exemplo abaixo:
```
{
"type": {
"definition": "type Mutation {addObj(id: ID! title: String date: AWSDateTime): Obj_Type_1}",
"name": "Mutation",
"arn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz/types/Mutation",
"format": "SDL"
}
}
```
------
#### [ CDK ]
**dica**
[Antes de usar o CDK, recomendamos revisar a [documentação oficial](https://docs.aws.amazon.com/cdk/v2/guide/home.html) do CDK junto com AWS AppSync a referência do CDK.](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_appsync-readme.html)
As etapas listadas abaixo mostram apenas um exemplo geral do trecho usado para adicionar um recurso específico. Isso **não** é uma solução funcional para seu código de produção. Também presumimos que você já tenha uma aplicação em funcionamento.
Você precisará adicionar sua consulta e a raiz do esquema ao arquivo do `.graphql`. Nosso exemplo se parece com o exemplo abaixo, mas considere substituí-lo pelo código do seu esquema real:
```
schema {
query: Query
mutation: Mutation
}
type Obj_Type_1 {
id: ID!
title: String
date: AWSDateTime
}
type Query {
getObj: [Obj_Type_1]
}
type Mutation {
addObj(id: ID!, title: String, date: AWSDateTime): Obj_Type_1
}
```
**nota**
A atualização da raiz do esquema é opcional. Nós a adicionamos a esse exemplo como uma prática recomendada.
Para usar as alterações feitas na sua API GraphQL, você precisará reimplantar a aplicação.
------
## Considerações opcionais: usar enumerados como status
Neste ponto, você já sabe como criar um esquema básico. No entanto, há muitos elementos que você pode adicionar para aumentar a funcionalidade do esquema. Uma coisa comum encontrada nas aplicações é o uso de enumerados como status. Você pode usar um enumerado para aplicar um valor específico de um conjunto de valores a ser escolhido quando chamado. Isso é bom para elementos que não mudarão drasticamente por longos períodos. Hipoteticamente falando, poderíamos adicionar um enumerado que retorna o código de status ou string na resposta.
Como exemplo, vamos supor que estamos criando uma aplicação de mídia social que armazena os dados de postagem de um usuário no back-end. Nosso esquema contém um tipo de `Post` que representa os dados de uma postagem individual:
```
type Post {
id: ID!
title: String
date: AWSDateTime
poststatus: PostStatus
}
```
Nossa `Post` conterá um único `id`, um `title`, uma `date` de postagem e um enumerado chamado de `PostStatus`, que representa o estado da postagem conforme ela é processada pela aplicação. Para nossas operações, teremos uma consulta que retornará todos os dados da postagem:
```
type Query {
getPosts: [Post]
}
```
Também teremos uma mutação que adiciona postagens à fonte de dados:
```
type Mutation {
addPost(id: ID!, title: String, date: AWSDateTime, poststatus: PostStatus): Post
}
```
Analisando nosso esquema, o enumerado `PostStatus` pode ter vários status. É possível termos os três estados básicos chamados de `success` (postagem processada com sucesso), `pending` (postagem sendo processada) e `error` (postagem que não foi processada). Para adicionar o enumerado, podemos fazer o seguinte:
```
enum PostStatus {
success
pending
error
}
```
O esquema completo pode ser semelhante a este:
```
schema {
query: Query
mutation: Mutation
}
type Post {
id: ID!
title: String
date: AWSDateTime
poststatus: PostStatus
}
type Mutation {
addPost(id: ID!, title: String, date: AWSDateTime, poststatus: PostStatus): Post
}
type Query {
getPosts: [Post]
}
enum PostStatus {
success
pending
error
}
```
Se um usuário adicionar uma `Post` à aplicação, a operação `addPost` será chamada para processar esses dados. À medida que o solucionador anexado à `addPost` processa os dados, ele vai atualizar o `poststatus` continuamente com o status da operação. Quando consultado, a `Post` vai mostrar o status final dos dados. Aqui só descrevemos como queremos que os dados funcionem no esquema. Fazemos muitas suposições sobre a implementação de nossos solucionadores, que implementarão a lógica comercial real para lidar com os dados e atender à solicitação.
## Considerações opcionais: assinaturas
As assinaturas em AWS AppSync são invocadas como resposta a uma mutação. Isso pode ser configurado com um tipo `Subscription` e diretiva `@aws_subscribe()` no esquema para indicar quais mutações invocam uma ou mais assinaturas. Consulte [Real-time data](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-real-time-data.html) para obter mais informações sobre como configurar assinaturas.
## Considerações opcionais: relações e paginação
Suponha que você tenha um milhão de `Posts` armazenadas em uma tabela do DynamoDB e queira retornar alguns desses dados. No entanto, o exemplo de consulta fornecido acima retorna todas as postagens. Não é fácil buscar tudo isso sempre que fizer uma solicitação. O melhor é [paginar](https://graphql.org/learn/pagination/) todas elas. Faça as seguintes alterações ao esquema:
+ No campo `getPosts`, adicione dois argumentos de entrada: `nextToken` (iterador) e `limit` (limite de iteração).
+ Adicione um novo tipo de `PostIterator` contendo `Posts` (isso recupera a lista de objetos `Post`) e campos `nextToken` (iterador).
+ Altere `getPosts` para que retorne `PostIterator`, não uma lista de objetos `Post`.
```
schema {
query: Query
mutation: Mutation
}
type Post {
id: ID!
title: String
date: AWSDateTime
poststatus: PostStatus
}
type Mutation {
addPost(id: ID!, title: String, date: AWSDateTime, poststatus: PostStatus): Post
}
type Query {
getPosts(limit: Int, nextToken: String): PostIterator
}
enum PostStatus {
success
pending
error
}
type PostIterator {
posts: [Post]
nextToken: String
}
```
O tipo `PostIterator` permite que você retorne parte da lista de objetos de `Post` e um `nextToken` para obter a próxima parte. Em `PostIterator`, há uma lista de itens da `Post` (`[Post]`) que é retornada com um token de paginação (`nextToken`). Em AWS AppSync, isso seria conectado ao Amazon DynamoDB por meio de um resolvedor e gerado automaticamente como um token criptografado. Isso converte o valor do argumento `limit` no parâmetro `maxResults` e o argumento `nextToken` no parâmetro `exclusiveStartKey`. Para ver exemplos e exemplos de modelos integrados no AWS AppSync console, consulte [Referência do Resolver (JavaScript)](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html).
# Anexando uma fonte de dados em AWS AppSync
As fontes de dados são recursos em sua AWS conta com os quais o GraphQL APIs pode interagir. AWS AppSync oferece suporte a várias fontes de dados AWS Lambda, como Amazon DynamoDB, bancos de dados relacionais (Amazon Aurora Serverless), Amazon Service e endpoints HTTP. OpenSearch Uma AWS AppSync API pode ser configurada para interagir com várias fontes de dados, permitindo que você agregue dados em um único local. AWS AppSync pode usar AWS recursos existentes da sua conta ou provisionar tabelas do DynamoDB em seu nome a partir de uma definição de esquema.
A seção a seguir mostrará como anexar uma fonte de dados à sua API GraphQL.
## Tipos de fontes de dados
Agora que você criou um esquema no AWS AppSync console, você pode anexar uma fonte de dados a ele. Quando você começa a criar uma API, há a opção de provisionar uma tabela do Amazon DynamoDB durante a criação do esquema predefinido. No entanto, não abordaremos essa opção nesta seção. Você pode ver um exemplo disso na seção [Iniciar um esquema](https://docs.aws.amazon.com//appsync/latest/devguide/schema-launch-start.html).
Em vez disso, analisaremos todos os AWS AppSync suportes de fontes de dados. Há muitos fatores que influenciam a escolha da solução certa para seu aplicativo. As seções abaixo fornecerão contexto adicional para cada fonte de dados. Para obter informações gerais sobre fontes de dados, consulte [Data sources](https://docs.aws.amazon.com/appsync/latest/devguide/data-source-components.html).
### Amazon DynamoDB
O Amazon DynamoDB é uma das principais soluções AWS de armazenamento para aplicativos escaláveis. O componente principal do DynamoDB é a **tabela**, que é simplesmente um conjunto de dados. Normalmente, você cria tabelas com base em entidades como `Book` ou `Author`. As informações de entrada da tabela são armazenadas como **itens**, que são grupos de campos exclusivos para cada entrada. Um item completo representa um row/record no banco de dados. Por exemplo, um item para uma entrada da `Book` pode incluir `title` e `author` com seus valores. Os campos individuais, como `title` e, `author` são chamados de **atributos**, que são semelhantes aos valores das colunas em bancos de dados relacionais.
Como você pode imaginar, as tabelas serão usadas para armazenar dados do seu aplicativo. AWS AppSync permite que você conecte suas tabelas do DynamoDB à sua API do GraphQL para manipular dados. Veja este [caso de uso](https://aws.amazon.com/blogs/mobile/new-real-time-multi-group-app-with-aws-amplify-graphql-build-a-twitter-community-clone/) no blog *Front-end web and mobile*. Esta aplicação permite que os usuários se inscrevam em um aplicativo de mídia social. Os usuários podem participar de grupos e fazer upload de postagens que são transmitidas para outros usuários inscritos no grupo. A aplicação armazena informações de usuários, publicações e grupos de usuários no DynamoDB. A API GraphQL (gerenciada por AWS AppSync) faz interface com a tabela do DynamoDB. Quando um usuário faz uma alteração no sistema que será refletida no front-end, a API GraphQL recupera essas alterações e as transmite para outros usuários em tempo real.
### AWS Lambda
O Lambda é um serviço orientado por eventos que cria automaticamente os recursos necessários para executar códigos como resposta a um evento. O Lambda usa **funções**, que são declarações de grupo contendo o código, as dependências e as configurações para executar um recurso. As funções são executadas automaticamente quando detectam um **gatilho**, um grupo de atividades que invocam sua função. Um gatilho pode ser algo como um aplicativo fazendo uma chamada de API, um AWS serviço em sua conta gerando um recurso etc. Quando acionadas, as funções processarão **eventos**, que são documentos JSON com os dados a serem modificados.
O Lambda é bom para executar códigos sem precisar provisionar os recursos para executá-lo. Veja este [caso de uso](https://aws.amazon.com/blogs/mobile/building-a-graphql-api-with-java-and-aws-lambda/) no blog *Front-end web and mobile*. Esse caso de uso é um pouco semelhante ao apresentado na seção do DynamoDB. Nessa aplicação, a API GraphQL é responsável por definir as operações para coisas como adicionar postagens (mutações) e buscar esses dados (consultas). Para implementar a funcionalidade de suas operações (por exemplo, `getPost ( id: String ! ) : Post` e `getPostsByAuthor ( author: String ! ) : [ Post ]`), eles usam funções do Lambda para processar solicitações de entrada. Na *Opção 2: AWS AppSync com o resolvedor Lambda*, eles usam o AWS AppSync serviço para manter seu esquema e vincular uma fonte de dados Lambda a uma das operações. Quando a operação é chamada, o Lambda interage com o Amazon RDS Proxy para executar a lógica de negócios no banco de dados.
### Amazon RDS
O Amazon RDS permite que você crie e configure rapidamente bancos de dados relacionais. No Amazon RDS, você criará uma **instância de banco de dados** genérica que servirá como ambiente de banco de dados isolado na nuvem. Nesta instância, você usará um **mecanismo de banco de dados**, que é o software RDBMS real (PostgreSQL, MySQL etc.). O serviço elimina grande parte do trabalho de back-end, fornecendo escalabilidade usando AWS infraestrutura, serviços de segurança, como patches e criptografia, e reduzindo os custos administrativos das implantações.
Veja o mesmo [caso de uso](https://aws.amazon.com/blogs/mobile/building-a-graphql-api-with-java-and-aws-lambda/) da seção do Lambda. Na *Opção 3: AWS AppSync com o resolvedor do Amazon RDS*, outra opção apresentada é vincular a API do GraphQL diretamente ao AWS AppSync Amazon RDS. Com uma [API de dados](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/data-api.html), eles associam o banco de dados à API GraphQL. Um resolvedor é anexado a um campo (geralmente uma consulta, mutação ou assinatura) e implementa as instruções SQL necessárias para acessar o banco de dados. Quando uma solicitação de chamada do campo é feita pelo cliente, o resolvedor executa as instruções e retorna a resposta.
### Amazon EventBridge
Em EventBridge, você criará **barramentos de eventos**, que são pipelines que recebem eventos de serviços ou aplicativos anexados (a **origem do evento**) e os processam com base em um conjunto de regras. Um **evento** é uma mudança de estado em um ambiente de execução, enquanto uma **regra** é um conjunto de filtros para eventos. Uma regra segue um **padrão de evento** ou metadados da mudança de estado de um evento (id, região, número da conta, ARN(s) etc.). Quando um evento corresponde ao padrão do evento, EventBridge enviará o evento pelo pipeline até o serviço de destino (**destino**) e acionará a ação especificada na regra.
EventBridge é bom para rotear operações de mudança de estado para algum outro serviço. Veja este [caso de uso](https://aws.amazon.com/blogs/mobile/appsync-eventbridge/) no blog *Front-end web and mobile*. O exemplo mostra uma solução de comércio eletrônico que tem várias equipes mantendo serviços diferentes. Um desses serviços fornece atualizações de pedidos ao cliente em cada etapa da entrega (pedido feito, em andamento, enviado, entregue etc.) no front-end. No entanto, a equipe de front-end que gerencia esse serviço não tem acesso direto aos dados do sistema de pedidos, pois eles são mantidos por uma equipe de back-end separada. O sistema de pedidos da equipe de back-end também é descrito como uma caixa preta, por isso, é difícil coletar informações sobre a forma como eles estruturam os dados. No entanto, a equipe de back-end configurou um sistema que publicou dados de pedidos por meio de um barramento de eventos gerenciado por EventBridge. Para acessar os dados provenientes do barramento de eventos e encaminhá-los para o front-end, a equipe de front-end criou um novo alvo apontando para a API GraphQL instalada. AWS AppSync Eles também criaram uma regra para enviar apenas dados relevantes para a atualização do pedido. Quando uma atualização é feita, os dados do barramento de eventos são enviados para a API GraphQL. O esquema na API processa os dados e os transfere para o front-end.
### Nenhuma fonte de dados
Se você não planeja usar uma fonte de dados, pode defini-la como `none`. Uma fonte de dados `none`, embora ainda seja explicitamente categorizada como fonte de dados, não é um meio de armazenamento. Normalmente, um resolvedor invoca uma ou mais fontes de dados em algum momento para processar a solicitação. No entanto, há situações em que talvez você não precise manipular uma fonte de dados. Definir a fonte de dados como `none` vai executar a solicitação, ignorar a etapa de invocação de dados e executar a resposta.
Veja o mesmo [caso de uso](https://aws.amazon.com/blogs/mobile/appsync-eventbridge/) da EventBridge seção. No esquema, a mutação processa a atualização de status e a envia aos assinantes. Semelhante ao funcionamento dos resolvedores, geralmente há pelo menos uma invocação de fonte de dados. No entanto, os dados nesse cenário já foram enviados automaticamente pelo barramento de eventos. Isso significa que não é necessário passar pela mutação para realizar uma invocação da fonte de dados; o status do pedido pode ser tratado localmente. A mutação é definida como `none`, o que funciona como um valor de passagem sem invocação da fonte de dados. O esquema é preenchido com os dados, que são enviados aos assinantes.
### OpenSearch
O Amazon OpenSearch Service é um conjunto de ferramentas para implementar pesquisa de texto completo, visualização de dados e registro. Você pode usar esse serviço para consultar os dados estruturados que enviou.
Nesse serviço, você criará instâncias de OpenSearch. Eles são chamados de **nós**. Em um nó, você adicionará pelo menos um **índice**. Conceitualmente, os índices são um pouco como tabelas em bancos de dados relacionais. (No entanto, OpenSearch não é compatível com ACID, então não deve ser usado dessa forma). Você preencherá seu índice com os dados que você envia para o OpenSearch serviço. Quando seus dados forem carregados, eles serão indexados em um ou mais fragmentos existentes no índice. Um **fragmento** é como uma partição do seu índice que contém alguns dos seus dados e pode ser consultado separadamente de outros fragmentos. Depois de carregados, seus dados serão estruturados como arquivos JSON chamados **documentos**. Em seguida, você pode consultar o nó em busca de dados no documento.
### Endpoints de HTTP
Você pode usar endpoints HTTP como fontes de dados. AWS AppSync pode enviar solicitações aos endpoints com as informações relevantes, como parâmetros e carga útil. A resposta HTTP será exposta ao resolvedor, que retornará a resposta final após concluir suas operações.
## Adicionar uma fonte de dados
Se você criou uma fonte de dados, pode vinculá-la ao AWS AppSync serviço e, mais especificamente, à API.
------
#### [ Console ]
1. Faça login no Console de gerenciamento da AWS e abra o [AppSyncconsole](https://console.aws.amazon.com/appsync/).
1. Escolha sua API no **Painel**.
1. Na **barra lateral**, escolha **Fontes de dados**.
1. Escolha **Criar fonte de dados**.
1. Dê um nome à sua fonte de dados. Você também pode incluir uma descrição, mas isso é opcional.
1. Selecione o **tipo de fonte de dados**.
1. Para o DynamoDB, você precisará escolher sua Região e, em seguida, a tabela na Região. Você pode definir regras de interação com sua tabela criando um novo perfil genérico ou importando um perfil existente. Você pode habilitar o [versionamento](https://docs.aws.amazon.com/appsync/latest/devguide/conflict-detection-and-sync.html), que pode criar automaticamente versões de dados para cada solicitação quando vários clientes estão tentando atualizar os dados ao mesmo tempo. O versionamento é usado para manter diversas variantes de dados para fins de detecção e resolução de conflitos. Você também pode ativar a geração automática de esquemas, que usa sua fonte de dados e gera parte do CRUD, `List` e `Query` das operações necessárias para acessá-la em seu esquema.
Para isso OpenSearch, você terá que escolher sua região e, em seguida, o domínio (cluster) na região. Você pode definir regras de interação com seu domínio criando uma nova função genérica ou importando uma função existente.
Para o Lambda, você terá que escolher sua Região e, em seguida, o ARN da função do Lambda na Região. Você pode definir regras de interação com sua função do Lambda criando um novo perfil da tabela genérica ou importando um perfil existente.
Para HTTP, você precisará inserir seu endpoint HTTP.
Pois EventBridge, você terá que escolher sua região e, em seguida, o ônibus do evento na região. Você pode definir regras de interação com seu barramento de eventos, criando uma nova função genérica ou importando uma função existente.
Para o RDS, você precisará escolher sua Região, depois o armazenamento secreto (nome de usuário e senha), nome do banco de dados e esquema.
Para nenhum deles, você adicionará uma fonte de dados sem uma fonte de dados real. Isso serve para lidar com resolvedores localmente, e não por meio de uma fonte de dados real.
**nota**
Se você estiver importando funções existentes, elas precisarão de uma política de confiança. Para obter mais informações sobre a política de confiança, consulte [política de confiança do IAM](#iam-trust-policy.title).
1. Escolha **Criar**.
**nota**
Como alternativa, se você estiver criando uma fonte de dados do DynamoDB, acesse a página **Esquema** no console, escolha **Criar recursos** na parte superior da página e preencha um modelo predefinido para converter em uma tabela. Nessa opção, você vai preencher ou importar o tipo de base, configurar os dados básicos da tabela, incluindo a chave de partição, além de analisar as alterações do esquema.
------
#### [ CLI ]
+ Crie um objeto da fonte de dados executando o comando [https://docs.aws.amazon.com/cli/latest/reference/appsync/create-data-source.html](https://docs.aws.amazon.com/cli/latest/reference/appsync/create-data-source.html).
Você precisará inserir alguns parâmetros para esse comando específico:
1. O `api-id` da sua API.
1. O `name` da tabela.
1. O `type` da fonte de dados. Dependendo do tipo de fonte de dados escolhido, talvez seja necessário inserir um `-config` e uma tag `service-role-arn`.
Veja um exemplo de comando:
```
aws appsync create-data-source --api-id abcdefghijklmnopqrstuvwxyz --name data_source_name --type data_source_type --service-role-arn arn:aws:iam::107289374856:role/role_name --[data_source_type]-config {params}
```
------
#### [ CDK ]
**dica**
[Antes de usar o CDK, recomendamos revisar a [documentação oficial](https://docs.aws.amazon.com/cdk/v2/guide/home.html) do CDK junto com AWS AppSync a referência do CDK.](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_appsync-readme.html)
As etapas listadas abaixo mostram apenas um exemplo geral do trecho usado para adicionar um recurso específico. Isso **não** é uma solução funcional para seu código de produção. Também presumimos que você já tenha uma aplicação em funcionamento.
Para adicionar sua fonte de dados específica, você precisará incluir a estrutura ao seu arquivo de pilha. Uma lista dos tipos de fontes de dados pode ser encontrada aqui:
+ [ DynamoDbDataSource ](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_appsync.DynamoDbDataSource.html)
+ [ EventBridgeDataSource ](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_appsync.EventBridgeDataSource.html)
+ [ HttpDataSource ](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_appsync.HttpDataSource.html)
+ [ LambdaDataSource ](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_appsync.LambdaDataSource.html)
+ [ NoneDataSource ](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_appsync.NoneDataSource.html)
+ [ OpenSearchDataSource ](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_appsync.OpenSearchDataSource.html)
+ [ RdsDataSource ](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_appsync.RdsDataSource.html)
1. Em geral, talvez seja necessário adicionar a diretiva de importação ao serviço que você está usando. Por exemplo, estas são as possíveis formas:
```
import * as x from 'x'; # import wildcard as the 'x' keyword from 'x-service'
import {a, b, ...} from 'c'; # import {specific constructs} from 'c-service'
```
Por exemplo, veja como você pode importar os serviços AWS AppSync e do DynamoDB:
```
import * as appsync from 'aws-cdk-lib/aws-appsync';
import * as dynamodb from 'aws-cdk-lib/aws-dynamodb';
```
1. Alguns serviços, como o RDS, exigem alguma configuração adicional no arquivo de pilha antes de criar a fonte de dados (por exemplo, criação de VPC, funções e credenciais de acesso). Consulte os exemplos nas páginas relevantes do CDK para obter mais informações.
1. Para a maioria das fontes de dados, especialmente AWS serviços, você criará uma nova instância da fonte de dados em seu arquivo de pilha. Normalmente, isso será exibido da seguinte forma:
```
const add_data_source_func = new service_scope.resource_name(scope: Construct, id: string, props: data_source_props);
```
Por exemplo, aqui está um exemplo de tabela do Amazon DynamoDB:
```
const add_ddb_table = new dynamodb.Table(this, 'Table_ID', {
partitionKey: {
name: 'id',
type: dynamodb.AttributeType.STRING,
},
sortKey: {
name: 'id',
type: dynamodb.AttributeType.STRING,
},
tableClass: dynamodb.TableClass.STANDARD,
});
```
**nota**
A maioria das fontes de dados terá pelo menos um suporte obrigatório (será indicado **sem** um símbolo `?`). Consulte a documentação do CDK para ver quais propriedades são necessárias.
1. Em seguida, você precisa vincular a fonte de dados à API GraphQL. O método recomendado é adicioná-la ao criar uma função para o resolvedor de pipeline. Por exemplo, o trecho abaixo é uma função que verifica todos os elementos em uma tabela do DynamoDB:
```
const add_func = new appsync.AppsyncFunction(this, 'func_ID', {
name: 'func_name_in_console',
add_api,
dataSource: add_api.addDynamoDbDataSource('data_source_name_in_console', add_ddb_table),
code: appsync.Code.fromInline(`
export function request(ctx) {
return { operation: 'Scan' };
}
export function response(ctx) {
return ctx.result.items;
}
`),
runtime: appsync.FunctionRuntime.JS_1_0_0,
});
```
Nas propriedades de `dataSource`, você pode chamar a API GraphQL (`add_api`) e usar um de seus métodos integrados (`addDynamoDbDataSource`) para fazer a associação entre a tabela e a API GraphQL. Os argumentos são o nome desse link que existirá no AWS AppSync console (`data_source_name_in_console`neste exemplo) e o método da tabela (`add_ddb_table`). Mais informações sobre esse tópico serão reveladas na próxima seção, quando você começar a criar resolvedores.
Existem métodos alternativos para vincular uma fonte de dados. Tecnicamente, você pode adicionar itens da `api` à lista de propriedades na função de tabela. Por exemplo, aqui está o trecho da etapa 3, mas com propriedades da `api` contendo uma API GraphQL:
```
const add_api = new appsync.GraphqlApi(this, 'API_ID', {
...
});
const add_ddb_table = new dynamodb.Table(this, 'Table_ID', {
...
api: add_api
});
```
Como alternativa, você pode chamar a estrutura do `GraphqlApi` separadamente:
```
const add_api = new appsync.GraphqlApi(this, 'API_ID', {
...
});
const add_ddb_table = new dynamodb.Table(this, 'Table_ID', {
...
});
const link_data_source = add_api.addDynamoDbDataSource('data_source_name_in_console', add_ddb_table);
```
Recomendamos criar a associação somente nas propriedades da função. Caso contrário, você precisará vincular sua função de resolução à fonte de dados manualmente no AWS AppSync console (se quiser continuar usando o valor do console`data_source_name_in_console`) ou criar uma associação separada na função com outro nome, como`data_source_name_in_console_2`. Isso se deve às limitações na forma como as propriedades processam as informações.
**nota**
Você precisará reimplantar a aplicação para conferir as alterações.
------
### Política de confiança do IAM
Se você estiver usando uma função do IAM existente para sua fonte de dados, precisará conceder a essa função as permissões apropriadas para realizar operações em seu AWS recurso, como `PutItem` em uma tabela do Amazon DynamoDB. Você também precisa modificar a política de confiança dessa função para permitir seu uso AWS AppSync para acesso a recursos, conforme mostrado no exemplo de política a seguir:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "appsync.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
------
Você também pode adicionar condições à sua política de confiança para limitar o acesso à fonte de dados, conforme desejado. Atualmente, as chaves `SourceArn` e `SourceAccount` podem ser usadas nessas condições. Por exemplo, a política a seguir limita o acesso à sua fonte de dados na conta `123456789012`:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "appsync.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "123456789012"
}
}
}
]
}
```
------
Como alternativa, é possível restringir o acesso de uma API específica a uma fonte de dados, por exemplo, `abcdefghijklmnopq`, usando a seguinte política:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "appsync.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"ArnEquals": {
"aws:SourceArn": "arn:aws:appsync:us-west-2:123456789012:apis/abcdefghijklmnopq"
}
}
}
]
}
```
------
Você pode limitar o acesso a todos AWS AppSync APIs de uma região específica, por exemplo`us-east-1`, usando a seguinte política:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "appsync.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"ArnEquals": {
"aws:SourceArn": "arn:aws:appsync:us-east-1:123456789012:apis/*"
}
}
}
]
}
```
------
Na próxima seção ([Configurar os resolvedores](https://docs.aws.amazon.com//appsync/latest/devguide/resolver-config-overview.html)), vamos adicionar nossa lógica de negócios do resolvedor e anexá-la aos campos em nosso esquema para processar os dados em nossa fonte de dados.
Para obter mais informações, consulte [Modificando um perfil](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_manage_modify.html) no *Guia do usuário do IAM*.
Para obter mais informações sobre o acesso entre contas de AWS Lambda resolvedores para AWS AppSync, consulte [Criação de resolvedores entre contas AWS Lambda](https://aws.amazon.com/blogs/mobile/appsync-lambda-cross-account/) para. AWS AppSync
# Configuração de resolvedores no AWS AppSync
Nas seções anteriores, você aprendeu a criar o esquema e a fonte de dados do GraphQL e, em seguida, vinculá-los no serviço AWS AppSync. No esquema, você pode ter estabelecido um ou mais campos (operações) na consulta e na mutação. Embora o esquema descrevesse os tipos de dado que as operações solicitariam da fonte de dados, ele nunca implementou o modo como essas operações se comportariam em relação aos dados.
O comportamento de uma operação é sempre implementado no resolvedor, que será vinculado ao campo que executa a operação. Para obter mais informações sobre como os resolvedores funcionam em geral, consulte a página [Resolvedores](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-components.html).
Em AWS AppSync, o resolvedor é vinculado a um runtime, que é o ambiente no qual o resolvedor é executado. Os runtimes determinam a linguagem na qual o resolvedor será gravado. Atualmente, há dois runtimes compatíveis: APPSYNC\$1JS (JavaScript) e Apache Velocity Template Language (VTL).
Ao implementar resolvedores, eles seguem uma estrutura geral:
+ **Etapa Anterior**: quando uma solicitação é feita pelo cliente, os resolvedores dos campos do esquema que estão sendo usados (normalmente consultas, mutações e assinaturas) recebem os dados da solicitação. O resolvedor começará a processar os dados da solicitação com um manipulador de etapas anteriores, o que permite que algumas operações de pré-processamento sejam executadas antes que os dados passem pelo resolvedor.
+ **Função(ões)**: Após a execução da etapa anterior, a solicitação é passada para a lista de funções. A primeira função na lista será executada na fonte de dados. Uma função é um subconjunto do código do resolvedor contendo seu próprio manipulador de solicitações e respostas. Um manipulador de solicitações pegará os dados da solicitação e executará operações na fonte de dados. O manipulador de respostas processará a resposta da fonte de dados antes de passá-la de volta para a lista. Se houver mais de uma função, os dados da solicitação serão enviados para a próxima função a ser executada na lista. As funções na lista serão executadas na ordem definida pelo desenvolvedor. Depois que todas as funções forem executadas, o resultado final será passado para a etapa posterior.
+ **Etapa Posterior**: A etapa Posterior é uma função do manipulador que permite realizar algumas operações finais na resposta da função final antes de passá-la para a resposta do GraphQL.
Esse fluxo é um exemplo de um resolvedor de pipeline. Os resolvedores de pipeline são compatíveis em ambos os runtimes. No entanto, essa é uma explicação simplificada do que os resolvedores de pipeline podem fazer. Além disso, estamos descrevendo apenas uma configuração possível do resolvedor. Para obter mais informações sobre as configurações de resolvedor compatíveis, consulte a [Visão geral dos resolvedores do JavaScript](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-overview-js.html) para APPSYNC\$1JS ou a [Visão geral do modelo de mapeamento do resolvedor](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-mapping-template-reference-overview.html) para VTL.
Como você pode ver, os resolvedores são modulares. Para que os componentes do resolvedor funcionem corretamente, eles devem ser capazes de examinar o estado da execução por meio de outros componentes. Na seção [Resolvedores](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-components.html), você sabe que cada componente no resolvedor pode receber informações essenciais sobre o estado da execução como um conjunto de argumentos (`args`, `context` etc.). Em AWS AppSync, isso é tratado estritamente pelo `context`. Trata-se de um contêiner para as informações sobre o campo que está sendo resolvido. Isso pode incluir tudo, desde argumentos passados, resultados, dados de autorização, dados de cabeçalho etc. Para obter mais informações sobre o contexto, consulte [Referência do objeto de contexto do resolvedor](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-context-reference-js.html) para APPSYNC\$1JS ou a [Referência de contexto do modelo de mapeamento do resolvedor](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-context-reference.html) para VTL.
O contexto não é a única ferramenta que você pode usar para implementar seu resolvedor. O AWS AppSync suporta uma ampla variedade de utilitários para geração de valor, tratamento de erros, análise, conversão etc. Você pode ver uma lista de utilitários [aqui](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-util-reference-js.html) para APPSYNC\$1JS ou [aqui](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-util-reference.html) para VTL.
Nas seções a seguir, você vai aprender a configurar resolvedores na API do GraphQL.
**Topics**
+ [Criação de consultas básicas () JavaScript](configuring-resolvers-js.md)
+ [Criação de consultas básicas (VTL)](configuring-resolvers.md)
# Criação de consultas básicas () JavaScript
Os resolvedores do GraphQL conectam os campos em um esquema de tipo a uma fonte de dados. Os resolvedores são o mecanismo pelo qual as solicitações são atendidas.
Resolvedores em AWS AppSync uso JavaScript para converter uma expressão GraphQL em um formato que a fonte de dados possa usar. Como alternativa, os modelos de mapeamento podem ser escritos em [Apache VTL (Velocity Template Language)](https://velocity.apache.org/engine/2.0/vtl-reference.html) para converter uma expressão de GraphQL em um formato que a fonte de dados possa usar.
Esta seção descreve como configurar resolvedores usando o. JavaScript A seção [Tutoriais do Resolver (JavaScript)](https://docs.aws.amazon.com/appsync/latest/devguide/tutorials-js.html) fornece tutoriais detalhados sobre como implementar resolvedores usando. JavaScript A seção [Referência do Resolvedor (JavaScript)](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html) fornece uma explicação das operações do utilitário que podem ser usadas com JavaScript resolvedores.
Recomendamos seguir este guia antes de tentar usar qualquer um dos tutoriais mencionados acima.
Nesta seção, mostraremos como criar e configurar resolvedores de consultas e mutações.
**nota**
Este guia pressupõe que você tenha criado seu esquema e tenha pelo menos uma consulta ou mutação. Se você estiver procurando por assinaturas (dados em tempo real), consulte [este guia](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-real-time-data.html).
Nesta seção, abordaremos algumas etapas gerais para configurar resolvedores e mostraremos um exemplo com o esquema abaixo:
```
// schema.graphql file
input CreatePostInput {
title: String
date: AWSDateTime
}
type Post {
id: ID!
title: String
date: AWSDateTime
}
type Mutation {
createPost(input: CreatePostInput!): Post
}
type Query {
getPost: [Post]
}
```
## Criação de resolvedores de consultas básicos
Esta seção mostrará como criar um resolvedor de consultas básico.
------
#### [ Console ]
1. Faça login no Console de gerenciamento da AWS e abra o [AppSyncconsole](https://console.aws.amazon.com/appsync/).
1. No **APIs painel**, escolha sua API GraphQL.
1. Na **barra lateral**, escolha **Esquema**.
1. Insira os detalhes do esquema e da fonte de dados. Consulte as seções [Criar seu esquema](https://docs.aws.amazon.com/appsync/latest/devguide/designing-your-schema.html) e [Anexar uma fonte de dados](https://docs.aws.amazon.com/appsync/latest/devguide/attaching-a-data-source.html) para obter mais informações.
1. Ao lado do editor de **esquemas**, há uma janela chamada **Resolvedores**. Essa caixa contém uma lista dos tipos e campos conforme definido na janela **Esquema**. É possível anexar resolvedores aos campos. Você provavelmente estará anexando resolvedores às suas operações de campo. Nesta seção, veremos configurações de consultas simples. Em **Tipo de consulta**, escolha **Anexar** ao lado do campo da sua consulta.
1. Na página **Anexar resolvedor**, em **Tipo de resolvedor**, você pode escolher entre resolvedores de pipeline ou de unidade. Para obter mais informações sobre esses tipos de regra, consulte [Resolvedores](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-components.html). Este guia fará uso de `pipeline resolvers`.
**dica**
Ao criar resolvedores de pipeline, suas fontes de dados serão anexadas às funções do pipeline. As funções são geradas depois que você cria o próprio resolvedor de pipeline, e é por isso que não há opção de configurá-lo nesta página. Se você estiver usando um resolvedor de unidades, a fonte de dados estará vinculada diretamente ao resolvedor, portanto, você o definiria nesta página.
Para o **tempo de execução do Resolver**, escolha `APPSYNC_JS` ativar o JavaScript tempo de execução.
1. Você pode ativar o [armazenamento em cache](https://docs.aws.amazon.com/appsync/latest/devguide/enabling-caching.html) dessa API. Recomendamos desativar esse atributo por enquanto. Selecione **Criar**.
1. Na página **Editar resolvedor**, há um editor de código chamado **Código do resolvedor** que permite implementar a lógica para o manipulador e a resposta do resolvedor (etapas anterior e posterior). Para obter mais informações, consulte a [visão geral dos JavaScript resolvedores](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-overview-js.html).
**nota**
Em nosso exemplo, vamos deixar a solicitação em branco e a resposta definida para retornar o resultado da última fonte de dados do [contexto](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-context-reference-js.html):
```
import {util} from '@aws-appsync/utils';
export function request(ctx) {
return {};
}
export function response(ctx) {
return ctx.prev.result;
}
```
Abaixo dessa seção, há uma tabela chamada **Funções**. As funções permitem que você implemente códigos que possam ser reutilizados em vários resolvedores. Em vez de reescrever ou copiar sempre o código, você pode armazenar o código-fonte como uma função a ser adicionada a um resolvedor sempre que precisar.
As funções compõem a maior parte da lista de operações de um pipeline. Ao usar várias funções em um resolvedor, você define a ordem das funções, e elas serão executadas nessa ordem sequencialmente. Elas são executadas depois da função de solicitação e antes do início da função de resposta.
Para adicionar uma nova função, em **Funções**, escolha **Adicionar função** e, em seguida, **Criar nova função**. Como alternativa, pode haver um botão **Criar função** para escolher.
1. Escolha uma fonte de dados. Essa será a fonte de dados em que o resolvedor vai atuar.
**nota**
Em nosso exemplo, estamos anexando um resolvedor para `getPost`, que recupera um objeto `Post` pelo `id`. Vamos supor que já tenhamos configurado uma tabela do DynamoDB para esse esquema. Sua chave de partição está vazia e definida como `id`.
1. Insira um `Function name`.
1. Em **Código da função**, você precisará implementar o comportamento da função. Isso pode ser confuso, mas cada função terá seu próprio manipulador local de solicitações e respostas. A solicitação é executada e, em seguida, a invocação da fonte de dados é feita para lidar com a solicitação e, em seguida, a resposta da fonte de dados é processada pelo manipulador. O resultado é armazenado no objeto do [contexto](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-context-reference-js.html). Depois disso, a próxima função na lista será executada ou transmitida para o manipulador de resposta da etapa posterior, se for a última.
**nota**
Em nosso exemplo, estamos anexando um resolvedor ao `getPost`, que obtém uma lista de objetos `Post` da fonte de dados. Nossa função de solicitação solicitará os dados da nossa tabela, a tabela passará sua resposta para o contexto (ctx) e, em seguida, a resposta retornará o resultado no contexto. AWS AppSync A força da está em sua interconexão com outros serviços. AWS Como estamos usando o DynamoDB, temos [um conjunto de operações](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html) para simplificar processos como esses. Também temos alguns exemplos padronizados para outros tipos de fontes de dados.
Nosso código será semelhante a este:
```
import { util } from '@aws-appsync/utils';
/**
* Performs a scan on the dynamodb data source
*/
export function request(ctx) {
return { operation: 'Scan' };
}
/**
* return a list of scanned post items
*/
export function response(ctx) {
return ctx.result.items;
}
```
Nesta etapa, adicionamos duas funções:
`request`: o manipulador de solicitações executa a operação de recuperação na fonte de dados. O argumento contém o objeto de contexto (`ctx`) ou alguns dados que estão disponíveis para todos os resolvedores que executam uma operação específica. Por exemplo, ele pode conter dados de autorização, os nomes dos campos que estão sendo resolvidos etc. A instrução return executa uma operação de [https://docs.aws.amazon.com//appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-scan](https://docs.aws.amazon.com//appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-scan) (confira exemplos [aqui](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Scan.html)). Como estamos trabalhando com o DynamoDB, podemos usar algumas das operações desse serviço. A verificação executa uma busca básica de todos os itens em nossa tabela. O resultado dessa operação é armazenado no objeto de contexto como um contêiner de `result` antes de ser transmitido ao manipulador de respostas. A `request` é executada antes da resposta no pipeline.
`response`: o manipulador de respostas que retorna o resultado da `request`. O argumento é o objeto de contexto atualizado e a instrução de retorno é `ctx.prev.result`. Neste ponto do guia, é possível que você não conheça esse valor. `ctx` refere-se ao objeto de contexto, e `prev` refere-se à operação anterior no pipeline, que era nossa `request`. O `result` contém os resultados do resolvedor à medida que ele se move pelo pipeline. Se você juntar tudo isso, `ctx.prev.result` está retornando o resultado da última operação realizada, que foi o manipulador da solicitação.
1. Depois de concluir, escolha **Criar**.
1. De volta à tela do resolvedor, em **Funções**, escolha o menu suspenso **Adicionar função** e inclua sua função na sua lista.
1. Escolha **Salvar** para atualizar o resolvedor.
------
#### [ CLI ]
**Para adicionar sua função**
+ Crie uma função para seu resolvedor de pipeline usando o comando `[create-function](https://docs.aws.amazon.com/cli/latest/reference/appsync/create-function.html)`.
Você precisará inserir alguns parâmetros para esse comando específico:
1. O `api-id` da sua API.
1. O `name` da função no AWS AppSync console.
1. O `data-source-name`, ou o nome da fonte de dados que a função usará. Ele já deve ter sido criado e vinculado à sua API do GraphQL no serviço do AWS AppSync .
1. O`runtime`, ou ambiente e idioma da função. Para JavaScript, o nome deve ser`APPSYNC_JS`, e o tempo de execução,`1.0.0`.
1. O `code`, ou manipuladores de solicitações e respostas de sua função. Embora você possa digitá-lo manualmente, é muito mais fácil adicioná-lo a um arquivo .txt (ou formato similar) e depois transmiti-lo como argumento.
**nota**
Nosso código de consulta estará em um arquivo transmitido como argumento:
```
import { util } from '@aws-appsync/utils';
/**
* Performs a scan on the dynamodb data source
*/
export function request(ctx) {
return { operation: 'Scan' };
}
/**
* return a list of scanned post items
*/
export function response(ctx) {
return ctx.result.items;
}
```
Veja um exemplo de comando:
```
aws appsync create-function \
--api-id abcdefghijklmnopqrstuvwxyz \
--name get_posts_func_1 \
--data-source-name table-for-posts \
--runtime name=APPSYNC_JS,runtimeVersion=1.0.0 \
--code file://~/path/to/file/{filename}.{fileType}
```
Uma saída será retornada na CLI. Veja um exemplo abaixo:
```
{
"functionConfiguration": {
"functionId": "ejglgvmcabdn7lx75ref4qeig4",
"functionArn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz/functions/ejglgvmcabdn7lx75ref4qeig4",
"name": "get_posts_func_1",
"dataSourceName": "table-for-posts",
"maxBatchSize": 0,
"runtime": {
"name": "APPSYNC_JS",
"runtimeVersion": "1.0.0"
},
"code": "Code output goes here"
}
}
```
**nota**
Certifique-se de gravar o `functionId` em algum lugar, pois isso será usado para anexar a função ao solucionados.
**Criar seu resolvedor**
+ Crie uma função de pipeline para `Query` executando o comando `[create-resolver](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/create-resolver.html)`.
Você precisará inserir alguns parâmetros para esse comando específico:
1. O `api-id` da sua API.
1. O `type-name`, ou o tipo de objeto especial em seu esquema (consulta, mutação, assinatura).
1. O `field-name` ou a operação do campo no tipo de objeto especial a ser anexado ao resolvedor.
1. O `kind`, que especifica um resolvedor de unidade ou pipeline. Defina como `PIPELINE` para ativar as funções do pipeline.
1. A `pipeline-config`, ou as funções a serem anexadas ao resolvedor. É preciso saber os valores de `functionId` de suas funções. A ordem da listagem é importante.
1. O`runtime`, que foi `APPSYNC_JS` (JavaScript). Atualmente o `runtimeVersion` é`1.0.0`.
1. O `code`, que contém os manipuladores das etapas anterior e posterior.
**nota**
Nosso código de consulta estará em um arquivo transmitido como argumento:
```
import { util } from '@aws-appsync/utils';
/**
* Sends a request to `put` an item in the DynamoDB data source
*/
export function request(ctx) {
const { id, ...values } = ctx.args;
return {
operation: 'PutItem',
key: util.dynamodb.toMapValues({ id }),
attributeValues: util.dynamodb.toMapValues(values),
};
}
/**
* returns the result of the `put` operation
*/
export function response(ctx) {
return ctx.result;
}
```
Veja um exemplo de comando:
```
aws appsync create-resolver \
--api-id abcdefghijklmnopqrstuvwxyz \
--type-name Query \
--field-name getPost \
--kind PIPELINE \
--pipeline-config functions=ejglgvmcabdn7lx75ref4qeig4 \
--runtime name=APPSYNC_JS,runtimeVersion=1.0.0 \
--code file:///path/to/file/{filename}.{fileType}
```
Uma saída será retornada na CLI. Veja um exemplo abaixo:
```
{
"resolver": {
"typeName": "Mutation",
"fieldName": "getPost",
"resolverArn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz/types/Mutation/resolvers/getPost",
"kind": "PIPELINE",
"pipelineConfig": {
"functions": [
"ejglgvmcabdn7lx75ref4qeig4"
]
},
"maxBatchSize": 0,
"runtime": {
"name": "APPSYNC_JS",
"runtimeVersion": "1.0.0"
},
"code": "Code output goes here"
}
}
```
------
#### [ CDK ]
**dica**
[Antes de usar o CDK, recomendamos revisar a [documentação oficial](https://docs.aws.amazon.com/cdk/v2/guide/home.html) do CDK junto com AWS AppSync a referência do CDK.](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_appsync-readme.html)
As etapas listadas abaixo mostram apenas um exemplo geral do trecho usado para adicionar um recurso específico. Isso **não** é uma solução funcional para seu código de produção. Também presumimos que você já tenha uma aplicação em funcionamento.
Uma aplicação básica precisará do seguinte:
1. Diretivas de importação de serviços
1. Código do esquema
1. Gerador de fontes de dados
1. Código da função
1. Código do resolvedor
Nas seções [Projetar seu esquema](https://docs.aws.amazon.com/appsync/latest/devguide/designing-your-schema.html) e [Anexar uma fonte de dados](https://docs.aws.amazon.com/appsync/latest/devguide/attaching-a-data-source.html), sabemos que o arquivo de pilha incluirá as diretivas de importação do formulário:
```
import * as x from 'x'; # import wildcard as the 'x' keyword from 'x-service'
import {a, b, ...} from 'c'; # import {specific constructs} from 'c-service'
```
**nota**
Nas seções anteriores, declaramos apenas como importar AWS AppSync construções. Em código real, você precisará importar mais serviços apenas para executar a aplicação. Em nosso exemplo, se criássemos um aplicativo CDK muito simples, importaríamos pelo menos o AWS AppSync serviço junto com nossa fonte de dados, que era uma tabela do DynamoDB. Também precisaríamos importar algumas estruturas adicionais para implantar a aplicação:
```
import * as cdk from 'aws-cdk-lib';
import * as appsync from 'aws-cdk-lib/aws-appsync';
import * as dynamodb from 'aws-cdk-lib/aws-dynamodb';
import { Construct } from 'constructs';
```
Para resumir cada uma delas:
`import * as cdk from 'aws-cdk-lib';`: isso permite que você defina a aplicação e as estruturas do CDK, como a pilha. Ela também contém algumas funções utilitárias relevantes para nosso aplicativo, como a manipulação de metadados. Se você já conhece essa diretiva de importação, mas não sabe por que a biblioteca principal do CDK não está sendo usada aqui, consulte a página de [migração](https://docs.aws.amazon.com/cdk/v2/guide/migrating-v2.html).
`import * as appsync from 'aws-cdk-lib/aws-appsync';`: isso importa o [serviço do AWS AppSync](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_appsync-readme.html).
`import * as dynamodb from 'aws-cdk-lib/aws-dynamodb';`: isso importa o [serviço do DynamoDB](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_dynamodb-readme.html).
`import { Construct } from 'constructs';`: precisamos disso para definir a [estrutura](https://docs.aws.amazon.com/cdk/v2/guide/constructs.html)-raiz.
O tipo de importação depende dos serviços que você está chamando. Recomendamos consultar a documentação do CDK para ver exemplos. O esquema na parte superior da página será um arquivo separado na sua aplicação do CDK como um arquivo `.graphql`. No arquivo de pilha, podemos associá-lo a um novo GraphQL usando este formato:
```
const add_api = new appsync.GraphqlApi(this, 'graphQL-example', {
name: 'my-first-api',
schema: appsync.SchemaFile.fromAsset(path.join(__dirname, 'schema.graphql')),
});
```
**nota**
No escopo do `add_api`, vamos adicionar uma nova API GraphQL usando a `new` palavra-chave seguida por `appsync.GraphqlApi(scope: Construct, id: string , props: GraphqlApiProps)`. Nosso escopo é `this`, o ID do CFN é `graphQL-example`, e nossas propriedades são `my-first-api` (nome da API no console) e `schema.graphql` (o caminho absoluto para o arquivo do esquema).
Para incluir uma fonte de dados, primeiro você precisa adicionar sua fonte de dados à pilha. Em seguida, associá-la à API GraphQL usando o método específico da fonte. A associação acontecerá quando seu resolvedor funcionar. Enquanto isso, vamos usar um exemplo criando a tabela do DynamoDB usando `dynamodb.Table`:
```
const add_ddb_table = new dynamodb.Table(this, 'posts-table', {
partitionKey: {
name: 'id',
type: dynamodb.AttributeType.STRING,
},
});
```
**nota**
Se usássemos isso em nosso exemplo, adicionaríamos uma nova tabela do DynamoDB com o ID do CFN e uma chave de partição `posts-table` do `id (S)`.
Em seguida, precisamos implementar nosso resolvedor no arquivo de pilha. Veja a seguir um exemplo de uma consulta simples que verifica todos os itens em uma tabela do DynamoDB:
```
const add_func = new appsync.AppsyncFunction(this, 'func-get-posts', {
name: 'get_posts_func_1',
add_api,
dataSource: add_api.addDynamoDbDataSource('table-for-posts', add_ddb_table),
code: appsync.Code.fromInline(`
export function request(ctx) {
return { operation: 'Scan' };
}
export function response(ctx) {
return ctx.result.items;
}
`),
runtime: appsync.FunctionRuntime.JS_1_0_0,
});
new appsync.Resolver(this, 'pipeline-resolver-get-posts', {
add_api,
typeName: 'Query',
fieldName: 'getPost',
code: appsync.Code.fromInline(`
export function request(ctx) {
return {};
}
export function response(ctx) {
return ctx.prev.result;
}
`),
runtime: appsync.FunctionRuntime.JS_1_0_0,
pipelineConfig: [add_func],
});
```
**nota**
Primeiro, criamos uma função chamada `add_func`. Essa ordem de criação pode parecer um pouco contraintuitiva, mas você precisa criar as funções em seu resolvedor de pipeline antes de criar o próprio resolvedor. Uma função segue o formato:
```
AppsyncFunction(scope: Construct, id: string, props: AppsyncFunctionProps)
```
Nosso escopo era `this`, nosso ID de CFN, `func-get-posts`, e nossas propriedades continham os detalhes reais da função. Dentro das propriedades, incluímos:
A `name` da função que estará presente no AWS AppSync console (`get_posts_func_1`).
A API GraphQL que criamos anteriormente (`add_api`).
A fonte de dados; esse é o ponto em que vinculamos a fonte de dados ao valor da API GraphQL e a anexamos à função. Pegamos a tabela que criamos (`add_ddb_table`) e a anexamos à API GraphQL (`add_api`) usando um dos métodos `GraphqlApi` ([https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_appsync.GraphqlApi.html#addwbrdynamowbrdbwbrdatawbrsourceid-table-options](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_appsync.GraphqlApi.html#addwbrdynamowbrdbwbrdatawbrsourceid-table-options)). O valor do ID (`table-for-posts`) é o nome da fonte de dados no console do AWS AppSync . Para obter a lista dos métodos específicos da fonte, consulte as seguintes páginas:
[ DynamoDbDataSource ](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_appsync.DynamoDbDataSource.html)
[ EventBridgeDataSource ](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_appsync.EventBridgeDataSource.html)
[ HttpDataSource ](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_appsync.HttpDataSource.html)
[ LambdaDataSource ](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_appsync.LambdaDataSource.html)
[ NoneDataSource ](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_appsync.NoneDataSource.html)
[ OpenSearchDataSource ](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_appsync.OpenSearchDataSource.html)
[ RdsDataSource ](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_appsync.RdsDataSource.html)
O código contém os manipuladores de solicitações e respostas da nossa função, que são uma simples digitalização e retorno.
O runtime especifica que queremos usar a versão 1.0.0 do runtime do APPSYNC\$1JS. Observe que atualmente essa é a única versão disponível do APPSYNC\$1JS.
Em seguida, precisamos anexar a função ao resolvedor de pipeline. Criamos nosso resolvedor usando o formulário:
```
Resolver(scope: Construct, id: string, props: ResolverProps)
```
Nosso escopo era `this`, nosso ID de CFN, `pipeline-resolver-get-posts`, e nossas propriedades continham os detalhes reais da função. Dentro das propriedades, incluímos:
A API GraphQL que criamos anteriormente (`add_api`).
O nome do tipo de objeto especial; essa é uma operação de consulta, então só adicionamos o valor da `Query`.
O nome do campo (`getPost`) é aquele no esquema abaixo do tipo de `Query`.
O código contém seus manipuladores de antes e depois. Nosso exemplo só vão retornar os resultados que estavam no contexto depois que a função tiver executado a operação.
O runtime especifica que queremos usar a versão 1.0.0 do runtime do APPSYNC\$1JS. Observe que atualmente essa é a única versão disponível do APPSYNC\$1JS.
A configuração do pipeline contém a referência à função que criamos (`add_func`).
------
Para resumir o que aconteceu neste exemplo, você viu uma AWS AppSync função que implementou um manipulador de solicitações e respostas. A função foi responsável por interagir com sua fonte de dados. O manipulador da solicitação enviou uma `Scan` operação para AWS AppSync, instruindo-a sobre qual operação realizar na sua fonte de dados do DynamoDB. O manipulador de respostas retornou a lista de itens (`ctx.result.items`). A lista de itens foi então mapeada automaticamente para o tipo `Post` GraphQL.
## Criar resolvedores básicos de mutação
Esta seção mostrará como criar um resolvedor de mutação básico.
------
#### [ Console ]
1. Faça login no Console de gerenciamento da AWS e abra o [AppSyncconsole](https://console.aws.amazon.com/appsync/).
1. No **APIs painel**, escolha sua API GraphQL.
1. Na **barra lateral**, escolha **Esquema**.
1. Na seção **Resolvedores** e no tipo de **mutação**, escolha **Anexar** ao lado do seu campo.
**nota**
Em nosso exemplo, estamos anexando um resolvedor para `createPost`, que recupera um objeto `Post` para nossa tabela. Vamos supor que estamos usando a mesma tabela do DynamoDB da última seção. Sua chave de partição está vazia e definida como `id`.
1. Na página **Anexar resolvedor**, em **Tipo de resolvedor**, escolha `pipeline resolvers`. Como lembrete, você pode encontrar mais informações sobre resolvedores [aqui](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-components.html). Para o **tempo de execução do Resolver**, escolha `APPSYNC_JS` ativar o JavaScript tempo de execução.
1. Você pode ativar o [armazenamento em cache](https://docs.aws.amazon.com/appsync/latest/devguide/enabling-caching.html) dessa API. Recomendamos desativar esse atributo por enquanto. Selecione **Criar**.
1. Escolha **Adicionar função** e, em seguida, **Criar nova função**. Como alternativa, pode haver um botão **Criar função** para escolher.
1. Selecione sua fonte de dados. Essa deve ser a fonte cujos dados você manipulará com a mutação.
1. Insira um `Function name`.
1. Em **Código da função**, você precisará implementar o comportamento da função. Isso é uma mutação, portanto, o ideal é que a solicitação realize alguma operação de mudança de estado na fonte de dados invocada. O resultado será processado pela função de resposta.
**nota**
O `createPost` adiciona ou “insere” um novo `Post` na tabela com nossos parâmetros como dados. Isso pode ser semelhante a:
```
import { util } from '@aws-appsync/utils';
/**
* Sends a request to `put` an item in the DynamoDB data source
*/
export function request(ctx) {
return {
operation: 'PutItem',
key: util.dynamodb.toMapValues({id: util.autoId()}),
attributeValues: util.dynamodb.toMapValues(ctx.args.input),
};
}
/**
* returns the result of the `put` operation
*/
export function response(ctx) {
return ctx.result;
}
```
Nesta etapa, adicionamos as funções `request` e `response`:
`request`: o manipulador da solicitação aceita o contexto como argumento. A instrução return do manipulador de solicitações executa um comando [https://docs.aws.amazon.com//appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-putitem](https://docs.aws.amazon.com//appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-putitem), que é uma operação integrada do DynamoDB (confira alguns exemplos [neste link](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/getting-started-step-2.html) ou [aqui](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/WorkingWithItems.html#WorkingWithItems.WritingData)). O comando `PutItem` adiciona um objeto `Post` à nossa tabela do DynamoDB considerando o valor `key` da partição (gerado automaticamente por `util.autoid()`) e `attributes` a partir da entrada do argumento de contexto (esses são os valores que vamos transmitir em nossa solicitação). A `key` é o `id`, e os `attributes` são os argumentos de campo `date` e `title`. Ambos são pré-formatados por meio do auxiliar [https://docs.aws.amazon.com//appsync/latest/devguide/dynamodb-helpers-in-util-dynamodb-js.html#utility-helpers-in-toMap-js](https://docs.aws.amazon.com//appsync/latest/devguide/dynamodb-helpers-in-util-dynamodb-js.html#utility-helpers-in-toMap-js) para trabalhar com a tabela do DynamoDB.
`response`: a resposta aceita o contexto atualizado e retorna o resultado do manipulador da solicitação.
1. Depois de concluir, escolha **Criar**.
1. De volta à tela do resolvedor, em **Funções**, escolha o menu suspenso **Adicionar função** e inclua sua função na sua lista.
1. Escolha **Salvar** para atualizar o resolvedor.
------
#### [ CLI ]
**Para adicionar sua função**
+ Crie uma função para seu resolvedor de pipeline usando o comando `[create-function](https://docs.aws.amazon.com/cli/latest/reference/appsync/create-function.html)`.
Você precisará inserir alguns parâmetros para esse comando específico:
1. O `api-id` da sua API.
1. O `name` da função no AWS AppSync console.
1. O `data-source-name`, ou o nome da fonte de dados que a função usará. Ele já deve ter sido criado e vinculado à sua API do GraphQL no serviço do AWS AppSync .
1. O`runtime`, ou ambiente e idioma da função. Para JavaScript, o nome deve ser`APPSYNC_JS`, e o tempo de execução,`1.0.0`.
1. O `code`, ou manipuladores de solicitações e respostas de sua função. Embora você possa digitá-lo manualmente, é muito mais fácil adicioná-lo a um arquivo .txt (ou formato similar) e depois transmiti-lo como argumento.
**nota**
Nosso código de consulta estará em um arquivo transmitido como argumento:
```
import { util } from '@aws-appsync/utils';
/**
* Sends a request to `put` an item in the DynamoDB data source
*/
export function request(ctx) {
return {
operation: 'PutItem',
key: util.dynamodb.toMapValues({id: util.autoId()}),
attributeValues: util.dynamodb.toMapValues(ctx.args.input),
};
}
/**
* returns the result of the `put` operation
*/
export function response(ctx) {
return ctx.result;
}
```
Veja um exemplo de comando:
```
aws appsync create-function \
--api-id abcdefghijklmnopqrstuvwxyz \
--name add_posts_func_1 \
--data-source-name table-for-posts \
--runtime name=APPSYNC_JS,runtimeVersion=1.0.0 \
--code file:///path/to/file/{filename}.{fileType}
```
Uma saída será retornada na CLI. Veja um exemplo abaixo:
```
{
"functionConfiguration": {
"functionId": "vulcmbfcxffiram63psb4dduoa",
"functionArn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz/functions/vulcmbfcxffiram63psb4dduoa",
"name": "add_posts_func_1",
"dataSourceName": "table-for-posts",
"maxBatchSize": 0,
"runtime": {
"name": "APPSYNC_JS",
"runtimeVersion": "1.0.0"
},
"code": "Code output foes here"
}
}
```
**nota**
Certifique-se de gravar o `functionId` em algum lugar, pois isso será usado para anexar a função ao solucionados.
**Criar seu resolvedor**
+ Crie uma função de pipeline para `Mutation` executando o comando `[create-resolver](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/create-resolver.html)`.
Você precisará inserir alguns parâmetros para esse comando específico:
1. O `api-id` da sua API.
1. O `type-name`, ou o tipo de objeto especial em seu esquema (consulta, mutação, assinatura).
1. O `field-name` ou a operação do campo no tipo de objeto especial a ser anexado ao resolvedor.
1. O `kind`, que especifica um resolvedor de unidade ou pipeline. Defina como `PIPELINE` para ativar as funções do pipeline.
1. A `pipeline-config`, ou as funções a serem anexadas ao resolvedor. É preciso saber os valores de `functionId` de suas funções. A ordem da listagem é importante.
1. O`runtime`, que foi `APPSYNC_JS` (JavaScript). Atualmente o `runtimeVersion` é`1.0.0`.
1. O `code`, que contém os manipuladores das etapas anterior e posterior.
**nota**
Nosso código de consulta estará em um arquivo transmitido como argumento:
```
import { util } from '@aws-appsync/utils';
/**
* Sends a request to `put` an item in the DynamoDB data source
*/
export function request(ctx) {
const { id, ...values } = ctx.args;
return {
operation: 'PutItem',
key: util.dynamodb.toMapValues({ id }),
attributeValues: util.dynamodb.toMapValues(values),
};
}
/**
* returns the result of the `put` operation
*/
export function response(ctx) {
return ctx.result;
}
```
Veja um exemplo de comando:
```
aws appsync create-resolver \
--api-id abcdefghijklmnopqrstuvwxyz \
--type-name Mutation \
--field-name createPost \
--kind PIPELINE \
--pipeline-config functions=vulcmbfcxffiram63psb4dduoa \
--runtime name=APPSYNC_JS,runtimeVersion=1.0.0 \
--code file:///path/to/file/{filename}.{fileType}
```
Uma saída será retornada na CLI. Veja um exemplo abaixo:
```
{
"resolver": {
"typeName": "Mutation",
"fieldName": "createPost",
"resolverArn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz/types/Mutation/resolvers/createPost",
"kind": "PIPELINE",
"pipelineConfig": {
"functions": [
"vulcmbfcxffiram63psb4dduoa"
]
},
"maxBatchSize": 0,
"runtime": {
"name": "APPSYNC_JS",
"runtimeVersion": "1.0.0"
},
"code": "Code output goes here"
}
}
```
------
#### [ CDK ]
**dica**
[Antes de usar o CDK, recomendamos revisar a [documentação oficial](https://docs.aws.amazon.com/cdk/v2/guide/home.html) do CDK junto com AWS AppSync a referência do CDK.](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_appsync-readme.html)
As etapas listadas abaixo mostram apenas um exemplo geral do trecho usado para adicionar um recurso específico. Isso **não** é uma solução funcional para seu código de produção. Também presumimos que você já tenha uma aplicação em funcionamento.
+ Para fazer uma mutação, supondo que esteja no mesmo projeto, você pode adicioná-la ao arquivo de pilha como na consulta. Aqui está uma função e um resolvedor modificados para uma mutação que adiciona uma nova `Post` à tabela:
```
const add_func_2 = new appsync.AppsyncFunction(this, 'func-add-post', {
name: 'add_posts_func_1',
add_api,
dataSource: add_api.addDynamoDbDataSource('table-for-posts-2', add_ddb_table),
code: appsync.Code.fromInline(`
export function request(ctx) {
return {
operation: 'PutItem',
key: util.dynamodb.toMapValues({id: util.autoId()}),
attributeValues: util.dynamodb.toMapValues(ctx.args.input),
};
}
export function response(ctx) {
return ctx.result;
}
`),
runtime: appsync.FunctionRuntime.JS_1_0_0,
});
new appsync.Resolver(this, 'pipeline-resolver-create-posts', {
add_api,
typeName: 'Mutation',
fieldName: 'createPost',
code: appsync.Code.fromInline(`
export function request(ctx) {
return {};
}
export function response(ctx) {
return ctx.prev.result;
}
`),
runtime: appsync.FunctionRuntime.JS_1_0_0,
pipelineConfig: [add_func_2],
});
```
**nota**
Como essa mutação e a consulta são estruturadas de forma semelhante, explicaremos apenas as alterações que implementamos para fazer a mutação.
Na função, alteramos o ID da CFN `func-add-post` e o nome para `add_posts_func_1` para refletir o fato de que estamos adicionando `Posts` à tabela. Na fonte de dados, fizemos uma nova associação à nossa tabela (`add_ddb_table`) no AWS AppSync console `table-for-posts-2` porque o `addDynamoDbDataSource` método exige isso. Lembre-se de que essa nova associação ainda está usando a mesma tabela que criamos anteriormente, mas agora temos duas conexões com ela no AWS AppSync console: uma para a consulta as `table-for-posts` e outra para a mutação as`table-for-posts-2`. O código foi alterado para adicionar uma `Post` gerando o valor do `id` automaticamente e aceitando a entrada de um cliente para o resto dos campos.
No resolvedor, mudamos o valor do ID para `pipeline-resolver-create-posts` a fim de refletir o fato de que estamos adicionando `Posts` à tabela. Para refletir a mutação no esquema, o nome do tipo mudou para `Mutation`, e o nome para `createPost`. A configuração do pipeline foi definida para nossa nova função de mutação `add_func_2`.
------
Para resumir o que está acontecendo neste exemplo, converte AWS AppSync automaticamente os argumentos definidos no `createPost` campo do seu esquema do GraphQL em operações do DynamoDB. O exemplo armazena registros no DynamoDB usando uma chave do `id`, que é criada automaticamente usando nosso auxiliar `util.autoId()`. Todos os outros campos que você passar para os argumentos de contexto (`ctx.args.input`) de solicitações feitas no AWS AppSync console ou de outra forma serão armazenados como atributos da tabela. Tanto a chave quanto os atributos são mapeados automaticamente para um formato compatível do DynamoDB usando o auxiliar `util.dynamodb.toMapValues(values)`.
AWS AppSync também oferece suporte a fluxos de trabalho de teste e depuração para edição de resolvedores. Use um objeto `context` de simulação para ver o valor do modelo transformado antes da invocá-lo. Uma alternativa é visualizar a execução de solicitação completa de uma fonte de dados de forma interativa ao executar uma consulta. Para obter mais informações, consulte [Resolvers de teste e depuração (JavaScript)](https://docs.aws.amazon.com/appsync/latest/devguide/test-debug-resolvers-js.html) e [Monitoramento e registro](https://docs.aws.amazon.com/appsync/latest/devguide/monitoring.html#aws-appsync-monitoring).
## Resolvedores avançados
Se você estiver seguindo a seção opcional de paginação em [Projetar seu esquema](designing-your-schema.md#aws-appsync-designing-your-schema), ainda precisará adicionar seu resolvedor à sua solicitação para usar a paginação. Nosso exemplo usou uma paginação de consulta chamada `getPosts` para retornar somente uma parte das coisas solicitadas por vez. O código do nosso resolvedor nesse campo pode ter a seguinte aparência:
```
/**
* Performs a scan on the dynamodb data source
*/
export function request(ctx) {
const { limit = 20, nextToken } = ctx.args;
return { operation: 'Scan', limit, nextToken };
}
/**
* @returns the result of the `put` operation
*/
export function response(ctx) {
const { items: posts = [], nextToken } = ctx.result;
return { posts, nextToken };
}
```
Na solicitação, transmitimos no contexto dela. Nosso `limit` é*20*, o que significa que retornamos até 20 `Posts` na primeira consulta. Nosso cursor do `nextToken` está fixo na primeira entrada da `Post` na fonte de dados. Eles são transmitidos para os argumentos. Em seguida, a solicitação executa uma varredura desde a primeira `Post` até o número limite de varredura. A fonte de dados armazena o resultado no contexto, que é transmitido para a resposta. A resposta retorna as `Posts` que foram recuperadas e, em seguida, define `nextToken` como a entrada `Post` logo após o limite. A próxima solicitação é enviada para fazer exatamente a mesma coisa, mas começando pelo deslocamento logo após a primeira consulta. Lembre-se de que esses tipos de solicitações são feitos sequencialmente e não de maneira simultânea.
# Testando e depurando resolvedores em () AWS AppSync JavaScript
AWS AppSync executa resolvedores em um campo GraphQL em relação a uma fonte de dados. Ao trabalhar com resolvedores de pipeline, as funções interagem com suas fontes de dados. Conforme descrito na [visão geral dos JavaScript resolvedores](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-overview-js.html), as funções se comunicam com as fontes de dados usando manipuladores de solicitação e resposta gravados JavaScript e executados no `APPSYNC_JS` tempo de execução. Isso permite fornecer lógica e condições personalizadas antes e depois da comunicação com a fonte de dados.
Para ajudar os desenvolvedores a escrever, testar e depurar esses resolvedores, o AWS AppSync console também fornece ferramentas para criar uma solicitação e uma resposta do GraphQL com dados simulados até o resolvedor de campo individual. Além disso, você pode realizar consultas, mutações e assinaturas no AWS AppSync console e ver um fluxo de log detalhado de toda a solicitação da Amazon. CloudWatch Isso inclui resultados da fonte de dados.
## Testes com dados simulados
Quando um resolvedor do GraphQL é invocado, ele contém um objeto `context` que contém informações relevantes sobre a solicitação. Isso inclui argumentos de um cliente, informações de identidade e dados do campo pai do GraphQL. Ele também armazena os resultados da fonte de dados, que podem ser usados no manipulador de respostas. Para obter mais informações sobre essa estrutura e os utilitários auxiliares disponíveis para usar durante a programação, consulte a [Referência do objeto de contexto do resolvedor](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-context-reference-js.html).
Ao escrever ou editar uma função de resolução, você pode passar um objeto de *contexto simulado* ou de *teste* para o editor do console. Isso permite que você veja como os manipuladores de solicitação e de resposta são avaliados sem realmente serem executados em uma fonte de dados. Por exemplo, você pode enviar um argumento `firstname: Shaggy` de teste e ver como ele avalia ao usar `ctx.args.firstname` no código do modelo. Você também pode testar a avaliação de qualquer utilitário auxiliar, como `util.autoId()` ou `util.time.nowISO8601()`.
### Teste de resolvedores
Este exemplo usará o AWS AppSync console para testar os resolvedores.
1. Faça login no Console de gerenciamento da AWS e abra o [AppSyncconsole](https://console.aws.amazon.com/appsync/).
1. No **APIs painel**, escolha sua API GraphQL.
1. Na **Barra lateral**, escolha **Funções**.
1. Escolha uma função existente.
1. Na parte superior da página **Atualizar função**, escolha **Selecionar contexto de teste** e, em seguida, escolha **Criar novo contexto**.
1. Selecione um objeto de contexto de amostra ou preencha o JSON manualmente na janela **Configurar contexto de teste**.
1. Insira um **nome de contexto de texto**.
1. Clique no botão **Salvar**.
1. Para avaliar o resolvedor usando esse objeto de contexto simulado, escolha **Executar teste**.
Como exemplo mais prático, digamos que você tenha um aplicativo que armazena um tipo do GraphQL `Dog` que usa a geração automática de ID para objetos e os armazena no Amazon DynamoDB. Você também deseja gravar alguns valores dos argumentos de uma mutação do GraphQL e permitir que apenas usuários específicos vejam uma resposta. O trecho a seguir mostra a aparência do esquema:
```
type Dog {
breed: String
color: String
}
type Mutation {
addDog(firstname: String, age: Int): Dog
}
```
Você pode escrever uma AWS AppSync função e adicioná-la ao seu `addDog` resolvedor para lidar com a mutação. Para testar sua AWS AppSync função, você pode preencher um objeto de contexto, como no exemplo a seguir. Ele tem argumentos do cliente de `name` e `age`, e um `username` preenchido no 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"
}
}
```
Você pode testar sua AWS AppSync função usando o seguinte código:
```
import { util } from '@aws-appsync/utils';
export function request(ctx) {
return {
operation: 'PutItem',
key: util.dynamodb.toMapValues({ id: util.autoId() }),
attributeValues: util.dynamodb.toMapValues(ctx.args),
};
}
export function response(ctx) {
if (ctx.identity.username === 'Nadia') {
console.log("This request is allowed")
return ctx.result;
}
util.unauthorized();
}
```
O manipulador de solicitação e resposta avaliado possui os dados do objeto de contexto de teste e o valor gerado de `util.autoId()`. Além disso, se você alterasse o `username` para um valor diferente de `Nadia`, os resultados não seriam retornados pois a verificação de autorização falharia. Para obter mais informações sobre o controle de acesso refinado, consulte [Casos de uso de autorização](security-authorization-use-cases.md#aws-appsync-security-authorization-use-cases).
### Testando manipuladores de solicitações e respostas com's AWS AppSync APIs
Você pode usar o comando API do `EvaluateCode` para testar remotamente seu código com dados simulados. Para começar a usar o comando, certifique-se de ter adicionado a permissão `appsync:evaluateMappingCode` à sua política. Por exemplo:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "appsync:evaluateCode",
"Resource": "arn:aws:appsync:us-east-1:111122223333:*"
}
]
}
```
------
Você pode aproveitar o comando usando o [AWS CLI](https://aws.amazon.com/cli/)ou [AWS SDKs](https://aws.amazon.com/tools/). Por exemplo, veja o `Dog` esquema e seus manipuladores de solicitação e resposta de AWS AppSync função da seção anterior. Usando a CLI em sua estação local, salve o código em um arquivo chamado `code.js` e salve o objeto `context` em um arquivo chamado `context.json`. No seu shell, execute o seguinte comando:
```
$ aws appsync evaluate-code \
--code file://code.js \
--function response \
--context file://context.json \
--runtime name=APPSYNC_JS,runtimeVersion=1.0.0
```
A resposta tem um `evaluationResult` contendo a carga retornada pelo seu manipulador. Também contém um objeto `logs` que contém a lista de logs que foram gerados pelo seu manipulador durante a avaliação. Isso facilita a depuração da execução do código e a visualização de informações sobre sua avaliação para ajudar na solução de problemas. Por exemplo:
```
{
"evaluationResult": "{\"breed\":\"Miniature Schnauzer\",\"color\":\"black_grey\"}",
"logs": [
"INFO - code.js:13:5: \"This request is allowed\""
]
}
```
O `evaluationResult` pode ser analisado como JSON, que fornece:
```
{
"breed": "Miniature Schnauzer",
"color": "black_grey"
}
```
Usando o SDK, você pode incorporar facilmente testes do seu conjunto de testes favorito para validar o comportamento dos seus manipuladores. Recomendamos a criação de testes usando o [Estrutura de trabalho de teste Jest](https://jestjs.io/), mas qualquer conjunto de testes funciona. O trecho a seguir mostra uma execução de validação hipotética. Esperamos que a resposta de avaliação seja um JSON válido, por isso, usamos `JSON.parse` para recuperar o JSON da resposta da string:
```
const AWS = require('aws-sdk')
const fs = require('fs')
const client = new AWS.AppSync({ region: 'us-east-2' })
const runtime = {name:'APPSYNC_JS',runtimeVersion:'1.0.0')
test('request correctly calls DynamoDB', async () => {
const code = fs.readFileSync('./code.js', 'utf8')
const context = fs.readFileSync('./context.json', 'utf8')
const contextJSON = JSON.parse(context)
const response = await client.evaluateCode({ code, context, runtime, function: 'request' }).promise()
const result = JSON.parse(response.evaluationResult)
expect(result.key.id.S).toBeDefined()
expect(result.attributeValues.firstname.S).toEqual(contextJSON.arguments.firstname)
})
```
Isso produz o seguinte 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 totalTime: 1.511 s, estimated 2 s
```
## Depuração de uma consulta atual
Não há substituto para um end-to-end teste e um registro para depurar um aplicativo de produção. AWS AppSync permite que você registre erros e detalhes completos da solicitação usando a Amazon CloudWatch. Além disso, você pode usar o AWS AppSync console para testar consultas, mutações e assinaturas do GraphQL e transmitir ao vivo os dados de log de cada solicitação de volta ao editor de consultas para depuração em tempo real. Para assinaturas, os logs exibem as informações do tempo de conexão.
Para fazer isso, você precisa ter CloudWatch os registros da Amazon habilitados com antecedência, conforme descrito em [Monitoramento e registro](monitoring.md#aws-appsync-monitoring). Em seguida, no AWS AppSync console, escolha a guia **Consultas** e insira uma consulta GraphQL válida. Na seção inferior direita, clique e arraste a janela **Registros em log** para abrir a visualização de registros. No topo da página, escolha o ícone de seta de reprodução para executar a consulta do GraphQL. Em alguns instantes, os logs completos da solicitação e da resposta para a operação serão transmitidos para essa seção e você poderá visualizá-los no console.
# Configurando e usando resolvedores de pipeline em AWS AppSync () JavaScript
AWS AppSync executa resolvedores em um campo GraphQL. Em alguns casos, os aplicativos requerem a execução de várias operações para resolver um único campo do GraphQL. Com os resolvedores de pipeline, os desenvolvedores agora podem elaborar operações chamadas Funções e executá-las em sequência. Os resolvedores de pipeline são úteis para aplicativos que, por exemplo, exigem a execução de uma verificação de autorização antes de obter dados para um campo.
Para obter mais informações sobre a arquitetura de um resolvedor de JavaScript pipeline, consulte a [visão geral dos JavaScript resolvedores](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-overview-js.html#anatomy-of-a-pipeline-resolver-js).
## Etapa 1: criar um resolvedor de pipeline
No AWS AppSync console, acesse a página **Esquema**.
Salve o seguinte esquema:
```
schema {
query: Query
mutation: Mutation
}
type Mutation {
signUp(input: Signup): User
}
type Query {
getUser(id: ID!): User
}
input Signup {
username: String!
email: String!
}
type User {
id: ID!
username: String
email: AWSEmail
}
```
Vamos conectar um resolvedor de pipeline ao campo **signUp** no tipo **Mutação**. No tipo **Mutação** no lado direito, escolha **Anexar** ao lado do campo de mutação `signUp`. Defina o resolvedor como `pipeline resolver` e o runtime `APPSYNC_JS` e, em seguida, crie o resolvedor.
Nosso resolvedor de pipeline cadastra um usuário validando primeiro a entrada do endereço de e-mail e salvando o usuário no sistema. Vamos encapsular a validação de e-mail dentro de uma função **validateEmail** e salvar o usuário dentro de uma função **saveUser**. A função **validateEmail** é executada primeiro e, se o e-mail for válido, a função **saveUser** será executada.
O fluxo de execução será da seguinte forma:
1. Manipulador de solicitações do resolvedor Mutation.signUp
1. Função validateEmail
1. Função saveUser
1. Manipulador de respostas do resolvedor Mutation.signUp
Provavelmente reutilizaremos a função **validateEmail** em outros resolvedores em nossa API. Sendo assim, queremos evitar o acesso a `ctx.args`, já que eles mudarão de um campo do GraphQL para outro. Em vez disso, podemos usar o `ctx.stash` para armazenar o atributo de e-mail a partir do argumento de campo de entrada `signUp(input: Signup)`.
Atualize seu código de resolvedor substituindo as funções de solicitação e resposta:
```
export function request(ctx) {
ctx.stash.email = ctx.args.input.email
return {};
}
export function response(ctx) {
return ctx.prev.result;
}
```
Escolha **Criar** ou **Salvar** para atualizar o resolvedor.
## Etapa 2: criar uma função
Na página do resolvedor de pipeline, na seção **Funções**, clique em **Adicionar função** e em **Criar função**. Também é possível criar funções sem passar pela página do resolvedor; para fazer isso, no AWS AppSync console, acesse a página **Funções**. Selecione o botão **Criar função**. Vamos criar uma função que verifique se um e-mail é válido e proveniente de um domínio específico. Se o e-mail não for válido, a função gerará um erro. Caso contrário, ele encaminha qualquer entrada fornecida.
Crie uma fonte de dados do tipo **NONE**. Escolha a fonte de dados na lista **Nome da fonte de dados**. Em **nome da função**, insira `validateEmail`. Na área **código da função**, substitua tudo por este trecho:
```
import { util } from '@aws-appsync/utils';
export function request(ctx) {
const { email } = ctx.stash;
const valid = util.matches(
'^[a-zA-Z0-9_.+-]+@(?:(?:[a-zA-Z0-9-]+\.)?[a-zA-Z]+\.)?(myvaliddomain)\.com',
email
);
if (!valid) {
util.error(`"${email}" is not a valid email.`);
}
return { payload: { email } };
}
export function response(ctx) {
return ctx.result;
}
```
Revise suas entradas e selecione **Criar**. Acabamos de criar nossa função **validateEmail**. Repita essas etapas para criar a função **saveUser** com o código a seguir (para simplificar, usamos a fonte de dados **NONE** e fingimos que o usuário foi salvo no sistema após a execução da função.):
```
import { util } from '@aws-appsync/utils';
export function request(ctx) {
return ctx.prev.result;
}
export function response(ctx) {
ctx.result.id = util.autoId();
return ctx.result;
}
```
Acabamos de criar nossa função **saveUser**.
## Etapa 3: adicionar uma função a um resolvedor de pipeline
Nossas funções devem ter sido adicionadas automaticamente ao resolvedor de pipeline que acabamos de criar. Se não foi esse o caso ou se você criou as funções por meio da página **Funções**, é possível clicar em **Adicionar função** na página do `signUp` resolvedor para anexá-las. Adicione as funções **validateEmail** e **saveUser** ao resolvedor. A função **validateEmail** deve ser colocada antes da função **saveUser**. À medida que você adiciona mais funções, pode usar as setas **para cima** e **para baixo** para reorganizar a ordem de execução das funções. Revise suas alterações e escolha **Salvar**.
## Etapa 4: executar uma consulta
No AWS AppSync console, acesse a página **Consultas.** No explorador, verifique se você está usando a mutação. Se não estiver, escolha `Mutation` na lista suspensa e escolha `+`. Digite a consulta a seguir:
```
mutation {
signUp(input: {email: "nadia@myvaliddomain.com", username: "nadia"}) {
id
username
}
}
```
Ela deve retornar algo semelhante a:
```
{
"data": {
"signUp": {
"id": "256b6cc2-4694-46f4-a55e-8cb14cc5d7fc",
"username": "nadia"
}
}
}
```
Cadastramos com sucesso nosso usuário e validamos o e-mail de entrada usando um resolvedor de pipeline.
# Criação de consultas básicas (VTL)
**nota**
Agora, oferecemos suporte principalmente ao runtime do APPSYNC\$1JS e sua documentação. Considere usar o runtime do APPSYNC\$1JS e seus guias disponíveis [aqui](https://docs.aws.amazon.com/appsync/latest/devguide/configuring-resolvers-js.html).
Os resolvedores do GraphQL conectam os campos em um esquema de tipo a uma fonte de dados. Os resolvedores são o mecanismo pelo qual as solicitações são atendidas. AWS AppSync pode criar e conectar automaticamente resolvedores a partir de um esquema ou criar um esquema e conectar resolvedores de uma tabela existente sem precisar escrever nenhum código.
Resolvedores em AWS AppSync uso JavaScript para converter uma expressão GraphQL em um formato que a fonte de dados possa usar. Como alternativa, os modelos de mapeamento podem ser escritos em [Apache VTL (Velocity Template Language)](https://velocity.apache.org/engine/2.0/vtl-reference.html) para converter uma expressão de GraphQL em um formato que a fonte de dados possa usar.
Esta seção mostrará como configurar resolvedores de VTL. [Um guia introdutório de programação em estilo tutorial para escrever resolvedores pode ser encontrado no guia de programação do [modelo de mapeamento do Resolver e os utilitários auxiliares disponíveis para uso durante a programação](resolver-mapping-template-reference-programming-guide.md#aws-appsync-resolver-mapping-template-reference-programming-guide) podem ser encontrados na referência de contexto do modelo de mapeamento do Resolver.](resolver-context-reference.md#aws-appsync-resolver-mapping-template-context-reference) AWS AppSync também tem fluxos de teste e depuração integrados que você pode usar ao editar ou criar do zero. Para obter mais informações, consulte [Resolvedores de teste e depuração](test-debug-resolvers.md#aws-appsync-test-debug-resolvers).
Recomendamos seguir este guia antes de tentar usar qualquer um dos tutoriais mencionados acima.
Nesta seção, vamos criar um resolvedor, adicionar um resolvedor para mutações e usar as configurações avançadas.
## Criar seu primeiro resolvedor
Seguindo os exemplos das seções anteriores, a primeira etapa é criar um resolvedor para seu tipo de `Query`.
------
#### [ Console ]
1. Faça login no Console de gerenciamento da AWS e abra o [AppSync console](https://console.aws.amazon.com/appsync/).
1. No **APIs painel**, escolha sua API GraphQL.
1. Na **barra lateral**, escolha **Esquema**.
1. No lado direito da página, há uma janela chamada **Resolvedores**. Essa caixa contém uma lista dos tipos e campos conforme definido na janela **Esquema** no lado esquerdo da página. Você pode anexar resolvedores aos campos. Por exemplo, no tipo de **consulta**, escolha **Anexar** ao lado do campo `getTodos`.
1. Na página **Criar resolvedor**, escolha a fonte de dados que você criou no guia [Anexar uma fonte de dados](https://docs.aws.amazon.com/appsync/latest/devguide/attaching-a-data-source.html). Na janela **Configurar modelos de mapeamento**, você pode escolher os modelos genéricos de mapeamento de solicitação e resposta na lista suspensa à direita ou escrever suas próprias opções.
**nota**
A combinação de um modelo de mapeamento de solicitação com um modelo de mapeamento de resposta é chamado de resolvedor de unidades. Os resolvedores de unidades normalmente são destinados a realizar operações rotineiras, e recomendamos usá-los somente para operações individuais com um pequeno número de fontes de dados. Para operações mais complexas, recomendamos o uso de resolvedores de pipeline, que podem executar diversas operações com várias fontes de dados sequencialmente.
Para obter mais informações sobre a diferença entre os modelos de mapeamento de solicitação e resposta, consulte [Resolvedores de unidades](https://docs.aws.amazon.com//appsync/latest/devguide/resolver-mapping-template-reference-overview.html#unit-resolvers).
Para obter mais informações sobre o uso de resolvedores de pipeline, consulte [Resolvedores de pipeline](pipeline-resolvers.md#aws-appsync-pipeline-resolvers).
1. Para casos de uso comuns, o AWS AppSync console tem modelos integrados que você pode usar para obter itens de fontes de dados (por exemplo, todas as consultas de itens, pesquisas individuais etc.). Por exemplo, na versão simples do esquema de [Projetar seu esquema](designing-your-schema.md#aws-appsync-designing-your-schema), onde `getTodos` não tinha paginação, o modelo de mapeamento para listar os itens é o seguinte:
```
{
"version" : "2017-02-28",
"operation" : "Scan"
}
```
1. Sempre é necessário ter um modelo de mapeamento da resposta para acompanhar a solicitação. O console fornece um padrão com o seguinte valor de passagem para listas:
```
$util.toJson($ctx.result.items)
```
Neste exemplo, o objeto `context` (com o alias de `$ctx`) para listas de itens tem o formato `$context.result.items`. Se a operação do GraphQL retorna um único item, ele seria `$context.result`. O AWS AppSync oferece funções auxiliares para operações comuns, como a função `$util.toJson` listada anteriormente, para formatar respostas corretamente. Para obter uma lista completa das funções, consulte [Referência do utilitário do modelo de mapeamento do resolvedor](resolver-util-reference.md#aws-appsync-resolver-mapping-template-util-reference).
1. Escolha **Salvar resolvedor**.
------
#### [ API ]
1. Crie um objeto resolvedor chamando a API [https://docs.aws.amazon.com/appsync/latest/APIReference/API_CreateResolver.html](https://docs.aws.amazon.com/appsync/latest/APIReference/API_CreateResolver.html).
1. Você pode modificar os campos do seu resolvedor chamando a API [https://docs.aws.amazon.com/appsync/latest/APIReference/API_UpdateResolver.html](https://docs.aws.amazon.com/appsync/latest/APIReference/API_UpdateResolver.html).
------
#### [ CLI ]
1. Crie um resolvedor executando o comando [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/create-resolver.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/create-resolver.html).
Você precisará digitar 6 parâmetros para este comando específico:
1. O `api-id` da sua API.
1. O `type-name` do tipo que você deseja modificar em seu esquema. No exemplo do console, tínhamos `Query`.
1. O `field-name` do tipo que você deseja modificar em seu tipo. No exemplo do console, tínhamos `getTodos`.
1. A fonte de dados `data-source-name` que você criou no guia [Anexar uma fonte de dados](https://docs.aws.amazon.com/appsync/latest/devguide/attaching-a-data-source.html).
1. O `request-mapping-template`, que é o corpo da solicitação. No exemplo do console, tínhamos:
```
{
"version" : "2017-02-28",
"operation" : "Scan"
}
```
1. O `response-mapping-template`, que é o corpo da resposta. No exemplo do console, tínhamos:
```
$util.toJson($ctx.result.items)
```
Veja um exemplo de comando:
```
aws appsync create-resolver --api-id abcdefghijklmnopqrstuvwxyz --type-name Query --field-name getTodos --data-source-name TodoTable --request-mapping-template "{ "version" : "2017-02-28", "operation" : "Scan", }" --response-mapping-template ""$"util.toJson("$"ctx.result.items)"
```
Uma saída será retornada na CLI. Veja um exemplo abaixo:
```
{
"resolver": {
"kind": "UNIT",
"dataSourceName": "TodoTable",
"requestMappingTemplate": "{ version : 2017-02-28, operation : Scan, }",
"resolverArn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz/types/Query/resolvers/getTodos",
"typeName": "Query",
"fieldName": "getTodos",
"responseMappingTemplate": "$util.toJson($ctx.result.items)"
}
}
```
1. Para modificar os modelos de and/or mapeamento de campos de um resolvedor, execute o [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/update-resolver.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/update-resolver.html)comando.
Com exceção do parâmetro de `api-id`, os parâmetros usados no comando `create-resolver` serão substituídos pelos novos valores do comando `update-resolver`.
------
## Adicionar um resolvedor para mutações
A próxima etapa é criar um resolvedor para seu tipo de `Mutation`.
------
#### [ Console ]
1. Faça login no Console de gerenciamento da AWS e abra o [AppSync console](https://console.aws.amazon.com/appsync/).
1. No **APIs painel**, escolha sua API GraphQL.
1. Na **barra lateral**, escolha **Esquema**.
1. No tipo **Mutação**, escolha **Anexar** ao lado do seu campo `addTodo`.
1. Na página **Criar resolvedor**, escolha a fonte de dados que você criou no guia [Anexar uma fonte de dados](https://docs.aws.amazon.com/appsync/latest/devguide/attaching-a-data-source.html).
1. Na janela **Configurar modelos de mapeamento**, você precisará modificar o modelo de solicitação porque essa é uma mutação em que você está adicionando um novo item ao DynamoDB. Use o seguinte modelo de mapeamento da solicitação:
```
{
"version" : "2017-02-28",
"operation" : "PutItem",
"key" : {
"id" : $util.dynamodb.toDynamoDBJson($ctx.args.id)
},
"attributeValues" : $util.dynamodb.toMapValuesJson($ctx.args)
}
```
1. AWS AppSync converte automaticamente os argumentos definidos no `addTodo` campo do seu esquema do GraphQL em operações do DynamoDB. O exemplo anterior armazena registros no DynamoDB usando uma chave do `id` que é transmitida a partir do argumento da mutação como `$ctx.args.id`. Todos os outros campos transmitidos são mapeados automaticamente para atributos do DynamoDB com `$util.dynamodb.toMapValuesJson($ctx.args)`.
Para esse resolvedor, use o seguinte modelo de mapeamento da resposta:
```
$util.toJson($ctx.result)
```
AWS AppSync também suporta fluxos de trabalho de teste e depuração para edição de resolvedores. Use um objeto `context` de simulação para ver o valor transformado do modelo antes de invocar. Opcionalmente, você pode visualizar a execução de solicitação completa para uma fonte de dados de forma interativa ao executar uma consulta. Para obter mais informações, consulte [Resolvedores de teste e depuração](test-debug-resolvers.md#aws-appsync-test-debug-resolvers) e o [Monitoramento e registro em log](monitoring.md#aws-appsync-monitoring).
1. Escolha **Salvar resolvedor**.
------
#### [ API ]
Você também pode fazer isso APIs utilizando os comandos na seção [Criar seu primeiro resolvedor](https://docs.aws.amazon.com/appsync/latest/devguide/configuring-resolvers.html#create-your-first-resolver) e os detalhes dos parâmetros desta seção.
------
#### [ CLI ]
Além disso, é possível fazer isso no CLI utilizando os comandos na seção [Criar seu primeiro resolvedor](https://docs.aws.amazon.com/appsync/latest/devguide/configuring-resolvers.html#create-your-first-resolver) e os detalhes dos parâmetros desta seção.
------
Neste momento, se não estiver usando os resolvedores avançados você pode começar a usar a API GraphQL conforme descrito em [Uso da API](using-your-api.md#aws-appsync-using-your-api).
## Resolvedores avançados
Se estiver seguindo a seção Avançado e estiver criando um esquema de exemplo em [Projetar seu esquema](designing-your-schema.md#aws-appsync-designing-your-schema) para fazer uma verificação paginada, use o seguinte modelo de solicitação para o campo `getTodos`:
```
{
"version" : "2017-02-28",
"operation" : "Scan",
"limit": $util.defaultIfNull(${ctx.args.limit}, 20),
"nextToken": $util.toJson($util.defaultIfNullOrBlank($ctx.args.nextToken, null))
}
```
Para esse caso de uso de paginação, o mapeamento da resposta é mais do que apenas uma passagem porque ele deve conter o *cursor* (para que o cliente saiba em qual página começar) e o conjunto de resultados. O modelo de mapeamento é conforme mostrado a seguir:
```
{
"todos": $util.toJson($context.result.items),
"nextToken": $util.toJson($context.result.nextToken)
}
```
Os campos no modelo de mapeamento da resposta anterior devem corresponder aos campos definidos no tipo `TodoConnection`.
Se houver relações em que há uma tabela de `Comments`, e você estiver resolvendo o campo dos comentários no tipo `Todo` (que retorna um tipo de `[Comment]`), use um modelo de mapeamento que executa uma consulta mediante a segunda tabela. Para fazer isso, é necessário já ter criado uma fonte de dados para a tabela `Comments`, conforme descrito em Associar uma fonte de dados.
**nota**
Estamos usando uma operação de consulta mediante uma segunda tabela somente para fins ilustrativos. Você pode usar outra operação mediante o DynamoDB no lugar. Além disso, você pode extrair os dados de outra fonte de dados, como AWS Lambda o Amazon OpenSearch Service, porque a relação é controlada pelo esquema do GraphQL.
------
#### [ Console ]
1. Faça login no Console de gerenciamento da AWS e abra o [AppSync console](https://console.aws.amazon.com/appsync/).
1. No **APIs painel**, escolha sua API GraphQL.
1. Na **barra lateral**, escolha **Esquema**.
1. No tipo **Tarefas**, escolha **Anexar** ao lado do seu campo `comments`.
1. Na página **Criar resolvedor**, escolha sua fonte de dados da tabela de **comentários**. O nome padrão da tabela **Comentários** nos guias de início rápido é `AppSyncCommentTable`, mas pode variar dependendo do nome que você atribuiu a ela.
1. Adicione o seguinte trecho ao seu modelo de mapeamento da solicitação:
```
{
"version": "2017-02-28",
"operation": "Query",
"index": "todoid-index",
"query": {
"expression": "todoid = :todoid",
"expressionValues": {
":todoid": {
"S": $util.toJson($context.source.id)
}
}
}
}
```
1. O `context.source` faz referência ao objeto pai do campo atual que está sendo resolvido. Neste exemplo, `source.id` se refere ao objeto `Todo` individual que é, então, usado para a expressão de consulta.
Você pode usar o modelo de mapeamento da resposta de passagem da seguinte forma:
```
$util.toJson($ctx.result.items)
```
1. Escolha **Salvar resolvedor**.
1. Por fim, de volta à página **Esquema** no console, anexe um resolvedor ao campo `addComment` e especifique a fonte de dados da tabela `Comments`. Neste caso, o modelo de mapeamento da solicitação é um simples `PutItem` com o `todoid` específico que está comentado como um argumento, mas use o utilitário `$utils.autoId()` para criar uma chave de classificação única para o comentário da seguinte forma:
```
{
"version": "2017-02-28",
"operation": "PutItem",
"key": {
"todoid": { "S": $util.toJson($context.arguments.todoid) },
"commentid": { "S": "$util.autoId()" }
},
"attributeValues" : $util.dynamodb.toMapValuesJson($ctx.args)
}
```
Use um modelo da resposta de passagem da seguinte forma:
```
$util.toJson($ctx.result)
```
------
#### [ API ]
Você também pode fazer isso APIs utilizando os comandos na seção [Criar seu primeiro resolvedor](https://docs.aws.amazon.com/appsync/latest/devguide/configuring-resolvers.html#create-your-first-resolver) e os detalhes dos parâmetros desta seção.
------
#### [ CLI ]
Além disso, é possível fazer isso no CLI utilizando os comandos na seção [Criar seu primeiro resolvedor](https://docs.aws.amazon.com/appsync/latest/devguide/configuring-resolvers.html#create-your-first-resolver) e os detalhes dos parâmetros desta seção.
------
# Como desabilitar modelos de mapeamento VTL com resolvedores diretos do Lambda (VTL)
**nota**
Agora, oferecemos suporte principalmente ao runtime do APPSYNC\$1JS e sua documentação. Considere usar o runtime do APPSYNC\$1JS e seus guias disponíveis [aqui](https://docs.aws.amazon.com/appsync/latest/devguide/configuring-resolvers-js.html).
Com resolvedores Lambda diretos, você pode contornar o uso de modelos de mapeamento VTL ao usar fontes de dados. AWS Lambda AWS AppSync pode fornecer uma carga padrão para sua função Lambda, bem como uma tradução padrão da resposta de uma função Lambda para um tipo GraphQL. Você pode optar por fornecer um modelo de solicitação, um modelo de resposta ou nenhum dos dois e AWS AppSync tratará isso adequadamente.
Para saber mais sobre a carga útil padrão da solicitação e a tradução de respostas que AWS AppSync fornece, consulte a referência do resolvedor do [Direct Lambda](resolver-mapping-template-reference-lambda.md#direct-lambda-resolvers). Para obter mais informações sobre como configurar uma fonte de AWS Lambda dados e configurar uma política de confiança do IAM, consulte [Anexar uma fonte de dados](attaching-a-data-source.md).
## Configurar resolvedores diretos do Lambda
As seções a seguir mostrarão como anexar fontes de dados do Lambda e adicionar resolvedores do Lambda aos seus campos.
### Adicionar uma fonte de dados do Lambda
Antes de ativar os resolvedores diretos do Lambda, você deve adicionar uma fonte de dados do Lambda.
------
#### [ Console ]
1. Faça login no Console de gerenciamento da AWS e abra o [AppSyncconsole](https://console.aws.amazon.com/appsync/).
1. No **APIs painel**, escolha sua API GraphQL.
1. Na **barra lateral**, selecione **Fontes de dados**.
1. Escolha **Criar fonte de dados**.
1. Para **Nome da fonte de dados**, digite um nome para sua fonte de dados, como **myFunction**.
1. Para **Tipo de fonte de dados**, escolha a opção **Função AWS Lambda **.
1. Para **Região**, escolha a região apropriada.
1. Para **Função ARN**, escolha a função do Lambda na lista suspensa. Você pode pesquisar o nome da função ou inserir manualmente o ARN da função que deseja usar.
1. Crie um perfil do IAM (recomendado) ou escolha uma função existente que tenha permissão `lambda:invokeFunction` do IAM. Os perfis existentes precisam de uma política de confiança, conforme explicado na seção [Anexar uma fonte de dados](attaching-a-data-source.md).
Veja a seguir um exemplo de política do IAM que tem as permissões necessárias para executar as operações no recurso:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [ "lambda:invokeFunction" ],
"Resource": [
"arn:aws:lambda:us-west-2:123456789012:function:myFunction",
"arn:aws:lambda:us-west-2:123456789012:function:myFunction:*"
]
}
]
}
```
------
1. Selecione o botão **Criar**.
------
#### [ CLI ]
1. Crie um objeto da fonte de dados executando o comando [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/create-data-source.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/create-data-source.html).
Você precisará digitar 4 parâmetros para esse comando específico:
1. O `api-id` da sua API.
1. O `name` da sua fonte de dados. No exemplo do console, esse é o **Nome da fonte de dados**.
1. O `type` da fonte de dados. No exemplo do console, isso é **função AWS Lambda **.
1. O `lambda-config`, que é o **ARN da função** no exemplo do console.
**nota**
Existem outros parâmetros, como `Region`, que devem ser configurados, mas geralmente usam como padrão os valores de configuração da CLI.
Veja um exemplo de comando:
```
aws appsync create-data-source --api-id abcdefghijklmnopqrstuvwxyz --name myFunction --type AWS_LAMBDA --lambda-config lambdaFunctionArn=arn:aws:lambda:us-west-2:102847592837:function:appsync-lambda-example
```
Uma saída será retornada na CLI. Veja um exemplo abaixo:
```
{
"dataSource": {
"dataSourceArn": "arn:aws:appsync:us-west-2:102847592837:apis/abcdefghijklmnopqrstuvwxyz/datasources/myFunction",
"type": "AWS_LAMBDA",
"name": "myFunction",
"lambdaConfig": {
"lambdaFunctionArn": "arn:aws:lambda:us-west-2:102847592837:function:appsync-lambda-example"
}
}
}
```
1. Para modificar os atributos de uma fonte de dados, execute o comando [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/update-data-source.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/update-data-source.html).
Com exceção do `api-id` parâmetro, os parâmetros usados no comando `create-data-source` serão substituídos pelos novos valores do comando `update-data-source`.
------
### Ativar resolvedores diretos do Lambda
Depois de criar uma fonte de dados Lambda e configurar a função apropriada do IAM AWS AppSync para permitir a invocação da função, você pode vinculá-la a uma função de resolução ou pipeline.
------
#### [ Console ]
1. Faça login no Console de gerenciamento da AWS e abra o [AppSyncconsole](https://console.aws.amazon.com/appsync/).
1. No **APIs painel**, escolha sua API GraphQL.
1. Na **barra lateral**, escolha **Esquema**.
1. Na janela **Resolvedores**, selecione um campo ou operação e selecione o botão **Anexar**.
1. Na página **Criar novo resolvedor**, escolha a função do Lambda na lista suspensa.
1. Para aproveitar os resolvedores diretos do Lambda, confirme se os modelos de mapeamento de solicitação e resposta estão desativados na seção **Configurar modelos de mapeamento**.
1. Selecione o botão **Salvar resolvedor**.
------
#### [ CLI ]
+ Crie um resolvedor executando o comando [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/create-resolver.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/create-resolver.html).
Você precisará digitar 6 parâmetros para este comando específico:
1. O `api-id` da sua API.
1. O `type-name` do tipo no seu esquema.
1. O `field-name` do campo no seu esquema.
1. O `data-source-name`, ou o nome da sua função do Lambda.
1. O `request-mapping-template`, que é o corpo da solicitação. No exemplo do console, desabilitamos o seguinte:
```
" "
```
1. O `response-mapping-template`, que é o corpo da resposta. No exemplo do console, o seguinte também foi desabilitado:
```
" "
```
Veja um exemplo de comando:
```
aws appsync create-resolver --api-id abcdefghijklmnopqrstuvwxyz --type-name Subscription --field-name onCreateTodo --data-source-name LambdaTest --request-mapping-template " " --response-mapping-template " "
```
Uma saída será retornada na CLI. Veja um exemplo abaixo:
```
{
"resolver": {
"resolverArn": "arn:aws:appsync:us-west-2:102847592837:apis/abcdefghijklmnopqrstuvwxyz/types/Subscription/resolvers/onCreateTodo",
"typeName": "Subscription",
"kind": "UNIT",
"fieldName": "onCreateTodo",
"dataSourceName": "LambdaTest"
}
}
```
------
Quando você desativa seus modelos de mapeamento, há vários comportamentos adicionais que ocorrerão no AWS AppSync:
+ Ao desativar um modelo de mapeamento, você está sinalizando AWS AppSync que aceita as traduções de dados padrão especificadas na referência do resolvedor do Direct [Lambda](resolver-mapping-template-reference-lambda.md#direct-lambda-resolvers).
+ Ao desativar o modelo de mapeamento de solicitações, sua fonte de dados do Lambda receberá uma payload que consiste em todo o objeto [Contexto](resolver-context-reference.md).
+ Ao desativar o modelo de mapeamento de resposta, o resultado da sua invocação do Lambda será traduzido de acordo com a versão do modelo de mapeamento da solicitação ou se o modelo de mapeamento da solicitação também estiver desativado.
# Testando e depurando resolvedores em (VTL) AWS AppSync
**nota**
Agora, oferecemos suporte principalmente ao runtime do APPSYNC\$1JS e sua documentação. Considere usar o runtime do APPSYNC\$1JS e seus guias disponíveis [aqui](https://docs.aws.amazon.com/appsync/latest/devguide/configuring-resolvers-js.html).
AWS AppSync executa resolvedores em um campo GraphQL em relação a uma fonte de dados. Conforme descrito na [Visão geral do modelo de mapeamento do resolvedor](resolver-mapping-template-reference-overview.md#aws-appsync-resolver-mapping-template-reference-overview), os resolvedores se comunicam com as fontes de dados usando uma linguagem de modelos. Isso permite personalizar o comportamento e aplicar lógica e condições antes e depois de se comunicar com a fonte de dados. Para obter um guia de programação introdutório no estilo tutorial para programar resolvedores, consulte o [Guia de programação do modelo de mapeamento do resolvedor](resolver-mapping-template-reference-programming-guide.md#aws-appsync-resolver-mapping-template-reference-programming-guide).
Para ajudar os desenvolvedores a escrever, testar e depurar esses resolvedores, o AWS AppSync console também fornece ferramentas para criar uma solicitação e uma resposta do GraphQL com dados simulados até o resolvedor de campo individual. Além disso, você pode realizar consultas, mutações e assinaturas no AWS AppSync console e ver um stream de log detalhado da Amazon CloudWatch de toda a solicitação. Isso inclui os resultados de uma fonte de dados.
## Testes com dados simulados
Quando um resolvedor do GraphQL é invocado, ele contém um objeto `context` que contém informações sobre a solicitação. Isso inclui argumentos de um cliente, informações de identidade e dados do campo pai do GraphQL. Ele também contém os resultados da fonte de dados, que podem ser usados no modelo da resposta. Para obter mais informações sobre essa estrutura e os utilitários auxiliares disponíveis para o uso ao programar, consulte a [Referência de contexto do modelo de mapeamento do resolvedor](resolver-context-reference.md#aws-appsync-resolver-mapping-template-context-reference).
Ao escrever ou editar um resolvedor, você pode passar um objeto de *contexto simulado* ou de *teste* para o editor do console. Isso permite ver como os modelos de solicitação e resposta avaliam, sem realmente executar segundo uma fonte de dados. Por exemplo, você pode enviar um argumento `firstname: Shaggy` de teste e ver como ele avalia ao usar `$ctx.args.firstname` no código do modelo. Você também pode testar a avaliação de qualquer utilitário auxiliar, como `$util.autoId()` ou `util.time.nowISO8601()`.
### Teste de resolvedores
Este exemplo usará o AWS AppSync console para testar os resolvedores.
1. Faça login no Console de gerenciamento da AWS e abra o [AppSyncconsole](https://console.aws.amazon.com/appsync/).
1. No **APIs painel**, escolha sua API GraphQL.
1. Na **barra lateral**, escolha **Esquema**.
1. Se ainda não tiver feito isso, no tipo e ao lado do campo, escolha **Anexar** para adicionar seu resolvedor.
Para obter mais informações sobre como construir um resolvedor completo, consulte [Configuração de resolvedores](https://docs.aws.amazon.com/appsync/latest/devguide/configuring-resolvers.html).
Caso contrário, selecione o resolvedor que já está no campo.
1. Na parte superior da página **Editar resolvedor**, escolha **Selecionar contexto de teste** e escolha **Criar novo contexto**.
1. Selecione um objeto de contexto de amostra ou preencha o JSON manualmente na janela **Contexto de execução**.
1. Insira um **Nome de contexto de texto**.
1. Clique no botão **Salvar**.
1. Na parte superior da página **Editar resolvedor**, escolha **Executar teste**.
Como exemplo mais prático, digamos que você tenha um aplicativo que armazena um tipo do GraphQL `Dog` que usa a geração automática de ID para objetos e os armazena no Amazon DynamoDB. Você também deseja gravar alguns valores dos argumentos de uma mutação do GraphQL e permitir que apenas usuários específicos vejam uma resposta. Veja a seguir a possível aparência do esquema:
```
type Dog {
breed: String
color: String
}
type Mutation {
addDog(firstname: String, age: Int): Dog
}
```
Ao adicionar um resolvedor para a mutação `addDog`, preencha um objeto de contexto como o exemplo a seguir. Ele tem argumentos do cliente de `name` e `age`, e um `username` preenchido no 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"
}
}
```
Você pode testar isso usando os seguintes modelos de mapeamento da solicitação e da resposta:
**Modelo de solicitação**
```
{
"version" : "2017-02-28",
"operation" : "PutItem",
"key" : {
"id" : { "S" : "$util.autoId()" }
},
"attributeValues" : $util.dynamodb.toMapValuesJson($ctx.args)
}
```
**Modelo da resposta**
```
#if ($context.identity.username == "Nadia")
$util.toJson($ctx.result)
#else
$util.unauthorized()
#end
```
O modelo avaliado tem os dados do objeto de contexto de teste e o valor gerado de `$util.autoId()`. Além disso, se você alterasse o `username` para um valor diferente de `Nadia`, os resultados não seriam retornados pois a verificação de autorização falharia. Para obter mais informações sobre o controle de acesso refinado, consulte [Casos de uso de autorização](security-authorization-use-cases.md#aws-appsync-security-authorization-use-cases).
### Testando modelos de mapeamento com AWS AppSync APIs
Você pode usar o comando da API `EvaluateMappingTemplate` para testar remotamente seus modelos de mapeamento com dados simulados. Para começar a usar o comando, certifique-se de ter adicionado a permissão `appsync:evaluateMappingTemplate` à sua política. Por exemplo:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "appsync:evaluateMappingTemplate",
"Resource": "arn:aws:appsync:us-east-1:111122223333:*"
}
]
}
```
------
Você pode aproveitar o comando usando o [AWS CLI](https://aws.amazon.com/cli/)ou [AWS SDKs](https://aws.amazon.com/tools/). Por exemplo, veja o `Dog` esquema e seus modelos de request/response mapeamento da seção anterior. Usando a CLI em sua estação local, salve o modelo de solicitação em um arquivo chamado `request.vtl` e salve o objeto `context` em um arquivo chamado `context.json`. No seu shell, execute o seguinte comando:
```
aws appsync evaluate-mapping-template --template file://request.vtl --context file://context.json
```
O comando retorna a seguinte resposta:
```
{
"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"
}
```
O `evaluationResult` contém os resultados do teste do modelo fornecido com o `context` fornecido. Você também pode testar seus modelos usando AWS SDKs o. Aqui está um exemplo usando o AWS SDK 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))
```
Usando o SDK, você pode incorporar facilmente testes do seu conjunto de testes favorito para validar o comportamento do seu modelo. Recomendamos a criação de testes usando o [Estrutura de trabalho de teste Jest](https://jestjs.io/), mas qualquer conjunto de testes funciona. O trecho a seguir mostra uma execução de validação hipotética. Esperamos que a resposta de avaliação seja um JSON válido, por isso, usamos `JSON.parse` para recuperar o JSON da resposta da string:
```
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)
})
```
Isso produz o seguinte 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
```
## Depuração de uma consulta atual
Não há substituto para um end-to-end teste e um registro para depurar um aplicativo de produção. AWS AppSync permite que você registre erros e detalhes completos da solicitação usando a Amazon CloudWatch. Além disso, você pode usar o AWS AppSync console para testar consultas, mutações e assinaturas do GraphQL e transmitir ao vivo os dados de log de cada solicitação de volta ao editor de consultas para depuração em tempo real. Para assinaturas, os logs exibem as informações do tempo de conexão.
Para fazer isso, você precisa ter CloudWatch os registros da Amazon habilitados com antecedência, conforme descrito em [Monitoramento e registro](monitoring.md#aws-appsync-monitoring). Em seguida, no AWS AppSync console, escolha a guia **Consultas** e insira uma consulta GraphQL válida. Na seção inferior direita, clique e arraste a janela **Registros em log** para abrir a visualização de registros. No topo da página, escolha o ícone de seta de reprodução para executar a consulta do GraphQL. Em alguns instantes, os logs completos da solicitação e da resposta para a operação serão transmitidos para essa seção e você poderá visualizá-los no console.
# Configurando e usando resolvedores de pipeline em AWS AppSync (VTL)
**nota**
Agora, oferecemos suporte principalmente ao runtime do APPSYNC\$1JS e sua documentação. Considere usar o runtime do APPSYNC\$1JS e seus guias disponíveis [aqui](https://docs.aws.amazon.com/appsync/latest/devguide/configuring-resolvers-js.html).
AWS AppSync executa resolvedores em um campo GraphQL. Em alguns casos, os aplicativos requerem a execução de várias operações para resolver um único campo do GraphQL. Com os resolvedores de pipeline, os desenvolvedores agora podem elaborar operações chamadas Funções e executá-las em sequência. Os resolvedores de pipeline são úteis para aplicativos que, por exemplo, exigem a execução de uma verificação de autorização antes de obter dados para um campo.
Um resolvedor de pipeline é composto de um modelo de mapeamento **Anterior**, um modelo de mapeamento **Posterior** e uma lista de Funções. Cada função possui um modelo de mapeamento de **solicitação** e **resposta** que é executado mediante 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. Consulte [Visão geral do modelo de mapeamento do resolvedor](resolver-mapping-template-reference-overview.md#aws-appsync-resolver-mapping-template-reference-overview) para obter mais informações.
## Etapa 1: criar um resolvedor de pipeline
No AWS AppSync console, acesse a página **Esquema**.
Salve o seguinte esquema:
```
schema {
query: Query
mutation: Mutation
}
type Mutation {
signUp(input: Signup): User
}
type Query {
getUser(id: ID!): User
}
input Signup {
username: String!
email: String!
}
type User {
id: ID!
username: String
email: AWSEmail
}
```
Vamos conectar um resolvedor de pipeline ao campo **signUp** no tipo **Mutação**. No tipo **Mutação** no lado direito, escolha **Anexar** ao lado do campo de mutação `signUp`. Na página de criação do resolvedor, clique em **Ações** e depois em **Atualizar runtime**. Escolha `Pipeline Resolver` e `VTL` e selecione **Atualizar**. Agora, a página deve mostrar 3 seções, uma área de texto **Modelo de mapeamento anterior**, uma seção **Funções** e uma área de texto **Modelo de mapeamento posterior**.
Nosso resolvedor de pipeline cadastra um usuário validando primeiro a entrada do endereço de e-mail e salvando o usuário no sistema. Vamos encapsular a validação de e-mail dentro de uma função **validateEmail** e salvar o usuário dentro de uma função **saveUser**. A função **validateEmail** é executada primeiro e, se o e-mail for válido, a função **saveUser** será executada.
O fluxo de execução será da seguinte forma:
1. Modelo de mapeamento de solicitação do resolvedor Mutation.signUp
1. Função validateEmail
1. Função saveUser
1. Modelo de mapeamento de resposta do resolvedor Mutation.signUp
Provavelmente reutilizaremos a função **validateEmail** em outros resolvedores em nossa API. Sendo assim, queremos evitar o acesso a `$ctx.args`, já que eles mudarão de um campo do GraphQL para outro. Em vez disso, podemos usar o `$ctx.stash` para armazenar o atributo de e-mail a partir do argumento de campo de entrada `signUp(input: Signup)`.
Modelo de mapeamento **ANTERIOR**:
```
## store email input field into a generic email key
$util.qr($ctx.stash.put("email", $ctx.args.input.email))
{}
```
O console fornece um modelo de mapeamento **POSTERIOR** de passagem padrão que usaremos:
```
$util.toJson($ctx.result)
```
Escolha **Criar** ou **Salvar** para atualizar o resolvedor.
## Etapa 2: criar uma função
Na página do resolvedor de pipeline, na seção **Funções**, clique em **Adicionar função** e em **Criar função**. Também é possível criar funções sem passar pela página do resolvedor; para fazer isso, no AWS AppSync console, acesse a página **Funções**. Selecione o botão **Criar função**. Vamos criar uma função que verifique se um e-mail é válido e proveniente de um domínio específico. Se o e-mail não for válido, a função gerará um erro. Caso contrário, ele encaminha qualquer entrada fornecida.
Na página da nova função, escolha **Ações** e, em seguida, **Atualizar runtime**. Escolha `VTL` e, em seguida, **Atualizar**. Crie uma fonte de dados do tipo **NONE**. Escolha a fonte de dados na lista **Nome da fonte de dados**. Em **nome da função**, insira `validateEmail`. Na área **código da função**, substitua tudo por este trecho:
```
#set($valid = $util.matches("^[a-zA-Z0-9_.+-]+@(?:(?:[a-zA-Z0-9-]+\.)?[a-zA-Z]+\.)?(myvaliddomain)\.com", $ctx.stash.email))
#if (!$valid)
$util.error("$ctx.stash.email is not a valid email.")
#end
{
"payload": { "email": $util.toJson(${ctx.stash.email}) }
}
```
Cole isso no modelo de mapeamento de resposta:
```
$util.toJson($ctx.result)
```
Verifique suas escolhas e selecione **Criar**. Acabamos de criar nossa função **validateEmail**. Repita essas etapas para criar a função **saveUser** com o código a seguir (a fim de simplificar, usamos a fonte de dados **NONE** e fingimos que o usuário foi salvo no sistema após a execução da função):
Modelo de mapeamento de solicitação:
```
## $ctx.prev.result contains the signup input values. We could have also
## used $ctx.args.input.
{
"payload": $util.toJson($ctx.prev.result)
}
```
Modelo de mapeamento da resposta:
```
## an id is required so let's add a unique random identifier to the output
$util.qr($ctx.result.put("id", $util.autoId()))
$util.toJson($ctx.result)
```
Acabamos de criar nossa função **saveUser**.
## Etapa 3: adicionar uma função a um resolvedor de pipeline
Nossas funções devem ter sido adicionadas automaticamente ao resolvedor de pipeline que acabamos de criar. Se não foi esse o caso ou se você criou as funções por meio da página **Funções**, é possível clicar em **Adicionar função** na página de resolvedor para anexá-las. Adicione as funções **validateEmail** e **saveUser** ao resolvedor. A função **validateEmail** deve ser colocada antes da função **saveUser**. À medida que você adiciona mais funções, pode usar as setas **para cima** e **para baixo** para reorganizar a ordem de execução das funções. Revise suas alterações e escolha **Salvar**.
## Etapa 4: executar uma consulta
No AWS AppSync console, acesse a página **Consultas.** No explorador, verifique se você está usando a mutação. Se não estiver, escolha `Mutation` na lista suspensa e escolha `+`. Digite a consulta a seguir:
```
mutation {
signUp(input: {
email: "nadia@myvaliddomain.com"
username: "nadia"
}) {
id
email
}
}
```
Ela deve retornar algo semelhante a:
```
{
"data": {
"signUp": {
"id": "256b6cc2-4694-46f4-a55e-8cb14cc5d7fc",
"email": "nadia@myvaliddomain.com"
}
}
}
```
Cadastramos com sucesso nosso usuário e validamos o e-mail de entrada usando um resolvedor de pipeline. Para seguir um tutorial mais completo com foco em resolvedores de pipeline, você pode acessar [Tutorial: Resolvedores de pipeline](tutorial-pipeline-resolvers.md#aws-appsync-tutorial-pipeline-resolvers)
# Usando uma AWS AppSync API com o AWS CDK
**dica**
[Antes de usar o CDK, recomendamos revisar a [documentação oficial](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html) do CDK junto com AWS AppSync a referência do CDK.](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_appsync-readme.html)
Também recomendamos garantir que suas instalações de [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) e [NPM](https://docs.npmjs.com/) estejam funcionando em seu sistema.
Nesta seção, criaremos uma aplicação do CDK simples que pode adicionar e buscar itens de uma tabela do DynamoDB. Esse é um exemplo de início rápido usando parte do código das seções [Projetando seu esquema](https://docs.aws.amazon.com/appsync/latest/devguide/designing-your-schema.html), [Anexando uma fonte de dados](https://docs.aws.amazon.com/appsync/latest/devguide/attaching-a-data-source.html) e [Configurando resolvers](https://docs.aws.amazon.com/appsync/latest/devguide/configuring-resolvers-js.html) (). JavaScript
## Configuração de um projeto de CDK
**Atenção**
Essas etapas podem não ser totalmente precisas, dependendo do seu ambiente. Presumimos que seu sistema tenha os utilitários necessários instalados, uma forma de interagir com AWS os serviços e as configurações adequadas.
A primeira etapa é instalar o AWS CDK. Na sua CLI, você pode inserir o seguinte comando:
```
npm install -g aws-cdk
```
Depois, você precisa criar um diretório de projeto e navegar até ele. Um exemplo de conjunto de comandos para criar e navegar até um diretório é:
```
mkdir example-cdk-app
cd example-cdk-app
```
Em seguida, você precisa criar um aplicativo. Nosso serviço usa principalmente TypeScript. No diretório do seu projeto, digite o seguinte comando:
```
cdk init app --language typescript
```
Ao fazer isso, um aplicativo CDK junto com seus arquivos de inicialização será instalado:
![\[Terminal output showing Git repository initialization and npm install completion.\]](http://docs.aws.amazon.com/pt_br/appsync/latest/devguide/images/cdk-init-app-example.png)
A estrutura do seu projeto pode ser semelhante a esta:
![\[Project directory structure showing folders and files for an example CDK app.\]](http://docs.aws.amazon.com/pt_br/appsync/latest/devguide/images/cdk-init-directories.png)
Você notará que temos vários diretórios importantes:
+ `bin`: o arquivo bin inicial criará o aplicativo. Não abordaremos esse tema neste guia.
+ `lib`: o diretório lib contém seus arquivos de pilha. Você pode pensar nos arquivos de pilha como unidades individuais de execução. As estruturas estarão dentro de nossos arquivos de pilha. Basicamente, esses são recursos para um serviço que será ativado CloudFormation quando o aplicativo for implantado. É aqui que a maior parte da nossa codificação acontecerá.
+ `node_modules`: esse diretório é criado pelo NPM e contém todas as dependências de pacotes que você instalou usando o comando do `npm`.
Nosso arquivo de pilha inicial pode conter algo assim:
```
import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
// import * as sqs from 'aws-cdk-lib/aws-sqs';
export class ExampleCdkAppStack extends cdk.Stack {
constructor(scope: Construct, id: string, props?: cdk.StackProps) {
super(scope, id, props);
// The code that defines your stack goes here
// example resource
// const queue = new sqs.Queue(this, 'ExampleCdkAppQueue', {
// visibilityTimeout: cdk.Duration.seconds(300)
// });
}
}
```
Esse é o código clichê para criar uma pilha em nosso aplicativo. A maior parte do nosso código neste exemplo estará dentro do escopo dessa classe.
Para verificar se seu arquivo de pilha está no aplicativo, no diretório do seu aplicativo, execute o seguinte comando no terminal:
```
cdk ls
```
Uma lista de suas pilhas deve aparecer. Caso contrário, talvez seja necessário executar as etapas novamente ou verificar a documentação oficial para obter ajuda.
Se quiser criar suas alterações de código antes da implantação, você sempre pode executar o seguinte comando no terminal:
```
npm run build
```
E para ver as mudanças antes da implantação:
```
cdk diff
```
Antes de adicionarmos nosso código ao arquivo de pilha, vamos realizar um bootstrap. O bootstrapping nos permite provisionar recursos para o CDK antes da implantação do aplicativo. Mais informações sobre esse processo podem ser encontradas [aqui](https://docs.aws.amazon.com/cdk/v2/guide/bootstrapping.html). Para criar um bootstrap, o comando é:
```
cdk bootstrap aws://ACCOUNT-NUMBER/REGION
```
**dica**
Essa etapa exige várias permissões do IAM em sua conta. Seu bootstrap será negado se você não as tiver. Se isso acontecer, talvez seja necessário excluir recursos incompletos causados pelo bootstrap, como o bucket S3 que ele gera.
O bootstrap criará vários recursos. A mensagem final terá a aparência a seguir:
![\[Terminal output showing successful bootstrapping of an AWS environment.\]](http://docs.aws.amazon.com/pt_br/appsync/latest/devguide/images/cdk-init-bootstrap-final.png)
Como isso é feito uma vez por conta por região, você não precisará fazer com frequência. Os principais recursos do bootstrap são a CloudFormation pilha e o bucket Amazon S3.
O bucket do Amazon S3 é usado para armazenar arquivos e perfis do IAM que concedem as permissões necessárias para realizar implantações. Os recursos necessários são definidos em uma CloudFormation pilha, chamada pilha de bootstrap, que geralmente é nomeada. `CDKToolkit` Como qualquer CloudFormation pilha, ela aparece no CloudFormation console depois de implantada:
![\[CDKToolkit stack with CREATE_COMPLETE status in CloudFormation console.\]](http://docs.aws.amazon.com/pt_br/appsync/latest/devguide/images/cdk-init-bootstrap-cfn-console.png)
Isso também se aplica ao bucket:
![\[S3 bucket details showing name, region, access settings, and creation date.\]](http://docs.aws.amazon.com/pt_br/appsync/latest/devguide/images/cdk-init-bootstrap-bucket-console.png)
Para importar os serviços que precisamos em nosso arquivo de pilha, podemos usar o seguinte comando:
```
npm install aws-cdk-lib # V2 command
```
**dica**
Se você estiver tendo problemas com a V2, poderá instalar as bibliotecas individuais usando os comandos da V1:
```
npm install @aws-cdk/aws-appsync @aws-cdk/aws-dynamodb
```
Não recomendamos isso porque a V1 foi descontinuada.
## Implementação de um projeto de CDK - Esquema
Agora podemos começar a implementar nosso código. Primeiro, precisamos criar nosso esquema. Você pode simplesmente criar um arquivo `.graphql` no seu aplicativo:
```
mkdir schema
touch schema.graphql
```
Em nosso exemplo, incluímos um diretório de nível superior chamado `schema` que contém nosso `schema.graphql`:
![\[File structure showing a schema folder containing schema.graphql file.\]](http://docs.aws.amazon.com/pt_br/appsync/latest/devguide/images/cdk-code-schema-directory.png)
Dentro do nosso esquema, vamos incluir um exemplo simples:
```
input CreatePostInput {
title: String
content: String
}
type Post {
id: ID!
title: String
content: String
}
type Mutation {
createPost(input: CreatePostInput!): Post
}
type Query {
getPost: [Post]
}
```
De volta ao nosso arquivo de pilha, precisamos garantir que as seguintes diretivas de importação estejam definidas:
```
import * as cdk from 'aws-cdk-lib';
import * as appsync from 'aws-cdk-lib/aws-appsync';
import * as dynamodb from 'aws-cdk-lib/aws-dynamodb';
import { Construct } from 'constructs';
```
Dentro da classe, adicionaremos código para criar nossa API GraphQL e conectá-la ao nosso arquivo `schema.graphql`:
```
export class ExampleCdkAppStack extends cdk.Stack {
constructor(scope: Construct, id: string, props?: cdk.StackProps) {
super(scope, id, props);
// makes a GraphQL API
const api = new appsync.GraphqlApi(this, 'post-apis', {
name: 'api-to-process-posts',
schema: appsync.SchemaFile.fromAsset('schema/schema.graphql'),
});
}
}
```
Também adicionaremos alguns códigos para imprimir a URL, a chave de API e a região do GraphQL:
```
export class ExampleCdkAppStack extends cdk.Stack {
constructor(scope: Construct, id: string, props?: cdk.StackProps) {
super(scope, id, props);
// Makes a GraphQL API construct
const api = new appsync.GraphqlApi(this, 'post-apis', {
name: 'api-to-process-posts',
schema: appsync.SchemaFile.fromAsset('schema/schema.graphql'),
});
// Prints out URL
new cdk.CfnOutput(this, "GraphQLAPIURL", {
value: api.graphqlUrl
});
// Prints out the AppSync GraphQL API key to the terminal
new cdk.CfnOutput(this, "GraphQLAPIKey", {
value: api.apiKey || ''
});
// Prints out the stack region to the terminal
new cdk.CfnOutput(this, "Stack Region", {
value: this.region
});
}
}
```
Neste momento, usaremos a implantação do nosso aplicativo novamente:
```
cdk deploy
```
Este é o resultado:
![\[Deployment output showing ExampleCdkAppStack details, including GraphQL API URL and stack region.\]](http://docs.aws.amazon.com/pt_br/appsync/latest/devguide/images/cdk-code-deploy-schema.png)
Parece que nosso exemplo foi bem-sucedido, mas vamos verificar o AWS AppSync console apenas para confirmar:
![\[GraphQL interface showing successful API request with response data displayed.\]](http://docs.aws.amazon.com/pt_br/appsync/latest/devguide/images/cdk-code-deploy-schema-result-1.png)
Parece que nossa API foi criada. Agora, verificaremos o esquema anexado à API:
![\[GraphQL schema defining CreatePostInput, Post type, Mutation, and Query operations.\]](http://docs.aws.amazon.com/pt_br/appsync/latest/devguide/images/cdk-code-deploy-schema-result-2.png)
Como parece corresponder ao nosso código de esquema, então foi bem-sucedido. Outra forma de confirmar isso do ponto de vista dos metadados é examinar a pilha: CloudFormation
![\[CloudFormation stack showing ExampleCdkAppStack update complete and CDKToolkit creation complete.\]](http://docs.aws.amazon.com/pt_br/appsync/latest/devguide/images/cdk-code-deploy-schema-result-3.png)
Quando implantamos nosso aplicativo CDK, ele usa recursos como o bootstrap. CloudFormation Cada pilha em nosso aplicativo mapeia 1:1 com uma CloudFormation pilha. Se você voltar ao código da pilha, o nome da pilha foi retirado do nome da classe `ExampleCdkAppStack`. Você pode ver os recursos que ele criou, que também correspondem às nossas convenções de nomenclatura em nossa estrutura da API GraphQL:
![\[Expanded view of post-apis resource showing Schema, DefaultApiKey, and CDKMetadata.\]](http://docs.aws.amazon.com/pt_br/appsync/latest/devguide/images/cdk-code-deploy-schema-result-4.png)
## Implementação de um projeto CDK - Fonte de dados
Depois, precisamos adicionar nossa fonte de dados. Nosso exemplo usará uma tabela do DynamoDB. Dentro da classe de pilha, adicionaremos códigos para criar uma tabela:
```
export class ExampleCdkAppStack extends cdk.Stack {
constructor(scope: Construct, id: string, props?: cdk.StackProps) {
super(scope, id, props);
// Makes a GraphQL API construct
const api = new appsync.GraphqlApi(this, 'post-apis', {
name: 'api-to-process-posts',
schema: appsync.SchemaFile.fromAsset('schema/schema.graphql'),
});
//creates a DDB table
const add_ddb_table = new dynamodb.Table(this, 'posts-table', {
partitionKey: {
name: 'id',
type: dynamodb.AttributeType.STRING,
},
});
// Prints out URL
new cdk.CfnOutput(this, "GraphQLAPIURL", {
value: api.graphqlUrl
});
// Prints out the AppSync GraphQL API key to the terminal
new cdk.CfnOutput(this, "GraphQLAPIKey", {
value: api.apiKey || ''
});
// Prints out the stack region to the terminal
new cdk.CfnOutput(this, "Stack Region", {
value: this.region
});
}
}
```
Neste momento, vamos implantar novamente:
```
cdk deploy
```
Devemos verificar nossa nova tabela no console do DynamoDB:
![\[DynamoDB console showing ExampleCdkAppStack-poststable as Active with Provisioned capacity.\]](http://docs.aws.amazon.com/pt_br/appsync/latest/devguide/images/cdk-code-deploy-ddb-result-1.png)
O nome da nossa pilha está correto e o nome da tabela corresponde ao nosso código. Se verificarmos nossa CloudFormation pilha novamente, agora veremos a nova tabela:
![\[Expanded view of a logical ID in CloudFormation showing post-apis, posts-table, and CDKMetadata.\]](http://docs.aws.amazon.com/pt_br/appsync/latest/devguide/images/cdk-code-deploy-ddb-result-2.png)
## Implementação de um projeto de CDK - Resolvedor
Este exemplo usará dois resolvedores: um para consultar a tabela e outro para adicioná-la. Como estamos usando resolvedores de pipeline, precisaremos declarar dois resolvedores de pipeline com uma função em cada um. Na consulta, adicionaremos o seguinte código:
```
export class ExampleCdkAppStack extends cdk.Stack {
constructor(scope: Construct, id: string, props?: cdk.StackProps) {
super(scope, id, props);
// Makes a GraphQL API construct
const api = new appsync.GraphqlApi(this, 'post-apis', {
name: 'api-to-process-posts',
schema: appsync.SchemaFile.fromAsset('schema/schema.graphql'),
});
//creates a DDB table
const add_ddb_table = new dynamodb.Table(this, 'posts-table', {
partitionKey: {
name: 'id',
type: dynamodb.AttributeType.STRING,
},
});
// Creates a function for query
const add_func = new appsync.AppsyncFunction(this, 'func-get-post', {
name: 'get_posts_func_1',
api,
dataSource: api.addDynamoDbDataSource('table-for-posts', add_ddb_table),
code: appsync.Code.fromInline(`
export function request(ctx) {
return { operation: 'Scan' };
}
export function response(ctx) {
return ctx.result.items;
}
`),
runtime: appsync.FunctionRuntime.JS_1_0_0,
});
// Creates a function for mutation
const add_func_2 = new appsync.AppsyncFunction(this, 'func-add-post', {
name: 'add_posts_func_1',
api,
dataSource: api.addDynamoDbDataSource('table-for-posts-2', add_ddb_table),
code: appsync.Code.fromInline(`
export function request(ctx) {
return {
operation: 'PutItem',
key: util.dynamodb.toMapValues({id: util.autoId()}),
attributeValues: util.dynamodb.toMapValues(ctx.args.input),
};
}
export function response(ctx) {
return ctx.result;
}
`),
runtime: appsync.FunctionRuntime.JS_1_0_0,
});
// Adds a pipeline resolver with the get function
new appsync.Resolver(this, 'pipeline-resolver-get-posts', {
api,
typeName: 'Query',
fieldName: 'getPost',
code: appsync.Code.fromInline(`
export function request(ctx) {
return {};
}
export function response(ctx) {
return ctx.prev.result;
}
`),
runtime: appsync.FunctionRuntime.JS_1_0_0,
pipelineConfig: [add_func],
});
// Adds a pipeline resolver with the create function
new appsync.Resolver(this, 'pipeline-resolver-create-posts', {
api,
typeName: 'Mutation',
fieldName: 'createPost',
code: appsync.Code.fromInline(`
export function request(ctx) {
return {};
}
export function response(ctx) {
return ctx.prev.result;
}
`),
runtime: appsync.FunctionRuntime.JS_1_0_0,
pipelineConfig: [add_func_2],
});
// Prints out URL
new cdk.CfnOutput(this, "GraphQLAPIURL", {
value: api.graphqlUrl
});
// Prints out the AppSync GraphQL API key to the terminal
new cdk.CfnOutput(this, "GraphQLAPIKey", {
value: api.apiKey || ''
});
// Prints out the stack region to the terminal
new cdk.CfnOutput(this, "Stack Region", {
value: this.region
});
}
}
```
Neste trecho, adicionamos um resolvedor de pipeline chamado `pipeline-resolver-create-posts` com uma função chamada `func-add-post` anexada a ele. Esse é o código que adicionará `Posts` à tabela. O outro resolvedor de pipeline foi chamado `pipeline-resolver-get-posts` com uma função chamada `func-get-post` que recupera `Posts` adicionado à tabela.
Vamos implantar isso para adicioná-lo ao AWS AppSync serviço:
```
cdk deploy
```
Vamos verificar o AWS AppSync console para ver se eles estavam conectados à nossa API GraphQL:
![\[GraphQL API schema showing mutation and query fields with Pipeline resolvers.\]](http://docs.aws.amazon.com/pt_br/appsync/latest/devguide/images/cdk-code-deploy-resolver-result-1.png)
Parece estar correto. No código, esses dois resolvedores foram anexados à API GraphQL que criamos (indicada pelo valor de props de `api` presente nos resolvedores e nas funções). Na API GraphQL, os campos aos quais anexamos nossos resolvedores também foram especificados nas props (definidas pelas props `typename` e `fieldname` em cada resolvedor).
Vamos ver se o conteúdo dos resolvedores está correto começando com `pipeline-resolver-get-posts`:
![\[Code snippet showing request and response functions in a resolver, with an arrow pointing to them.\]](http://docs.aws.amazon.com/pt_br/appsync/latest/devguide/images/cdk-code-deploy-resolver-result-2.png)
Os manipuladores de antes e depois correspondem ao valor de nossos props `code`. Também podemos ver que uma função chamada `add_posts_func_1` corresponde ao nome da função que anexamos no resolvedor.
Vamos dar uma olhada no conteúdo do código dessa função:
![\[Function code showing request and response methods for a PutItem operation.\]](http://docs.aws.amazon.com/pt_br/appsync/latest/devguide/images/cdk-code-deploy-resolver-result-3.png)
Isso corresponde aos props `code` da função `add_posts_func_1`. Como nossa consulta foi enviada com sucesso, vamos verificar a consulta:
![\[Resolver code with request and response functions, and a get_posts_func_1 function listed below.\]](http://docs.aws.amazon.com/pt_br/appsync/latest/devguide/images/cdk-code-deploy-resolver-result-4.png)
Eles também correspondem ao código. Se observarmos `get_posts_func_1`:
![\[Code snippet showing two exported functions: request returning 'Scan' operation and response returning items.\]](http://docs.aws.amazon.com/pt_br/appsync/latest/devguide/images/cdk-code-deploy-resolver-result-5.png)
Tudo parece estar no lugar certo. Para confirmar isso do ponto de vista dos metadados, podemos verificar nossa pilha no CloudFormation novamente:
![\[List of logical IDs for AWS resources including API, table, functions, and pipelines.\]](http://docs.aws.amazon.com/pt_br/appsync/latest/devguide/images/cdk-code-deploy-resolver-result-6.png)
Agora, precisamos testar esse código executando algumas solicitações.
## Implementação de um projeto de CDK - Solicitações
Para testar nosso aplicativo no AWS AppSync console, fizemos uma consulta e uma mutação:
![\[GraphQL code snippet showing a query to get post details and a mutation to create a post.\]](http://docs.aws.amazon.com/pt_br/appsync/latest/devguide/images/cdk-code-request-1.png)
`MyMutation` contém uma operação `createPost` com os argumentos `1970-01-01T12:30:00.000Z` e `first post`. Retorna `date` e `title` que passamos, bem como o valor `id` gerado automaticamente. Executar a mutação produz o seguinte resultado:
```
{
"data": {
"createPost": {
"date": "1970-01-01T12:30:00.000Z",
"id": "4dc1c2dd-0aa3-4055-9eca-7c140062ada2",
"title": "first post"
}
}
}
```
Se verificarmos a tabela do DynamoDB rapidamente, poderemos ver nossa entrada na tabela quando a verificarmos:
![\[DynamoDB table entry showing id, date, and title fields for a single item.\]](http://docs.aws.amazon.com/pt_br/appsync/latest/devguide/images/cdk-code-request-2.png)
De volta ao AWS AppSync console, se executarmos a consulta para recuperar isso`Post`, obteremos o seguinte resultado:
```
{
"data": {
"getPost": [
{
"id": "9f62c4dd-49d5-48d5-b835-143284c72fe0",
"date": "1970-01-01T12:30:00.000Z",
"title": "first post"
}
]
}
}
```