Como anexar uma fonte de dados no AWS AppSync

As fontes de dados são recursos da conta da AWS com que as APIs GraphQL podem interagir. O AWS AppSync oferece suporte a várias fontes de dados, como o AWS Lambda, o Amazon DynamoDB, os bancos de dados relacionais (Amazon Aurora Sem Servidor), o Amazon OpenSearch Service e endpoints HTTP. Uma API do AWS AppSync pode ser configurada para interagir com várias fontes de dados, permitindo que você agregue dados em um único local. O AWS AppSync pode usar os recursos da AWS da sua conta que já existem ou provisionar tabelas do DynamoDB em seu nome 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 console do AWS AppSync e o salvou, adicione uma fonte de dados. 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.

Em vez disso, analisaremos todas as fontes de dados compatíveis com o AWS AppSync. 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.

Amazon DynamoDB

O Amazon DynamoDB é uma das principais soluções do 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 uma linha/registro 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 da sua aplicação. O AWS AppSync permite que você conecte suas tabelas do DynamoDB à sua API GraphQL para manipular dados. Veja este caso de uso 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 pelo 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 qualquer coisa como um aplicativo fazendo uma chamada de API, um serviço da AWS 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 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 do Lambda, eles usam o serviço do AWS AppSync para manter seu esquema e vincular uma fonte de dados do 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 ao fornecer escalabilidade usando a infraestrutura da AWS, os serviços de segurança, como patches e criptografia, e reduz os custos administrativos das implantações.

Veja o mesmo caso de uso da seção do Lambda. Na Opção 3: AWS AppSync com o resolvedor do Amazon RDS, outra opção apresentada é vincular a API GraphQL diretamente ao Amazon RDS no AWS AppSync. Com uma API de dados, 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

No EventBridge, você criará barramentos de eventos, que são pipelines que recebem eventos de serviços ou aplicações que você anexa (a fonte 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, o EventBridge envia o evento pelo pipeline até o serviço de destino (destino) e aciona a ação especificada na regra.

O EventBridge faz o roteamento de operações de mudança de estado para algum outro serviço. Veja este caso de uso 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 pela 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 destino que direciona para a API GraphQL instalada no 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 da seção do EventBridge. 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 a pesquisa de texto completo, a visualização de dados e o registro em log. Você pode usar esse serviço para consultar os dados estruturados que enviou.

Neste serviço, você criará instâncias do 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, o OpenSearch não é compatível com ACID, então não deve ser usado dessa forma). Você preencherá seu índice com os dados que carregará no serviço OpenSearch. 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. O 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 serviço AWS AppSync e, mais especificamente, à API.

Console

1. Faça login no AWS Management Console e abra o Console do AppSync.

   1. Escolha sua API no Painel.

   2. Na barra lateral, escolha Fontes de dados.

2. Escolha Criar fonte de dados.

   1. Dê um nome à sua fonte de dados. Você também pode incluir uma descrição, mas isso é opcional.

   2. Selecione o tipo de fonte de dados.

   3. 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, 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 o 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.

      Para o EventBridge, você terá que escolher sua região e, em seguida, o barramento de eventos 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.

3. 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 create-data-source.

  Você precisará inserir alguns parâmetros para esse comando específico:

  1. O api-id da sua API.

  2. O name da tabela.

  3. 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, leia a documentação oficial junto com a referência do CDK do AWS AppSync.

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

• EventBridgeDataSource

• HttpDataSource

• LambdaDataSource

• NoneDataSource

• OpenSearchDataSource

• RdsDataSource

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 do AWS AppSync e do DynamoDB:

   import * as appsync from 'aws-cdk-lib/aws-appsync';
   import * as dynamodb from 'aws-cdk-lib/aws-dynamodb';

2. 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.

3. Para a maioria das fontes de dados, especialmente os serviços da AWS, 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.

4. 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 console do AWS AppSync (neste exemplo data_source_name_in_console) 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 console do AWS AppSync (para continuar usando o valor data_source_name_in_console do 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 estiver usando um perfil existente do IAM para sua fonte de dados, é necessário conceder as permissões apropriadas a esse perfil para executar operações no recurso da AWS, como PutItem em uma tabela do Amazon DynamoDB. Também é necessário modificar a política de confiança desse perfil para permitir que ele use o AWS AppSync para acessar os recursos, conforme mostrado na seguinte política de exemplo:

{
    "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:

{
  "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:

{
  "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 todas as APIs do AWS AppSync de uma região específica, por exemplo, us-east-1, usando a seguinte política:

{
  "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), 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 no Guia do usuário do IAM.

Para obter mais informações sobre o acesso entre contas de resolvedores do AWS Lambda para o AWS AppSync, consulte Building cross-account AWS Lambda resolvers for AWS AppSync.