Google Sheets

Tipo: Referência
Para: Engenharia de dados, Desenvolvedor
Na tela: HorusETL › Dataflows › editor do Dataflow

Planilha do Google entra e sai do Dataflow por dois nós: Google Sheet lê uma aba, e Inserir Google Sheet grava o resultado numa aba. Os dois acessam a API do Google com uma conta de serviço (service account), sem o login de uma pessoa.

Na biblioteca	`kind` no YAML	Grupo	Entradas
Google Sheet	`ExtractGoogleSheet`	Cloud	nenhuma
Inserir Google Sheet	`InsertGoogleSheet`	Destinos	uma

Antes de usar

Crie uma conta de serviço num projeto do Google Cloud, com a API do Google Sheets ativada, e baixe a chave em JSON. O botão de ajuda ao lado de Credenciais Google: abre o passo a passo Como Criar Credenciais de Conta de Serviço.
Compartilhe a planilha com o e-mail da conta de serviço (termina em iam.gserviceaccount.com): leitor para o Google Sheet, editor para o Inserir Google Sheet.
No nó, clique em Configurar ao lado de Credenciais Google: e cole o conteúdo do JSON.

Para não repetir a chave em cada nó, guarde o JSON numa variável do Tenant (por exemplo, GOOGLE_JSON) e escreva {GOOGLE_JSON} no lugar da chave. O Agente ETL troca a variável pelo valor antes de chamar o Google.

O ID da planilha está na URL dela: em https://docs.google.com/spreadsheets/d/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms/edit, o ID é 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms.

Google Sheet (leitura)

Na tela	No YAML (`options`)	Tipo	Padrão	Regra
Credenciais Google:	`CredentialsJson`	texto (JSON)	vazio	Obrigatório. Sem ele, o nó falha
sem campo na tela	`CredentialType`	texto	`ServiceAccountJson`	Único valor aceito
ID da Planilha:	`SpreadsheetId`	texto	vazio	Obrigatório
Nome da Aba:	`SheetName`	texto	vazio	Vazio lê a primeira aba visível
Intervalo (opcional):	`Range`	texto	vazio	Notação A1, como `A1:F100`. Vazio lê `A1:ZZZ99999`, ou seja, até a linha 99999. Um intervalo com nome de aba (`Vendas!A1:F100`) vale mais que o Nome da Aba:
Primeira linha como cabeçalho	`FirstRowAsHeader`	booleano	ligado	Desligado, as colunas se chamam `COLUNA_1`, `COLUNA_2`...
Extrair como texto	`ExtractAsString`	booleano	desligado	Ligado, toda coluna vem como texto, do jeito que aparece formatada na planilha

Nome das colunas: o cabeçalho perde acento, fica só com letras, números, espaço e hífen, troca espaço por _ e vai para maiúsculas. Célula vazia vira VAZIO, e nome repetido ganha _1, _2.
Tipos: vêm da primeira linha de dados. Número vira número; texto em yyyy-MM-dd, yyyy-MM-dd HH:mm:ss ou dd/MM/yyyy (com ou sem hora) vira data; o resto vira texto. Valor que não converte para o tipo da coluna chega vazio, sem erro. Se a primeira linha não representa a coluna (número em cima, texto mais abaixo), ligue Extrair como texto e converta depois, num nó SQL (DuckDB).

Inserir Google Sheet (gravação)

Na tela	No YAML (`options`)	Tipo	Padrão	Regra
ID da Planilha:	`SpreadsheetId`	texto	vazio	Obrigatório
Nome da Aba:	`SheetName`	texto	vazio	A aba que recebe os dados. Se não existir, o nó cria
Credenciais Google:	`CredentialJson`	texto (JSON)	vazio	A conta precisa poder editar a planilha
Modo de Escrita:	`WriteMode`	texto	`Overwrite`	Sobrescrever (`Overwrite`) ou Adicionar ao final (`Append`)

A chave da credencial muda de nome entre os dois nós: CredentialsJson na leitura e CredentialJson na gravação.

Modo	O que acontece na aba
Sobrescrever	Apaga todo o conteúdo da aba, grava o cabeçalho na linha 1 e as linhas em seguida
Adicionar ao final	Com a aba vazia, grava o cabeçalho e as linhas. Com a aba preenchida, confere se o cabeçalho é o mesmo do Dataflow, coluna por coluna, e acrescenta as linhas no fim

WARNING

Sobrescrever apaga tudo o que está na aba antes de gravar, inclusive o que alguém digitou à mão. Use uma aba só para o Dataflow.

No modo Adicionar ao final, um cabeçalho diferente falha o nó com "Divergência de cabeçalhos na planilha 'Vendas'. Existente: [...], Entrada: [...]. Use o modo Sobrescrever ou garanta que os cabeçalhos coincidam." O cabeçalho gravado usa os nomes das colunas que chegam ao nó.

O nó aceita uma entrada só, e não grava no HorusDW: para o dado chegar a um Dashboard, o Dataflow precisa de um nó Inserir no DW.

Exemplo

yaml

- internalId: ler_metas
  kind: ExtractGoogleSheet
  description: Metas mensais
  inputs: []
  options:
    CredentialType: ServiceAccountJson
    CredentialsJson: "{GOOGLE_JSON}"
    SpreadsheetId: 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms
    SheetName: Metas
    Range: ""
    FirstRowAsHeader: true
    ExtractAsString: false

Relacionado

Pelo Lumo CLI

O nó também pode ser escrito e versionado em YAML. Veja a referência de flow.

Google Sheets ​

Antes de usar ​

Google Sheet (leitura) ​

Inserir Google Sheet (gravação) ​

Exemplo ​