Ctrlk

AWS DynamoDB

☁️ Módulo AWS DynamoDB

O módulo AWS DynamoDB permite que o seu chatbot se comunique com um banco de dados Amazon DynamoDB durante uma conversa. Com ele, você pode ler um registro específico, gravar novos dados, consultar itens por condição ou varrer uma tabela inteira com filtros — tudo de forma automática, enquanto o atendimento acontece.

📷 Inserir print: visão geral do nó AWS DynamoDB no canvas do Builder

🗂️ Como acessar

  1. No menu lateral, clique em Aplicativo.

  2. Em seguida, clique em Fluxos.

  3. Abra o fluxo desejado ou crie um novo.

  4. No canvas do Builder, clique no botão + para adicionar um novo nó.

  5. Localize e selecione AWS - DynamoDB na lista de módulos disponíveis.

📷 Inserir print: lista de módulos com o item "AWS - DynamoDB" destacado

Pré-requisito: Para usar este módulo, é necessário ter uma integração com a AWS configurada na plataforma. Caso não exista nenhuma integração disponível no campo Nome da integração, acesse as configurações de integrações, cadastre as credenciais da AWS e retorne para configurar o módulo.

🧩 Conhecendo o módulo

Ao adicionar o módulo ao fluxo, um painel de configuração é aberto. Nele, você define qual tabela do DynamoDB será acessada, qual operação o bot deve realizar e os parâmetros necessários para cada ação.

📷 Inserir print: painel de configuração do módulo AWS DynamoDB aberto

🔧 Configurações gerais

Estes campos aparecem em todas as operações e devem ser preenchidos antes de escolher a ação.

Campo
O que preencher

Nome da integração

Selecione a integração AWS cadastrada que o bot deve usar para se conectar ao DynamoDB. Campo obrigatório.

Endpoint DAX

(Opcional) Informe o endereço do cluster Amazon DAX se quiser usar cache distribuído para acelerar as leituras.

Operação

Escolha o que o bot deve fazer: Leitura, Escrita, Varredura ou Consulta.

Tabela

Informe o nome da tabela do DynamoDB que será acessada. Aceita variáveis do fluxo (ex.: {{config.tabela}}).

📷 Inserir print: campos gerais preenchidos (integração, operação e tabela)

⚙️ Configurações por operação

Os campos exibidos no painel mudam conforme a operação selecionada. Veja abaixo o que configurar em cada caso.

1️⃣ Leitura

🎯 Propósito

Buscar um único item na tabela do DynamoDB a partir de sua chave primária — por exemplo, recuperar os dados de um cliente pelo seu ID.

✅ Como fazer na tela

  1. No campo Operação, selecione Leitura.

  2. Informe o nome da Tabela que contém o registro desejado.

  3. No campo Chave, informe o nome do atributo que é a chave primária da tabela (ex.: userId).

  4. No campo Valor da chave, informe o valor a ser buscado. Você pode digitar um valor fixo ou usar uma variável do fluxo (ex.: {{input.id}}).

  5. Clique em Salvar alterações.

📷 Inserir print: painel configurado para a operação Leitura com chave e valor preenchidos

📌 Resultado esperado

O módulo busca o item correspondente na tabela e disponibiliza os dados como variáveis para os próximos nós do fluxo. Se o item não for encontrado ou ocorrer algum problema, o fluxo segue pela saída ERR.

2️⃣ Escrita

🎯 Propósito

Gravar um novo item ou sobrescrever um item existente na tabela do DynamoDB — por exemplo, registrar os dados de um lead coletados durante a conversa.

✅ Como fazer na tela

  1. No campo Operação, selecione Escrita.

  2. Informe o nome da Tabela de destino.

  3. No campo Chave, informe o nome do atributo que é a chave primária da tabela.

  4. No campo Valor da chave, informe o valor que identificará o item gravado. Aceita variáveis do fluxo.

  5. No campo Corpo, insira o objeto completo a ser gravado no formato JSON. Você pode usar variáveis do fluxo dentro do JSON (ex.: {"nome": "{{lead.nome}}", "email": "{{lead.email}}"}).

  6. Clique em Salvar alterações.

O campo Corpo aceita JSON completo. Certifique-se de que a estrutura esteja correta — chaves e valores devem seguir o formato {"atributo": "valor"}. Variáveis do fluxo podem ser usadas dentro das strings.

📷 Inserir print: painel configurado para Escrita com o campo Corpo preenchido em JSON

📌 Resultado esperado

O item é gravado na tabela com os dados informados no campo Corpo. Se a gravação for bem-sucedida, o fluxo segue pela saída OK. Em caso de falha, segue pela saída ERR.

3️⃣ Varredura

🎯 Propósito

Percorrer todos os itens de uma tabela e retornar aqueles que correspondem a uma expressão de filtro — por exemplo, listar todos os clientes de uma determinada cidade.

✅ Como fazer na tela

  1. No campo Operação, selecione Varredura.

  2. Informe o nome da Tabela a ser varrida.

  3. (Opcional) No campo Expressão de filtro, informe a condição que os itens devem atender para ser retornados (ex.: cidade = :cidade). A sintaxe segue o padrão de expressões do DynamoDB.

  4. No campo Nomes de atributos da expressão (JSON obrigatório), mapeie os apelidos usados na expressão para os nomes reais dos atributos da tabela. Exemplo:

  5. No campo Valores de atributos da expressão (JSON obrigatório), defina os valores correspondentes aos marcadores usados na expressão de filtro. Exemplo:

  6. Clique em Salvar alterações.

A operação Varredura percorre a tabela inteira antes de aplicar o filtro. Em tabelas muito grandes, isso pode ser mais lento e custoso do que uma Consulta. Prefira a Consulta quando precisar de resultados frequentes em grandes volumes de dados.

📷 Inserir print: painel configurado para Varredura com expressão de filtro e campos JSON preenchidos

📌 Resultado esperado

O módulo retorna todos os itens da tabela que atendem ao filtro definido. Os dados ficam disponíveis como variáveis para os próximos nós do fluxo.

4️⃣ Consulta

🎯 Propósito

Buscar itens em uma tabela ou índice do DynamoDB a partir de uma expressão de condição de chave — por exemplo, retornar todos os pedidos de um determinado cliente usando um índice secundário.

✅ Como fazer na tela

  1. No campo Operação, selecione Consulta.

  2. Informe o nome da Tabela a ser consultada.

  3. (Opcional) No campo Nome do índice, informe o nome do índice secundário global (GSI) ou local (LSI) a ser usado. Deixe vazio para consultar pela chave primária da tabela.

  4. No campo Expressão de condição de chave, informe a condição que a chave deve atender (ex.: clienteId = :id).

  5. (Opcional) No campo Expressão de filtro, adicione filtros adicionais sobre os itens retornados.

  6. No campo Nomes de atributos da expressão (JSON obrigatório), mapeie os apelidos usados nas expressões. Exemplo:

  7. No campo Valores de atributos da expressão (JSON obrigatório), defina os valores dos marcadores usados. Exemplo:

  8. Clique em Salvar alterações.

📷 Inserir print: painel configurado para Consulta com índice, expressão de chave e campos JSON preenchidos

📌 Resultado esperado

O módulo retorna os itens que correspondem à condição de chave (e ao filtro, se informado). Os dados ficam disponíveis como variáveis nos próximos nós do fluxo.

🔀 Saídas do módulo no fluxo

Após a execução, o módulo AWS DynamoDB direciona o fluxo por dois caminhos:

Saída
Quando acontece

OK

A operação foi realizada com sucesso

ERR

Ocorreu um erro ao executar a operação (ex.: chave não encontrada, credenciais inválidas, JSON malformado)

Conecte cada saída ao próximo nó conforme a lógica do seu fluxo — por exemplo, exibir uma mensagem de confirmação no caminho OK ou uma mensagem de erro no caminho ERR.

📷 Inserir print: nó AWS DynamoDB no canvas com as saídas OK e ERR conectadas a nós diferentes

💡 Dicas úteis

  • Variáveis do fluxo: A maioria dos campos de texto aceita variáveis dinâmicas com a sintaxe {{nome.da.variavel}}. Use isso para preencher automaticamente dados coletados durante a conversa.

  • Formato JSON: Os campos de expressão de nomes e valores de atributos esperam JSON válido no formato do DynamoDB. Cada valor deve ter o tipo explicitado (ex.: { "S": "texto" } para string, { "N": "42" } para número).

  • Endpoint DAX: Use o campo DAX Endpoint apenas se o seu ambiente AWS tiver um cluster Amazon DAX configurado para cache de leitura. Na maioria dos casos, esse campo pode ser deixado vazio.

  • Consulta vs. Varredura: Para buscas frequentes em tabelas grandes, prefira sempre a Consulta (com um índice adequado) em vez da Varredura, pois a Varredura lê a tabela inteira a cada execução.

  • Nomes reservados: Se o nome de um atributo da sua tabela for uma palavra reservada do DynamoDB (ex.: status, name), use o campo Nomes de atributos da expressão para criar um apelido seguro (ex.: #status).

📋 Caso de uso

Cenário: Uma empresa de e-commerce usa um chatbot no WhatsApp para permitir que clientes consultem o status dos seus pedidos em tempo real. Os pedidos estão armazenados em uma tabela do DynamoDB chamada pedidos, com um índice secundário por clienteId.

Configuração principal:

  1. Adicione o módulo AWS DynamoDB ao fluxo, após o nó que coleta o número de CPF do cliente.

  2. Selecione a integração AWS com as credenciais do ambiente de produção.

  3. Escolha a operação Consulta.

  4. Informe a tabela pedidos e o índice clienteId-index.

  5. No campo Expressão de condição de chave, insira clienteId = :id.

  6. No campo Valores de atributos da expressão, insira:

  7. Conecte a saída OK a um nó de mensagem que exibe o status do pedido usando a variável retornada.

  8. Conecte a saída ERR a um nó que informa ao cliente que não foi possível localizar o pedido e oferece alternativas de atendimento.

Resultado esperado no fluxo: O chatbot consulta o DynamoDB com o CPF informado pelo cliente e retorna automaticamente o status atualizado do pedido, sem precisar de intervenção humana.

✅ Resumo

  • O módulo AWS DynamoDB conecta o chatbot a tabelas do Amazon DynamoDB para realizar operações em tempo real durante o atendimento.

  • São 4 operações disponíveis: Leitura (buscar um item pela chave), Escrita (gravar um item), Varredura (percorrer a tabela com filtros) e Consulta (buscar por condição de chave em índice).

  • Todos os campos de texto aceitam variáveis dinâmicas do fluxo, permitindo automações personalizadas.

  • Os campos de expressão (Nomes e Valores de atributos) usam o formato JSON do DynamoDB e são obrigatórios nas operações de Varredura e Consulta.

  • O módulo possui duas saídas: OK (sucesso) e ERR (erro), que devem ser conectadas a nós diferentes conforme a lógica do fluxo.

Last updated