Pular para conteúdo

SHEETS_UPDATE - Atualizar Células do Google Sheets

O que é este Node?

O SHEETS_UPDATE é o node responsável por atualizar células específicas no Google Sheets. Similar ao SHEETS_WRITE, mas com foco em atualizações pontuais.

Por que este Node existe?

Atualizar células específicas é comum em manutenção de dados. O SHEETS_UPDATE existe para:

  1. Correção de Dados: Ajustar valores específicos sem afetar outros
  2. Atualização de Status: Modificar campo de status em registro
  3. Incrementos: Atualizar contadores ou métricas
  4. Sincronização: Manter dados atualizados com outras fontes

Como funciona internamente?

SHEETS_UPDATE usa a mesma implementação de SHEETS_WRITE com spreadsheets.values.update(). A diferença é semântica - update indica modificação de existente, write indica escrita nova.

Código interno (google-executors.service.ts:768-782): 

case 'update':
case 'write':
  const updateResult = await sheets.spreadsheets.values.update({
    spreadsheetId: data.spreadsheetId,
    range: data.range,
    valueInputOption: 'USER_ENTERED',
    requestBody: {
      values: data.values,
    },
  });

  return {
    success: true,
    updatedCells: updateResult.data.updatedCells,
    updatedRows: updateResult.data.updatedRows,
  };

Quando você DEVE usar este Node?

Use SHEETS_UPDATE quando precisar modificar células existentes específicas:

Casos de uso

  1. Atualizar Status: "Mudar status de 'Pendente' para 'Concluído'"
  2. Correção: "Ajustar preço de produto específico"
  3. Contador: "Incrementar número de visualizações"
  4. Timestamp: "Atualizar data de última modificação"

Quando NÃO usar SHEETS_UPDATE

  • Adicionar linhas novas: Use NODE SHEETS_APPEND
  • Limpar dados: Use NODE SHEETS_CLEAR

Parâmetros

Campo Tipo Obrigatório Descrição
operation string Sim Deve ser "update"
spreadsheetId string Sim ID da planilha
range string Sim Range das células a atualizar
values array Sim Novos valores
accessToken string Sim Token OAuth2
refreshToken string Sim Token OAuth2 refresh

Exemplo 1: Atualizar Status de Pedido

Objetivo: Marcar pedido como enviado

JSON para Importar

{
  "name": "Atualizar Status Pedido",
  "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": "Número Pedido",
        "parameters": {
          "prompt": "Número do pedido enviado:",
          "variableName": "pedido_num"
        }
      }
    },
    {
      "id": "sheets_1",
      "type": "google_sheets",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Atualizar Status",
        "parameters": {
          "operation": "update",
          "spreadsheetId": "1Pedidos_XYZ",
          "range": "Pedidos!E{{pedido_num}}",
          "values": [["Enviado"]],
          "accessToken": "{{google_access_token}}",
          "refreshToken": "{{google_refresh_token}}"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "✅ Pedido {{pedido_num}} marcado como Enviado"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 900, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "input_1" },
    { "source": "input_1", "target": "sheets_1" },
    { "source": "sheets_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Saída esperada: 

Sistema: Número do pedido enviado:
Usuário: 1234
Sistema: ✅ Pedido 1234 marcado como Enviado

Resposta do Node

{
  "success": true,
  "updatedCells": 1,
  "updatedRows": 1
}

Boas Práticas

✅ SIM: - Use range preciso para atualizar apenas o necessário - Valide dados antes de atualizar - Mantenha log de atualizações importantes

❌ NÃO: - Não atualize ranges grandes sem necessidade - Não esqueça de verificar se célula existe

Dicas

💡 Dica 1: UPDATE e WRITE são tecnicamente idênticos. Use UPDATE semanticamente para indicar modificação de existente.

💡 Dica 2: Combine com SHEETS_READ para verificar valor atual antes de atualizar.

Próximo Node

→ SHEETS_WRITE - Escrever dados → SHEETS_READ - Ler antes de atualizar