Uso de uma API do AWS AppSync com o AWS CDK

Nesta seção, criaremos uma aplicação do CDK simples que pode adicionar e buscar itens de uma tabela do DynamoDB. Este é um exemplo de início rápido usando parte do código nas seções Projetar seu esquema, Anexar uma fonte de dados e Configuração de resolvedores (JavaScript).

Configuração de um projeto de CDK

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:

A estrutura do seu projeto pode ser semelhante a esta:

Você notará que temos vários diretórios importantes:

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. Para criar um bootstrap, o comando é:

cdk bootstrap aws://ACCOUNT-NUMBER/REGION

O bootstrap criará vários recursos. A mensagem final terá a aparência a seguir:

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 pilha do AWS CloudFormation e o bucket do 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 pilha do AWS CloudFormation, chamada pilha de bootstrap, que geralmente é nomeada CDKToolkit. Como qualquer pilha do AWS CloudFormation, ela aparece no console do AWS CloudFormation depois de implantada:

Isso também se aplica ao bucket:

Para importar os serviços que precisamos em nosso arquivo de pilha, podemos usar o seguinte comando:

npm install aws-cdk-lib # V2 command

npm install @aws-cdk/aws-appsync @aws-cdk/aws-dynamodb

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:

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:

Parece que nosso exemplo foi bem-sucedido, mas vamos verificar o console AWS AppSync apenas para confirmar:

Parece que nossa API foi criada. Agora, verificaremos o esquema anexado à API:

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 do AWS CloudFormation:

Quando implantamos nosso aplicativo CDK, ele passa pelo AWS CloudFormation para configurar recursos como o bootstrap. Cada pilha em nosso aplicativo realiza mapeamento individual com uma pilha do AWS CloudFormation. 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:

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:

O nome da nossa pilha está correto e o nome da tabela corresponde ao nosso código. Se verificarmos nossa pilha do AWS CloudFormation novamente, agora veremos a nova tabela:

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 serviço do AWS AppSync:

cdk deploy

Vamos verificar o console do AWS AppSync para ver se eles estavam conectados à nossa API GraphQL:

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:

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:

Isso corresponde aos props code da função add_posts_func_1. Como nossa consulta foi enviada com sucesso, vamos verificar a consulta:

Eles também correspondem ao código. Se observarmos get_posts_func_1:

Tudo parece estar no lugar certo. Para confirmar isso do ponto de vista dos metadados, podemos verificar nossa pilha no AWS CloudFormation novamente:

Agora, precisamos testar esse código executando algumas solicitações.

Implementação de um projeto de CDK - Solicitações

Para testar nosso aplicativo no console do AWS AppSync, fizemos uma consulta e uma mutação:

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:

De volta ao console AWS AppSync, se executarmos a consulta para recuperar este Post, obteremos o seguinte resultado:

{
  "data": {
    "getPost": [
      {
        "id": "9f62c4dd-49d5-48d5-b835-143284c72fe0",
        "date": "1970-01-01T12:30:00.000Z",
        "title": "first post"
      }
    ]
  }
}