Google Sheets

1. Visão Geral

O componente Google Sheets (google-sheets) permite criar planilhas, ler, atualizar, adicionar e limpar dados em uma planilha do Google Sheets.

Use quando o fluxo precisa gravar ou consultar dados em uma planilha compartilhada. Só funciona como ação de saída.

2. Pré-requisitos

• Um aplicativo OAuth 2.0 configurado a nível de plataforma (clientId, clientSecret, applicationName — configurados globalmente, não no step).
• Um accessToken e refreshToken válidos da conta do Google com acesso à planilha.
• O ID da planilha (spreadsheetId) a ser usada.

3. Autenticação e Conexão

Campo	Obrigatório	Tipo	Descrição	Exemplo
accessToken	Sim	Texto	Token de acesso OAuth do Google.	Um token OAuth
refreshToken	Sim	Texto	Token de atualização OAuth do Google.	Um refresh token OAuth

⚠️ CONFIRMAR: clientId, clientSecret e applicationName deste componente vêm exclusivamente de uma configuração global da aplicação (não podem ser definidos por fluxo), diferente do componente Google Calendar, que aceita esses campos também no step.

4. Configuração / Operações Suportadas

Campo	Obrigatório	Tipo	Descrição	Exemplo
operation	Sim	Texto: CREATE, CLEAR, UPDATE, APPEND, READ	Operação a ser executada na planilha.	"APPEND"
spreadsheetId	Sim, exceto em CREATE	Texto	ID da planilha (encontrado na URL da planilha do Google).	"1AbCdEfGhIjKlMnOpQrStUvWxYz"
range	Não	Texto	Intervalo de células a considerar.	"Sheet1!A1:C10"
valueInput	Não	Texto	Como os valores enviados são interpretados pelo Google Sheets. Valor padrão: "USER_ENTERED" (como se digitado por um usuário, aplicando formatação/fórmulas).	"RAW"
payload	Sim, em APPEND e UPDATE	Texto (JSON, matriz de linhas)	Os dados a inserir ou atualizar, no formato de lista de linhas, cada linha uma lista de valores.	[["Maria", "maria@exemplo.com"]]

5. Exemplos Práticos

Exemplo simples: adicionar uma nova linha com dados de um cliente em uma planilha.

Entrada:

{
  "cliente": { "nome": "Maria Silva", "email": "maria@exemplo.com" }
}

Configuração do componente:

{
  "componentName": "google-sheets",
  "configurations": {
    "operation": "APPEND",
    "accessToken": "{$.secrets.googleAccessToken}",
    "refreshToken": "{$.secrets.googleRefreshToken}",
    "spreadsheetId": "1AbCdEfGhIjKlMnOpQrStUvWxYz",
    "range": "Clientes!A1",
    "payload": "[[\"{$.body.cliente.nome}\", \"{$.body.cliente.email}\"]]"
  }
}

Resposta:

{
  "spreadsheetId": "1AbCdEfGhIjKlMnOpQrStUvWxYz",
  "updates": { "updatedRange": "Clientes!A5:B5", "updatedRows": 1 }
}

Exemplo avançado: ler um intervalo de dados de uma planilha para processar no fluxo.

Configuração do componente:

{
  "componentName": "google-sheets",
  "configurations": {
    "operation": "READ",
    "accessToken": "{$.secrets.googleAccessToken}",
    "refreshToken": "{$.secrets.googleRefreshToken}",
    "spreadsheetId": "1AbCdEfGhIjKlMnOpQrStUvWxYz",
    "range": "Clientes!A1:B10"
  }
}

Resposta:

{
  "range": "Clientes!A1:B10",
  "values": [
    ["Maria Silva", "maria@exemplo.com"],
    ["João Souza", "joao@exemplo.com"]
  ]
}

6. Erros Comuns e Troubleshooting

Erro / Sintoma	Causa provável	Como resolver
"Missing required environment variables for Google Sheets configuration: ..."	As credenciais globais (clientId/clientSecret/applicationName) não estão configuradas na plataforma.	Configurar as credenciais OAuth a nível de aplicação.
"Operation not specified or invalid."	O campo operation não foi preenchido ou não é reconhecido.	Preencher operation com um dos valores suportados.
"Spreadsheet ID is empty."	O campo spreadsheetId não foi preenchido.	Preencher spreadsheetId com o ID da planilha.
"Payload is empty."	As operações APPEND/UPDATE foram usadas sem o campo payload.	Preencher payload com a matriz de valores a inserir/atualizar.
"Failed to parse payload: ..."	O texto de payload não é um JSON válido no formato esperado.	Revisar o formato do JSON em payload (deve ser uma lista de listas).
"Request to Google Sheets failed: ..."	Erro de comunicação com a API do Google Sheets (permissão, token expirado, planilha inexistente).	Revisar as permissões da conta e a validade dos tokens.