SHEETS_BATCH_UPDATE - Múltiplas Operações no Google Sheets

O que é este Node?

O SHEETS_BATCH_UPDATE é o node responsável por executar múltiplas operações no Google Sheets em uma única requisição: escrever, formatar, ordenar, criar abas, tudo de uma vez.

Por que este Node existe?

Executar operações separadamente é lento e consome quota da API. O SHEETS_BATCH_UPDATE existe para:

1. Performance: Executar 10+ operações em 1 requisição ao invés de 10
2. Atomicidade: Garantir que todas operações sejam aplicadas ou nenhuma
3. Eficiência: Economizar quota da API Google
4. Complexidade: Realizar operações interdependentes em sequência

Como funciona internamente?

Quando o SHEETS_BATCH_UPDATE é executado, o sistema:

1. Autentica: Valida tokens OAuth2
2. Monta requests: Array de operações a executar
3. Executa batchUpdate: Chama spreadsheets.batchUpdate()
4. Processa em sequência: Google aplica todas as operações
5. Retorna replies: Array de respostas para cada operação
6. Se erro em uma: Toda a operação pode falhar (depende de atomicidade)

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

case 'batch_update':
  const batchResult = await sheets.spreadsheets.batchUpdate({
    spreadsheetId: data.spreadsheetId,
    requestBody: {
      requests: data.requests,  // Array de operações
      includeSpreadsheetInResponse: false,
      responseRanges: [],
      responseIncludeGridData: false,
    },
  });

  return {
    success: true,
    replies: batchResult.data.replies,
    updatedSpreadsheetId: batchResult.data.spreadsheetId,
  };

Quando você DEVE usar este Node?

Use SHEETS_BATCH_UPDATE quando precisar múltiplas operações coordenadas:

Casos de uso

1. Setup Completo: "Criar planilha + formatar + inserir dados + criar gráfico"
2. Relatório Automatizado: "Limpar dados + inserir novos + formatar + ordenar"
3. Manutenção: "Deletar linhas antigas + reordenar + atualizar totais"
4. Template: "Criar múltiplas abas + configurar cada uma"

Quando NÃO usar SHEETS_BATCH_UPDATE

• Operação única simples: Use nodes específicos (SHEETS_WRITE, etc)
• Operações independentes: Não há ganho em agrupar

Parâmetros

Campo	Tipo	Obrigatório	Descrição
operation	string	Sim	Deve ser "batch_update"
spreadsheetId	string	Sim	ID da planilha
requests	array	Sim	Array de operações a executar
accessToken	string	Sim	Token OAuth2
refreshToken	string	Sim	Token OAuth2 refresh

Exemplo 1: Setup Completo de Nova Aba

Objetivo: Criar aba, adicionar cabeçalho, formatar e inserir dados

JSON para Importar

{
  "name": "Setup Completo Nova Aba",
  "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": "Batch Setup",
        "parameters": {
          "operation": "batch_update",
          "spreadsheetId": "1Projeto_XYZ",
          "requests": [
            {
              "addSheet": {
                "properties": {
                  "title": "Dados_Janeiro_2025",
                  "gridProperties": {
                    "rowCount": 1000,
                    "columnCount": 10
                  }
                }
              }
            },
            {
              "updateCells": {
                "range": {
                  "sheetId": 0,
                  "startRowIndex": 0,
                  "endRowIndex": 1,
                  "startColumnIndex": 0,
                  "endColumnIndex": 5
                },
                "rows": [{
                  "values": [
                    { "userEnteredValue": { "stringValue": "ID" } },
                    { "userEnteredValue": { "stringValue": "Nome" } },
                    { "userEnteredValue": { "stringValue": "Email" } },
                    { "userEnteredValue": { "stringValue": "Telefone" } },
                    { "userEnteredValue": { "stringValue": "Status" } }
                  ]
                }],
                "fields": "userEnteredValue"
              }
            },
            {
              "repeatCell": {
                "range": {
                  "sheetId": 0,
                  "startRowIndex": 0,
                  "endRowIndex": 1,
                  "startColumnIndex": 0,
                  "endColumnIndex": 5
                },
                "cell": {
                  "userEnteredFormat": {
                    "backgroundColor": {
                      "red": 0.2,
                      "green": 0.2,
                      "blue": 0.2
                    },
                    "textFormat": {
                      "bold": true,
                      "foregroundColor": {
                        "red": 1,
                        "green": 1,
                        "blue": 1
                      }
                    }
                  }
                },
                "fields": "userEnteredFormat(backgroundColor,textFormat)"
              }
            }
          ],
          "accessToken": "{{google_access_token}}",
          "refreshToken": "{{google_refresh_token}}"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "✅ Aba configurada completamente:\n- Criada\n- Cabeçalho inserido\n- Formatação aplicada"
        }
      }
    },
    {
      "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: ✅ Aba configurada completamente:
- Criada
- Cabeçalho inserido
- Formatação aplicada

Exemplo 2: Limpeza e Reorganização

Objetivo: Limpar dados antigos, inserir novos, ordenar

JSON para Importar

{
  "name": "Limpeza e Reorganização",
  "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": "Batch Operations",
        "parameters": {
          "operation": "batch_update",
          "spreadsheetId": "1Vendas_XYZ",
          "requests": [
            {
              "updateCells": {
                "range": {
                  "sheetId": 0,
                  "startRowIndex": 1,
                  "endRowIndex": 100
                },
                "fields": "*"
              }
            },
            {
              "sortRange": {
                "range": {
                  "sheetId": 0,
                  "startRowIndex": 1,
                  "endRowIndex": 100,
                  "startColumnIndex": 0,
                  "endColumnIndex": 5
                },
                "sortSpecs": [{
                  "dimensionIndex": 3,
                  "sortOrder": "DESCENDING"
                }]
              }
            }
          ],
          "accessToken": "{{google_access_token}}",
          "refreshToken": "{{google_refresh_token}}"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "🔄 Planilha reorganizada:\n- Dados limpos\n- Ordenação aplicada"
        }
      }
    },
    {
      "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: 🔄 Planilha reorganizada:
- Dados limpos
- Ordenação aplicada

Resposta do Node

{
  "success": true,
  "replies": [
    {
      "addSheet": {
        "properties": {
          "sheetId": 123456,
          "title": "Dados_Janeiro_2025"
        }
      }
    },
    {
      "updateCells": {}
    },
    {
      "repeatCell": {}
    }
  ],
  "updatedSpreadsheetId": "1Projeto_XYZ"
}

Boas Práticas

✅ SIM: - Agrupe operações relacionadas logicamente - Teste cada operação separadamente antes de combinar - Use batch para setup inicial de planilhas - Aproveite atomicidade para garantir consistência

❌ NÃO: - Não inclua operações muito complexas sem testar - Não exceda limite razoável (50-100 operações por batch) - Não misture operações completamente independentes

Dicas

💡 Dica 1: Tipos de operações comuns em batchUpdate: - addSheet - Criar aba - deleteSheet - Remover aba - updateCells - Modificar células - repeatCell - Aplicar formatação - sortRange - Ordenar dados - deleteDimension - Remover linhas/colunas - addChart - Criar gráfico

💡 Dica 2: Operações são executadas em sequência. Use essa ordem para operações dependentes.

💡 Dica 3: BATCH_UPDATE é a operação mais poderosa e flexível. Todas as outras tools podem ser implementadas usando batchUpdate.

💡 Dica 4: Consulte API Reference para tipos completos de requests.

Próximo Node

→ SHEETS_READ - Ler dados após batch update → SHEETS_WRITE - Operação simples de escrita → SHEETS_FORMAT - Formatação específica