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á.
# 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"
}
]
}
}
```