AWS AppSync: Desenvolvimento centrado em código com AWS CloudFormation

Image for post
Image for post

O AWS AppSync é um serverless GraphQL backend-as-a-service. A maioria dos artigos online mostra seu uso através do console da AWS e configurando via interface web, o que não é uma abordagem centrada em código. Eu gostaria de mostrar uma abordagem orientada a código, empregando uma técnica chamada Infraestrutura como Código usando o AWS CloudFormation. O CloudFormation permite que você especifique todos os recursos da AWS na forma de código e automatize suas implantações por meio da linha de comando. Desta forma, todos os recursos de infraestrutura necessários para o seu aplicativo se tornam parte do repositório git — controlados por versão. Você pode reproduzir a stack inteira (conjunto de recursos relacionados) na nuvem com um único comando, ao invés de repetir as etapas manualmente por meio da GUI. Depois que a stack inicial é criada, você pode implantar facilmente alterações em sua infraestrutura, modificando o arquivo de modelo e, em seguida, executando comandos por meio da linha de comando. Essa abordagem oferece controle total direto por meio de código e é muito flexível para se integrar ao restante do ecossistema da AWS.

Mostrarei passo a passo como criar e implantar uma API AppSync GraphQL de nível de produção usando o DynamoDB, tudo a partir do conforto de seu editor e terminal.

1. Definindo o esquema GraphQL

Iremos criar um esquema de exemplo com uma consulta para obter contatos e uma mutação para adicionar um novo contato e salvar o arquivo como schema.graphql no diretório principal do projeto.

mkidr exemplo-appsync
cd exemplo-appsync
touch schema.graphql
vim schema.graphql

Adicionamos:

type Contact {
username: String!
fullName: String!
email: String!
phone: String
}
input ContactInput {
fullName: String!
email: String!
phone: String
}
type Query {
getContacts: [Contact!]!
}
type Mutation {
addContact(username: String! contact: ContactInput!): Contact
}
type Schema {
query: Query
mutation: Mutation
}

2. Adicionar modelos de mapeamento para os Resolvers

O modelo de mapeamento de resolução informa ao AppSync como converter uma solicitação de GraphQL recebida em instruções para sua fonte de dados do back-end e como traduzir a resposta dessa origem de dados de volta para uma resposta do GraphQL. Criaremos modelos de mapeamento de solicitação e resposta separados em arquivos diferentes para cada resolver.

$ mkdir mapping-templates
$ cd mapping-templates
$ touch addContact.request.vm
$ touch addContact.response.vm
$ touch getContacts.request.vm
$ touch getContacts.response.vm

Em addContact.request.vm, adicione:

## mapeamento de resolução da requisição da mutação `addContact`, mapeando para a operação `PutItem` do DynamoDB.
{
"version": "2017-02-28",
"operation": "PutItem",
"key": {
"username": $util.dynamodb.toDynamoDBJson($ctx.args.username)
},
"attributeValues": $util.dynamodb.toMapValuesJson($ctx.args.contact)
}

Em addContact.response.vm, adicione:

## mapeamento de resolução da resposta da mutação `addContact`, retornando o novo objeto de contato adicionado.
$util.toJson($ctx.result)

Em getContacts.request.vm, adicione:

## mapeamento de resolução da requisição da query `getContacts`, mapeando para a operação `Scan` do DynamoDB.
{
"version": "2017-02-28",
"operation": "Scan"
}

Em getContacts.response.vm, adicione:

## mapeamento de resolução da resposta da query `getContacts`, retornando todos os contatos.
$util.toJson($ctx.result.items)

3. Especifique recursos no modelo do CloudFormation

Aqui criaremos o modelo CloudFormation no formato YAML, que é mais legível do que sua contraparte JSON. Ele especifica detalhes sobre nossa AppSync API, API Key, o esquema GraphQL, a tabela do DynamoDB, nossas Fontes de Dados para a API AppSync, os Resolvers do GraphQL e o acesso à Tabela do DynamoDB usando uma IAM Role.

$ touch template.yml
$ vim template.yml

E em seguida:

AWSTemplateFormatVersion: '2010-09-09'
Description: Create AppSync GraphQL API using DynamoDB
Parameters: ApiName:
Type: String
Description: Name of the API - used to generate unique names for resources
MinLength: 3
MaxLength: 25
AllowedPattern: '^[a-zA-Z][a-zA-Z0-9\-]*$'
Resources: GraphQLApi:
Type: AWS::AppSync::GraphQLApi
Properties:
Name: !Sub ${ApiName}-graphql-api
AuthenticationType: API_KEY
ApiKey:
Type: AWS::AppSync::ApiKey
Properties:
ApiId: !GetAtt GraphQLApi.ApiId
GraphQLSchema:
Type: AWS::AppSync::GraphQLSchema
Properties:
ApiId: !GetAtt GraphQLApi.ApiId
# caminho para o esquema graphql
DefinitionS3Location: schema.graphql
ContactsTable:
Type: AWS::DynamoDB::Table
Properties:
TableName: !Sub ${ApiName}-contacts
KeySchema:
- AttributeName: username
KeyType: HASH
AttributeDefinitions:
- AttributeName: username
AttributeType: S
BillingMode: PAY_PER_REQUEST
ApiRole:
Type: AWS::IAM::Role
Properties:
AssumeRolePolicyDocument:
Version: '2012-10-17'
Statement:
- Effect: Allow
Principal:
Service:
- appsync.amazonaws.com
Action:
- sts:AssumeRole
Policies:
- PolicyName: !Sub ${ApiName}-dynamo-access
PolicyDocument:
Version: '2012-10-17'
Statement:
- Effect: Allow
Action:
- dynamodb:GetItem
- dynamodb:PutItem
- dynamodb:DeleteItem
- dynamodb:UpdateItem
- dynamodb:Query
- dynamodb:Scan
- dynamodb:BatchGetItem
- dynamodb:BatchWriteItem
Resource: !GetAtt ContactsTable.Arn
ContactsTableDataSource:
Type: AWS::AppSync::DataSource
Properties:
Name: ContactsTableDataSource
Type: AMAZON_DYNAMODB
ServiceRoleArn: !GetAtt ApiRole.Arn
DynamoDBConfig:
AwsRegion: !Ref AWS::Region
TableName: !Ref ContactsTable
ApiId: !GetAtt GraphQLApi.ApiId
QueryGetContactsResolver:
Type: AWS::AppSync::Resolver
Properties:
TypeName: Query
FieldName: getContacts
DataSourceName: !GetAtt ContactsTableDataSource.Name
# caminho para o arquivo de mapeamento de resolução da requisição
RequestMappingTemplateS3Location: mapping-templates/getContacts.request.vm
# caminho para o arquivo de mapeamento de resolução da resposta
ResponseMappingTemplateS3Location: mapping-templates/getContacts.response.vm
ApiId: !GetAtt GraphQLApi.ApiId
MutationAddContactResolver:
Type: AWS::AppSync::Resolver
Properties:
TypeName: Mutation
FieldName: addContact
DataSourceName: !GetAtt ContactsTableDataSource.Name
# caminho para o arquivo de mapeamento de resolução da requisição
RequestMappingTemplateS3Location: mapping-templates/addContact.request.vm
# caminho para o arquivo de mapeamento de resolução da resposta
ResponseMappingTemplateS3Location: mapping-templates/addContact.response.vm
ApiId: !GetAtt GraphQLApi.ApiId
Outputs: GraphQLApiEndpoint:
Description: GraphQL API URL
Value: !GetAtt GraphQLApi.GraphQLUrl
ApiKey:
Description: API Key
Value: !GetAtt ApiKey.ApiKey

4. Deploy usando o AWS CLI

Primeiro, instale o AWS CLI e configure-o especificando as credenciais de segurança e as informações de região da sua conta. Forneça a opção de perfil em todos os comandos se você quiser usar uma configuração de perfil específica, caso contrário, usará o perfil padrão.

Crie um bucket do S3 para fazer o upload de arquivos de código:

aws s3 mb s3://contacts-dev-codes  --profile faisal

Execute o comando package para empacotar os artefatos locais referenciados no arquivo CloudFormation que criamos, template.yml, para o bucket S3 especificado. Isso gerará um novo arquivo, que se irá usar referências aos arquivos no bucket S3 ao invés dos arquivos locais.

aws cloudformation package \
--s3-bucket contacts-dev-codes \
--template-file template.yml \
--output-template-file packaged-template.yml \
--profile faisal

Execute o comando deploy utilizando o arquivo recém-gerado para criar todos os recursos de infraestrutura. Além disso, não esqueça de fornecer o nome da stack e os parâmetros necessários do template:

aws cloudformation deploy \
--stack-name contacts-dev \
--template-file packaged-template.yml \
--capabilities CAPABILITY_IAM \
--parameter-overrides ApiName=contacts-dev \
--profile faisal

Agora você tem uma API AppSync GraphQL totalmente funcional com DynamoDB na AWS. Você pode usar os comandos package e deploy repetidamente sempre que fizer alterações no template, ele criará automaticamente o conjunto de mudanças e o executará. Se você estiver usando o Node.js, poderá adicionar esses comandos como scripts do NPM ao package.json de um projeto, por conveniência.

Eu criei o repositório GitHub que contém todo o código padrão com a configuração completa necessária para o kickstart do projeto AppSync.

Crédito

Written by

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store