Pular para conteúdo

SHEETS_GET_VALUES - Buscar Valores Específicos do Google Sheets

O que é este Node?

O SHEETS_GET_VALUES é o node responsável por buscar valores de múltiplos ranges em uma única requisição, otimizando performance quando precisa ler dados de áreas diferentes.

Por que este Node existe?

Buscar múltiplos ranges separadamente é ineficiente. O SHEETS_GET_VALUES existe para:

  1. Performance: Reduzir número de requisições à API
  2. Dados Dispersos: Buscar células não adjacentes em uma chamada
  3. Relatórios: Coletar métricas de diferentes partes da planilha
  4. Otimização: Usar quota da API de forma eficiente

Como funciona internamente?

Quando o SHEETS_GET_VALUES é executado, o sistema:

  1. Autentica: Valida tokens OAuth2
  2. Prepara ranges: Lista de múltiplos ranges a buscar
  3. Executa batchGet: Chama spreadsheets.values.batchGet()
  4. Retorna múltiplos resultados: Array com dados de cada range
  5. Se erro: Lança exceção

Código interno (baseado na API Google Sheets): 

case 'get_values':
  const getValuesResult = await sheets.spreadsheets.values.batchGet({
    spreadsheetId: data.spreadsheetId,
    ranges: data.ranges,  // Array de strings: ['Sheet1!A1:B10', 'Sheet2!C5']
  });

  return {
    success: true,
    valueRanges: getValuesResult.data.valueRanges.map((vr: any) => ({
      range: vr.range,
      values: vr.values || [],
      rowCount: vr.values?.length || 0,
    })),
  };

Quando você DEVE usar este Node?

Use SHEETS_GET_VALUES quando precisar ler múltiplas áreas diferentes:

Casos de uso

  1. Dashboard: "Buscar KPIs de células A1, B5, C10 em uma chamada"
  2. Relatório Consolidado: "Ler totais de múltiplas abas"
  3. Validação: "Verificar valores de células específicas dispersas"
  4. Comparação: "Buscar métricas de diferentes períodos"

Quando NÃO usar SHEETS_GET_VALUES

  • Área contígua única: Use NODE SHEETS_READ (mais simples)
  • Toda planilha: Use SHEETS_READ com range amplo

Parâmetros

Campo Tipo Obrigatório Descrição
operation string Sim Deve ser "get_values"
spreadsheetId string Sim ID da planilha
ranges array Sim Array de ranges em notação A1
accessToken string Sim Token OAuth2
refreshToken string Sim Token OAuth2 refresh

Exemplo 1: Buscar KPIs de Dashboard

Objetivo: Coletar métricas dispersas em uma única requisição

JSON para Importar

{
  "name": "Buscar KPIs Múltiplos",
  "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": "Buscar Métricas",
        "parameters": {
          "operation": "get_values",
          "spreadsheetId": "1Dashboard_XYZ",
          "ranges": [
            "Dashboard!B2",
            "Dashboard!D2",
            "Dashboard!F2",
            "Vendas!A1:A10",
            "Produtos!B5:C5"
          ],
          "accessToken": "{{google_access_token}}",
          "refreshToken": "{{google_refresh_token}}"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Mostrar Métricas",
        "parameters": {
          "message": "📊 KPIs coletados:\n\nVendas Hoje: {{sheets_1.valueRanges.0.values.0.0}}\nClientes: {{sheets_1.valueRanges.1.values.0.0}}\nTaxa Conversão: {{sheets_1.valueRanges.2.values.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" }
  ]
}

Saída esperada: 

Sistema: 📊 KPIs coletados:

Vendas Hoje: 45
Clientes: 320
Taxa Conversão: 23%

Exemplo 2: Comparar Dados de Múltiplas Abas

Objetivo: Buscar totais de vendas de diferentes meses

JSON para Importar

{
  "name": "Comparar Vendas Mensais",
  "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": "Buscar Totais",
        "parameters": {
          "operation": "get_values",
          "spreadsheetId": "1Vendas_Ano_XYZ",
          "ranges": [
            "Janeiro!E100",
            "Fevereiro!E100",
            "Março!E100"
          ],
          "accessToken": "{{google_access_token}}",
          "refreshToken": "{{google_refresh_token}}"
        }
      }
    },
    {
      "id": "variable_1",
      "type": "variable",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Calcular Média",
        "parameters": {
          "variableName": "media_trimestre",
          "value": "{{(sheets_1.valueRanges.0.values.0.0 + sheets_1.valueRanges.1.values.0.0 + sheets_1.valueRanges.2.values.0.0) / 3}}"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Resultado",
        "parameters": {
          "message": "📈 Vendas Trimestre:\n\nJan: R$ {{sheets_1.valueRanges.0.values.0.0}}\nFev: R$ {{sheets_1.valueRanges.1.values.0.0}}\nMar: R$ {{sheets_1.valueRanges.2.values.0.0}}\n\nMédia: R$ {{media_trimestre}}"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 900, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "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: 📈 Vendas Trimestre:

Jan: R$ 150000
Fev: R$ 165000
Mar: R$ 180000

Média: R$ 165000

Resposta do Node

{
  "success": true,
  "valueRanges": [
    {
      "range": "Dashboard!B2",
      "values": [["45"]],
      "rowCount": 1
    },
    {
      "range": "Dashboard!D2",
      "values": [["320"]],
      "rowCount": 1
    },
    {
      "range": "Dashboard!F2",
      "values": [["23%"]],
      "rowCount": 1
    }
  ]
}

Boas Práticas

✅ SIM: - Agrupe buscas de múltiplas áreas em uma chamada - Use notação A1 clara para cada range - Limite a 100 ranges por requisição (limite da API) - Acesse resultados por índice: valueRanges[0], valueRanges[1]

❌ NÃO: - Não use para área contígua única (use SHEETS_READ) - Não exceda limite de 100 ranges - Não confunda ordem dos resultados (segue ordem do array ranges)

Dicas

💡 Dica 1: GET_VALUES é perfeito para dashboards onde precisa buscar KPIs de diferentes células.

💡 Dica 2: Resultados mantêm mesma ordem do array ranges. valueRanges[0] corresponde a ranges[0].

💡 Dica 3: Para acessar valor específico: valueRanges[0].values[0][0] = primeira célula do primeiro range.

Próximo Node

→ SHEETS_READ - Ler área contígua única → SHEETS_BATCH_UPDATE - Múltiplas operações de escrita