> For the complete documentation index, see [llms.txt](https://help.hyperflow.global/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.hyperflow.global/docs/builder-hyperflow/gerenciamento-de-aplicativos/fluxos/integracao/aws-dynamodb.md). # 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 {% hint style="warning" %} **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. {% endhint %} *** ### 🧩 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**. {% hint style="info" %} 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. {% endhint %} **📷 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: ```json { "#cidade": "cidade" } ``` 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: ```json { ":cidade": { "S": "São Paulo" } } ``` 6. Clique em **Salvar alterações**. {% hint style="warning" %} 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. {% endhint %} **📷 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: ```json { "#status": "status" } ``` 7. No campo **Valores de atributos da expressão** (JSON obrigatório), defina os valores dos marcadores usados. Exemplo: ```json { ":id": { "S": "{{input.clienteId}}" } } ``` 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: ```json { ":id": { "S": "{{input.cpf}}" } } ``` 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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://help.hyperflow.global/docs/builder-hyperflow/gerenciamento-de-aplicativos/fluxos/integracao/aws-dynamodb.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.