Pular para conteúdo

SHEETS_READ - Ler Dados do Google Sheets

O que é este Node?

O SHEETS_READ é o node responsável por ler dados de uma planilha do Google Sheets com autenticação OAuth2. Permite extrair valores de qualquer range (intervalo) da planilha para uso no fluxo.

Por que este Node existe?

Muitas empresas armazenam dados críticos em Google Sheets - desde listas de produtos até registros de clientes. O SHEETS_READ existe para:

  1. Integração com Dados Empresariais: Buscar informações de planilhas corporativas sem migração de dados
  2. Automação de Processos: Ler automaticamente dados atualizados para enviar mensagens personalizadas
  3. Consultas Dinâmicas: Verificar estoque, preços, cadastros diretamente da fonte
  4. Análise de Dados: Extrair informações para decisões em tempo real no fluxo

Como funciona internamente?

Quando o SHEETS_READ é executado, o sistema:

  1. Valida autenticação: Verifica se há tokens OAuth2 válidos (accessToken e refreshToken)
  2. Conecta ao Google Sheets API: Usa o cliente OAuth2 para autenticar
  3. Identifica a planilha: Extrai o spreadsheetId da URL ou usa o ID fornecido
  4. Define o range: Usa o range fornecido ou padrão 'Sheet1!A1:Z1000'
  5. Executa leitura: Chama spreadsheets.values.get() para obter os dados
  6. Retorna dados: Devolve array de arrays com os valores lidos
  7. Se erro: Lança exceção com mensagem detalhada

Código interno (google-executors.service.ts:756-766): 

case 'read':
  const readResult = await sheets.spreadsheets.values.get({
    spreadsheetId: data.spreadsheetId,
    range: data.range || 'Sheet1!A1:Z1000',
  });

  return {
    success: true,
    data: readResult.data.values,
    rowCount: readResult.data.values?.length || 0,
  };

Quando você DEVE usar este Node?

Use SHEETS_READ sempre que precisar buscar dados de uma planilha do Google Sheets:

Casos de uso

  1. CRM Manual: "Ler lista de clientes da planilha 'Cadastros' para enviar promoções personalizadas"
  2. Controle de Estoque: "Verificar estoque disponível na planilha antes de confirmar pedido"
  3. Base de Conhecimento: "Buscar respostas de FAQ armazenadas em Google Sheets"
  4. Relatórios: "Extrair dados de vendas para análise e geração de mensagens"
  5. Validação: "Verificar se número de telefone existe na planilha de autorizados"

Quando NÃO usar SHEETS_READ

  • Dados estáticos pequenos: Use NODE VARIABLE para armazenar no fluxo
  • Banco de dados relacional: Use NODE DATABASE para consultas SQL
  • APIs REST: Use NODE API_CALL para endpoints HTTP

Parâmetros Detalhados

spreadsheetId (string, obrigatório)

O que é: ID da planilha do Google Sheets. Pode ser extraído da URL da planilha.

Exemplo de URL: https://docs.google.com/spreadsheets/d/1abc123xyz/edit O spreadsheetId é: 1abc123xyz

Flow completo para testar:

{
  "name": "Teste Sheets Read - SpreadsheetId",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "sheets_1",
      "type": "google_sheets",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Ler Planilha",
        "parameters": {
          "operation": "read",
          "spreadsheetId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
          "range": "Class Data!A1:E10",
          "accessToken": "{{google_access_token}}",
          "refreshToken": "{{google_refresh_token}}"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Mostrar Dados",
        "parameters": {
          "message": "Lidos {{sheets_1.rowCount}} linhas da planilha"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 700, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "sheets_1" },
    { "source": "sheets_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Teste: Configure os tokens OAuth2 do Google nas variáveis. O sistema deve retornar os dados da planilha.

range (string, opcional)

O que é: Range (intervalo) de células a ser lido usando notação A1. Define exatamente quais células serão extraídas.

Padrão: "Sheet1!A1:Z1000"

Formato da notação A1: - A1:B10 - Da célula A1 até B10 (10 linhas, 2 colunas) - Sheet1!A:A - Toda a coluna A da Sheet1 - Sheet1!1:1 - Toda a primeira linha da Sheet1 - Sheet1!A1:Z - Da coluna A até Z, todas as linhas - Vendas!B2:D100 - Da célula B2 até D100 na aba 'Vendas'

Flow completo para testar:

{
  "name": "Teste Sheets Read - Range",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "sheets_1",
      "type": "google_sheets",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Ler Coluna Nome",
        "parameters": {
          "operation": "read",
          "spreadsheetId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
          "range": "Class Data!A2:A50",
          "accessToken": "{{google_access_token}}",
          "refreshToken": "{{google_refresh_token}}"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Mostrar Primeiro Nome",
        "parameters": {
          "message": "Primeiro nome encontrado: {{sheets_1.data.0.0}}"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 700, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "sheets_1" },
    { "source": "sheets_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Teste: O sistema deve ler apenas a coluna A (nomes) da linha 2 até 50 e retornar o primeiro valor.

accessToken (string, obrigatório)

O que é: Token de acesso OAuth2 do Google para autenticar a requisição. Obtido através do fluxo OAuth2 do Google.

Como obter: 1. Configure Google Cloud Console com API Sheets habilitada 2. Configure OAuth2 Consent Screen 3. Crie credenciais OAuth 2.0 (Client ID e Client Secret) 4. Use o fluxo OAuth2 para obter o accessToken

Flow completo para testar:

{
  "name": "Teste Sheets Read - AccessToken",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "variable_1",
      "type": "variable",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Configurar Token",
        "parameters": {
          "variableName": "google_access_token",
          "value": "ya29.a0AfB_..."
        }
      }
    },
    {
      "id": "sheets_1",
      "type": "google_sheets",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Ler Planilha",
        "parameters": {
          "operation": "read",
          "spreadsheetId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
          "range": "Sheet1!A1:C10",
          "accessToken": "{{google_access_token}}",
          "refreshToken": "{{google_refresh_token}}"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "Leitura realizada com sucesso!"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 900, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "variable_1" },
    { "source": "variable_1", "target": "sheets_1" },
    { "source": "sheets_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Teste: Substitua o token por um válido do Google OAuth2. O sistema deve autenticar e ler a planilha.

refreshToken (string, obrigatório)

O que é: Token de atualização OAuth2 usado para obter novos accessTokens quando expiram. É de longa duração.

Padrão: Nenhum - deve ser fornecido

Flow completo para testar:

{
  "name": "Teste Sheets Read - RefreshToken",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "sheets_1",
      "type": "google_sheets",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Ler Planilha",
        "parameters": {
          "operation": "read",
          "spreadsheetId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
          "range": "Sheet1!A1:B5",
          "accessToken": "{{google_access_token}}",
          "refreshToken": "1//0gABC123..."
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "Dados lidos: {{sheets_1.rowCount}} linhas"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 700, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "sheets_1" },
    { "source": "sheets_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Teste: O refreshToken garante que mesmo com accessToken expirado, o sistema obtenha um novo automaticamente.

Parâmetros

Campo Tipo Obrigatório Descrição
operation string Sim Deve ser "read" para leitura
spreadsheetId string Sim ID da planilha Google Sheets
range string Não Range em notação A1 (padrão: Sheet1!A1:Z1000)
accessToken string Sim Token OAuth2 de acesso
refreshToken string Sim Token OAuth2 de atualização

Exemplo 1: Ler Lista de Clientes para CRM

Objetivo: Ler cadastro de clientes de uma planilha e enviar mensagem personalizada

JSON para Importar

{
  "name": "CRM - Ler Clientes do Sheets",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": {
        "label": "Início",
        "message": "Iniciando leitura de clientes"
      }
    },
    {
      "id": "sheets_1",
      "type": "google_sheets",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Buscar Clientes",
        "parameters": {
          "operation": "read",
          "spreadsheetId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
          "range": "Clientes!A2:D100",
          "accessToken": "{{google_access_token}}",
          "refreshToken": "{{google_refresh_token}}"
        }
      }
    },
    {
      "id": "variable_1",
      "type": "variable",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Salvar Dados",
        "parameters": {
          "variableName": "clientes",
          "value": "{{sheets_1.data}}"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Resumo",
        "parameters": {
          "message": "📊 Total de clientes encontrados: {{sheets_1.rowCount}}\n\nPrimeiro cliente: {{sheets_1.data.0.0}}"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 900, "y": 100 },
      "data": {
        "label": "Fim",
        "message": "Leitura concluída com sucesso!"
      }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "sheets_1" },
    { "source": "sheets_1", "target": "variable_1" },
    { "source": "variable_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: Iniciando leitura de clientes
Sistema: 📊 Total de clientes encontrados: 98

Primeiro cliente: José Silva
Sistema: Leitura concluída com sucesso!

Exemplo 2: Verificar Estoque Antes de Confirmar Pedido

Objetivo: Consultar estoque em tempo real na planilha antes de processar pedido

JSON para Importar

{
  "name": "E-commerce - Verificar Estoque",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "input_1",
      "type": "input",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Perguntar Produto",
        "parameters": {
          "prompt": "Qual produto você deseja? Digite o código:",
          "variableName": "codigo_produto"
        }
      }
    },
    {
      "id": "sheets_1",
      "type": "google_sheets",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Consultar Estoque",
        "parameters": {
          "operation": "read",
          "spreadsheetId": "1ABC_EstoqueControle_XYZ",
          "range": "Produtos!A:D",
          "accessToken": "{{google_access_token}}",
          "refreshToken": "{{google_refresh_token}}"
        }
      }
    },
    {
      "id": "condition_1",
      "type": "condition",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Tem Estoque?",
        "parameters": {
          "condition": "{{sheets_1.data.length}} > 0"
        }
      }
    },
    {
      "id": "message_success",
      "type": "message",
      "position": { "x": 900, "y": 50 },
      "data": {
        "label": "Produto Disponível",
        "parameters": {
          "message": "✅ Produto em estoque! Quantidade: {{sheets_1.data.0.3}}"
        }
      }
    },
    {
      "id": "message_fail",
      "type": "message",
      "position": { "x": 900, "y": 150 },
      "data": {
        "label": "Sem Estoque",
        "parameters": {
          "message": "❌ Produto indisponível no momento"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 1100, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "input_1" },
    { "source": "input_1", "target": "sheets_1" },
    { "source": "sheets_1", "target": "condition_1" },
    { "source": "condition_1", "target": "message_success", "label": "true" },
    { "source": "condition_1", "target": "message_fail", "label": "false" },
    { "source": "message_success", "target": "end_1" },
    { "source": "message_fail", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: Qual produto você deseja? Digite o código:
Usuário: PROD001
Sistema: ✅ Produto em estoque! Quantidade: 45

Exemplo 3: Base de Conhecimento de FAQ

Objetivo: Buscar respostas de perguntas frequentes armazenadas no Google Sheets

JSON para Importar

{
  "name": "FAQ Automático com Sheets",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Boas-vindas",
        "parameters": {
          "message": "Olá! Consultando nossa base de FAQ..."
        }
      }
    },
    {
      "id": "sheets_1",
      "type": "google_sheets",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Carregar FAQ",
        "parameters": {
          "operation": "read",
          "spreadsheetId": "1FAQ_Database_XYZ",
          "range": "FAQ!A2:B50",
          "accessToken": "{{google_access_token}}",
          "refreshToken": "{{google_refresh_token}}"
        }
      }
    },
    {
      "id": "variable_1",
      "type": "variable",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Armazenar FAQ",
        "parameters": {
          "variableName": "faq_lista",
          "value": "{{sheets_1.data}}"
        }
      }
    },
    {
      "id": "message_2",
      "type": "message",
      "position": { "x": 900, "y": 100 },
      "data": {
        "label": "Mostrar FAQ",
        "parameters": {
          "message": "📚 Base de FAQ carregada com {{sheets_1.rowCount}} perguntas!\n\nPrimeira pergunta: {{sheets_1.data.0.0}}\nResposta: {{sheets_1.data.0.1}}"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 1100, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "message_1" },
    { "source": "message_1", "target": "sheets_1" },
    { "source": "sheets_1", "target": "variable_1" },
    { "source": "variable_1", "target": "message_2" },
    { "source": "message_2", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: Olá! Consultando nossa base de FAQ...
Sistema: 📚 Base de FAQ carregada com 48 perguntas!

Primeira pergunta: Qual o horário de funcionamento?
Resposta: Funcionamos de segunda a sexta, das 8h às 18h.

Resposta do Node

{
  "success": true,
  "data": [
    ["Nome", "Email", "Telefone", "Cidade"],
    ["José Silva", "jose@email.com", "11987654321", "São Paulo"],
    ["Maria Santos", "maria@email.com", "11976543210", "Rio de Janeiro"]
  ],
  "rowCount": 3
}

Boas Práticas

✅ SIM:

  • Sempre especifique o range exato para evitar leitura desnecessária de dados
  • Use ranges nomeados (ex: "Clientes!A:D") para melhor organização
  • Armazene tokens OAuth2 de forma segura (variáveis de ambiente)
  • Trate erros de autenticação e permissão adequadamente
  • Use a primeira linha como cabeçalho e comece leitura de dados em A2
  • Limite o range para melhorar performance (evite A:Z em planilhas grandes)

❌ NÃO:

  • Não exponha accessToken ou refreshToken em logs
  • Não use range muito amplo se precisa de poucos dados
  • Não esqueça de renovar tokens expirados
  • Não presuma que a planilha tem dados - sempre verifique rowCount
  • Não faça múltiplas leituras se pode ler tudo de uma vez

Dicas

💡 Dica 1 - Range Notation: Use notação A1 corretamente: - A1:B10 = células específicas - A:A = coluna inteira - 1:1 = linha inteira - Sheet1!A1:B10 = especifica a aba

💡 Dica 2 - OAuth Setup: Para configurar OAuth2 Google Sheets: 1. Acesse Google Cloud Console 2. Ative Google Sheets API 3. Crie credenciais OAuth 2.0 4. Configure redirect URI 5. Obtenha Client ID e Client Secret 6. Use fluxo OAuth2 para obter tokens

💡 Dica 3 - Performance: Para planilhas grandes: - Leia apenas as colunas necessárias: A:C ao invés de A:Z - Use range limitado: A1:C100 ao invés de A:C - Cache os resultados em variáveis se usar múltiplas vezes

💡 Dica 4 - Estrutura de Dados: O retorno é array de arrays: 

data[0][0] = primeira linha, primeira coluna
data[1][2] = segunda linha, terceira coluna

💡 Dica 5 - Permissões: A conta Google usada precisa ter permissão de "Visualizar" ou superior na planilha.

Próximo Node

→ SHEETS_WRITE - Escrever dados na planilha → SHEETS_APPEND - Adicionar linhas ao final → SHEETS_CLEAR - Limpar range de células