Skip to main content
O conector Google Sheets carrega cada aba das planilhas que você escolhe como uma tabela no Data Catalog, com as colunas do cabeçalho da aba. Cada linha carrega a lista de pessoas e grupos que podem abrir a planilha no Google Drive.

​
Capacidades

  • Data Catalog. Cada aba vira uma tabela na camada raw, com uma coluna por título do cabeçalho. Você escolhe as planilhas, liga e desliga abas e marca colunas com dados pessoais no Data Catalog.
  • Permissão da fonte. O compartilhamento de cada planilha no Drive é lido a cada sincronização e gravado em todas as linhas das abas dela. No modo “Espelhar a fonte”, cada pessoa vê só as linhas das planilhas que ela pode abrir.
  • Carga só do que mudou. Uma aba só é relida quando a planilha foi editada, o compartilhamento mudou, a marcação de dados pessoais mudou ou passaram 24 horas desde a última carga.
O conector entrega só a camada raw. Ele não traz modelos da camada clean nem mapeamento para o Memory, porque as tabelas têm a forma que você deu às suas planilhas. Esses modelos são escritos depois da primeira carga, sobre as tabelas que você escolheu.

​
Recursos disponíveis

Os recursos não têm nome fixo. Cada aba das planilhas no escopo vira um recurso, descoberto a cada sincronização. Só abas de grade viram tabela. Abas que contêm só um gráfico ou uma imagem, e abas de dados conectados (Connected Sheets), ficam de fora. Uma aba oculta entra como qualquer outra.

​
Nome da tabela

O nome junta o título da planilha e o título da aba, separados por __. Cada parte é escrita em minúsculas, sem acento, com _ no lugar de espaços e símbolos, sem _ repetido nem nas pontas, e cortada em 48 caracteres. Por exemplo, a aba “Pedidos” da planilha “Vendas 2026” vira vendas_2026__pedidos, e o nome para consultas SQL é:
O __ entre a planilha e a aba continua no nome público. Só a separação entre o conector e o recurso vira ponto. Quando um título não tem nenhum caractere que sobreviva às regras, como um título só com emoji, a parte da planilha vira spreadsheet_ seguido dos 8 primeiros caracteres do id da planilha, e a parte da aba vira sheet_ seguido do id da aba (sheet_0). A descrição da tabela no Data Catalog traz os títulos originais, com acento e maiúsculas, no formato Vendas 2026 › Pedidos, seguidos do idioma (locale) e do fuso (timeZone) da planilha. Renomear na origem troca a tabela. Se você renomeia a planilha ou a aba no Google Sheets, a tabela passa a ter o nome novo na sincronização seguinte. A tabela antiga sai do catálogo, junto com os modelos da camada clean construídos sobre ela. A nova herda a seleção, as colunas desligadas e as marcações de dados pessoais da antiga, e é carregada inteira. O resumo da execução avisa a troca, e quem mantém a camada clean precisa trocar o nome antigo pelo novo no SQL. Duas abas com o mesmo nome. Se duas abas no escopo chegam ao mesmo nome, como “Jan/24” e “Jan-24” na mesma planilha, ou duas planilhas “Sem título” com uma aba “Página1”, a aba que já tinha o nome fica com ele. A outra mantém o nome anterior, se tinha um, ou não é carregada. O resumo da execução avisa, e você resolve renomeando uma delas na planilha.

​
Colunas

A linha 1 é sempre o cabeçalho. Cada título vira o nome de uma coluna, com as mesmas regras do nome da tabela, e o texto original fica na descrição da coluna. A coluna _row_number é o número da linha na planilha. O cabeçalho é a linha 1, então o primeiro dado tem _row_number 2. Ela serve para achar a linha na planilha e não é chave. Uma aba só com o cabeçalho vira uma tabela com as colunas e nenhuma linha. Uma aba com a linha 1 em branco não aparece no Data Catalog até ganhar um cabeçalho.

​
Valores

Toda coluna é texto. O conector não infere tipo. O idioma e o fuso da planilha ficam na descrição da tabela, para a camada clean converter datas e números. Uma linha mais curta que o cabeçalho tem nulo nas colunas que faltam. Uma linha inteiramente vazia é ignorada. Numa célula mesclada, o valor fica só na primeira célula da mescla.

​
Quando as colunas mudam

  • Uma coluna nova entra na tabela na próxima vez que a aba é relida.
  • Uma coluna removida da planilha continua na tabela, com nulo, e no Data Catalog, com missing in source no começo da descrição. Ela sai quando você a exclui no Data Catalog.
  • Uma coluna renomeada conta como uma removida e uma nova. O conector casa as colunas pelo nome, não pela posição.

​
Dados pessoais

O conector não marca nenhuma coluna como dado pessoal. Você marca no Data Catalog, que sugere colunas pelo nome. Até a marcação, a coluna é carregada sem máscara. Mudar a marcação faz a aba ser relida na sincronização seguinte.

​
Permissões (ACL)

O conector lê a permissão de cada item na fonte e a guarda junto com o dado. Em Comportamento dos dados, você escolhe entre dois modos: No modo “Espelhar a fonte”, a Strattum reconhece cada pessoa pelo e-mail com que a planilha foi compartilhada com ela. O conector grava esse e-mail como uma identidade do Google Sheets, ligada a esta conexão, e assume que a pessoa usa o mesmo e-mail na Strattum. O Google Sheets não tem a opção Exigir login na fonte como prova de identidade.

​
Como a fonte define acesso

No Google Sheets, o acesso é o compartilhamento da planilha no Google Drive. Uma planilha pode ser compartilhada com uma pessoa, com um Grupo do Google, com um domínio do Google Workspace ou com qualquer pessoa que tenha o link. Não há permissão por aba nem por linha.

​
Como a Strattum traduz o acesso

Para cada planilha, o conector lê o compartilhamento e grava os leitores em todas as linhas de todas as abas dela. O papel não importa: Leitor, Comentarista e Editor leem a planilha. Um compartilhamento que não é traduzido não afeta os outros. Por exemplo, uma planilha compartilhada com duas pessoas e com o domínio de um parceiro fica com as duas pessoas. A Service Account precisa ser Editor. O Drive só mostra o compartilhamento de uma planilha a quem pode alterá-lo. Com a Service Account como Leitor, o conector lê os dados, mas não o compartilhamento, e grava as linhas sem nenhum leitor. No modo “Espelhar a fonte”, essas linhas ficam invisíveis para todos. No modo “Aberto”, ficam visíveis para quem pode usar o conector. O teste de conexão e o resumo da execução apontam as planilhas nesse caso. Se o dono da planilha desligou a opção que permite a editores alterar o compartilhamento, o mesmo acontece com a Service Account como Editor. Domínio do Workspace. O domínio vem só do campo Domínio do Workspace do conector, nunca do dono da planilha. Com o campo vazio, todo compartilhamento com domínio é ignorado, e quem tem acesso só pelo domínio não vê a planilha no modo “Espelhar a fonte”. O teste de conexão mostra o domínio que mais aparece nos compartilhamentos e quantas planilhas ele cobre, para você preencher o campo. Informe só o domínio principal da empresa. Se o Workspace tem mais de um domínio, só o informado é reconhecido. Grupos. Para gravar um grupo, a Service Account precisa ler os membros dele na Cloud Identity API. Isso exige o papel de admin Groups Reader atribuído à Service Account no Google Workspace e a Cloud Identity API ativa no projeto. A cada sincronização, o conector confere cada grupo com acesso às planilhas do escopo, inclusive os grupos dentro dele, até 10 níveis. Um grupo que não pode ser lido, como um grupo de outra empresa ou de um Workspace sem o papel atribuído, não é gravado, e o resumo da execução mostra quantos grupos ficaram de fora. O Google Workspace não é obrigatório: sem ele, só os compartilhamentos com pessoas e com link valem.

​
Quando a identidade não é encontrada

No modo “Espelhar a fonte”, uma pessoa não vê a planilha quando:
  • o e-mail dela na Strattum é diferente do e-mail com que a planilha foi compartilhada;
  • o acesso dela vem de um grupo que a Service Account não consegue ler;
  • o acesso dela vem do domínio e o Domínio do Workspace está vazio ou tem outro domínio.
A planilha continua visível para os outros leitores.

​
Quando a permissão é atualizada

O compartilhamento de cada planilha é lido de novo em toda sincronização, mesmo quando a planilha não foi editada. Quando os leitores mudam, as abas da planilha são relidas e regravadas com os leitores novos. Uma mudança de compartilhamento chega às linhas na sincronização seguinte. Os membros de cada grupo são lidos por uma rotina própria, a cada 10 minutos por padrão. Se a leitura do compartilhamento falha por erro do Google, as abas daquela planilha não são relidas naquela sincronização. As linhas ficam como estavam, sem os grupos que deixaram de poder ser lidos, e a planilha é tentada de novo na sincronização seguinte.

​
Pré-requisitos

  • Um projeto no Google Cloud com a Google Sheets API e a Google Drive API ativas.
  • Uma Service Account nesse projeto.
  • No modo Chave JSON: uma chave JSON da Service Account.
  • No modo Sem chave: a Strattum rodando no Google Cloud, com credenciais padrão do Google no servidor, ou na AWS, com Workload Identity Federation. A identidade do servidor precisa do papel roles/iam.serviceAccountTokenCreator na Service Account, e a API IAM Service Account Credentials (iamcredentials.googleapis.com) precisa estar ativa no projeto da Service Account.
  • As planilhas, ou as pastas que as contêm, compartilhadas com o e-mail da Service Account como Editor.
  • Opcional, para grupos: a Cloud Identity API ativa no projeto e o papel Groups Reader atribuído à Service Account por um super administrador do Google Workspace.
O conector não usa delegação em todo o domínio (domain-wide delegation) nem login de usuário. A Service Account age em nome dela mesma.

​
Autenticação e escopos

O conector se autentica como a Service Account, com a chave JSON ou sem chave. Todos os escopos são de leitura. Como não há delegação, nada precisa ser autorizado no Admin Console do Google Workspace além do papel Groups Reader.
1

Ative as APIs

No Google Cloud Console, acesse APIs & Services > Library e ative a Google Sheets API e a Google Drive API. Para grupos, ative também a Cloud Identity API. No modo sem chave, ative a IAM Service Account Credentials API.
2

Crie a Service Account

Acesse IAM & Admin > Service Accounts e clique em Create Service Account. Dê um nome, como strattum-sheets-reader. Não é preciso atribuir papéis do IAM.
3

Gere a chave JSON (modo Chave JSON)

Clique no e-mail da Service Account, abra a aba Keys, clique em Add key > Create new key, escolha JSON e clique em Create. O arquivo é baixado uma única vez. Se a criação for bloqueada pela política iam.disableServiceAccountKeyCreation, um administrador da organização no Google Cloud precisa liberar o projeto, ou use o modo sem chave.
4

Autorize o servidor (modo Sem chave)

Na Service Account, abra Permissions e conceda roles/iam.serviceAccountTokenCreator à identidade do servidor da Strattum: a conta de serviço da VM no Google Cloud, ou a identidade federada do papel da instância na AWS.
5

Compartilhe as planilhas

No Google Sheets ou no Drive, compartilhe cada planilha, ou a pasta que as contém, com o e-mail da Service Account (formato nome@projeto.iam.gserviceaccount.com), com papel Editor.
6

Atribua o papel Groups Reader

Opcional, para grupos. No Admin Console do Google Workspace, como super administrador, acesse Account > Admin roles, abra o papel Groups Reader, clique em Assign admin > Assign service accounts e informe o e-mail da Service Account.

​
Onde a chave fica e como trocá-la

A chave JSON fica no cofre de credenciais da sua instalação da Strattum, o backend definido em SECRET_BACKEND: um arquivo no servidor (json_file, o padrão), AWS Secrets Manager, GCP Secret Manager ou Azure Key Vault. O Console nunca mostra a chave de volta. Na revisão do assistente ela aparece mascarada, e na edição aparece só o e-mail da Service Account da chave atual. Para trocar a chave:
  1. Gere uma chave nova na Service Account, como no passo “Gere a chave JSON”.
  2. No Console, abra o conector, vá a Conexão, cole a chave nova em Service Account JSON e clique em Testar Conexão.
  3. Salve. A chave nova substitui a antiga no cofre.
  4. No Google Cloud, apague a chave antiga na aba Keys da Service Account.
Na edição, qualquer salvamento exige colar a chave de novo e testar a conexão, mesmo que só a frequência ou o acesso tenham mudado. Se você muda para o modo Sem chave e salva, a chave guardada é removida.

​
Configuração no Console

O link Guia de configuração, ao lado da escolha de autenticação, abre esta página.
1

Preencha a conexão

Nome do Conector (Opcional): um nome para identificar esta instância. O padrão é “Google Sheets”.Autenticação (Obrigatório): escolha Chave JSON ou Sem chave. Nenhum dos dois vem marcado.Service Account JSON (Quando selecionado “Chave JSON”, obrigatório): cole o conteúdo do arquivo JSON ou clique em Carregar arquivo.E-mail da conta de serviço (Quando selecionado “Sem chave”, obrigatório): o e-mail da Service Account, terminado em .gserviceaccount.com.Endereço da federação (só AWS, opcional) (Opcional, só no modo “Sem chave”): o provedor do pool de Workload Identity Federation, no formato //iam.googleapis.com/projects/NÚMERO/locations/global/workloadIdentityPools/POOL/providers/PROVEDOR. Fora da AWS, deixe vazio.Domínio do Workspace (opcional) (Opcional): o domínio principal da empresa, como empresa.com.br. Sem ele, compartilhamentos com o domínio são ignorados.Clique em Testar Conexão. O Console só avança depois de um teste sem erro. O teste confere a credencial e a listagem de planilhas no Drive. Ele também confere o compartilhamento de até 10 planilhas e até 5 grupos, e mostra avisos que não bloqueiam: nenhuma planilha visível, planilhas com a Service Account como Leitor, domínio sugerido e grupos que não podem ser lidos.
2

Defina a frequência

Frequência de Sincronização (Obrigatório): o recomendado é A cada 1h (recomendado). Também há opções prontas, de 10 minutos a semanal, e Personalizado, para informar uma Expressão Cron. Os horários são em UTC.
3

Configure acesso e visibilidade

Quem pode usar este conector (Obrigatório): “Todos os usuários” ou “Apenas times específicos”. Na segunda opção, selecione os Times com acesso.Comportamento dos dados (Obrigatório): “Aberto” ou “Espelhar a fonte”.
4

Revise e salve

Na revisão, Planilhas mostra “Escolha no Data Catalog”. Nada é carregado até você escolher as planilhas.
5

Escolha as planilhas no Data Catalog

No Data Catalog, abra o conector e, em Planilhas no contexto, marque as planilhas que entram e salve.
  • Ao salvar, as abas existentes de cada planilha marcada são ligadas. Uma aba criada depois começa desligada: ligue-a no Data Catalog.
  • Cada salvamento aceita até 20 planilhas novas. Para mais, salve em partes.
  • Desmarcar uma planilha tira as tabelas dela do lake, com as linhas já carregadas e os modelos da camada clean construídos sobre elas.
Salvar não dispara uma carga. As tabelas são carregadas na próxima sincronização.

​
Como a sincronização funciona

O agendamento recomendado roda de hora em hora. Uma planilha que não mudou custa só chamadas ao Drive, para a data de modificação e o compartilhamento, sem gastar a cota do Google Sheets. Descoberta. Para cada planilha do escopo, o conector consulta a data de modificação no Drive (modifiedTime). Se ela não mudou, as abas e as colunas da última descoberta são mantidas. Se mudou, o conector lê as abas da planilha e a linha 1 de cada aba. Cada aba ligada. A aba só é pulada quando, desde a última carga dela, nada disto mudou: a data de modificação da planilha, os leitores gravados para a planilha e a marcação de dados pessoais da aba, e a última carga tem menos de 24 horas. Em qualquer outro caso, a aba é lida inteira, em fatias de 5.000 linhas, e gravada num arquivo temporário. Só depois de lida inteira ela substitui a tabela. Se a leitura falha no meio, nada é gravado e a tabela anterior fica. Carga completa a cada 24 horas. Fórmulas como NOW(), RAND(), IMPORTRANGE e GOOGLEFINANCE mudam de valor sem mudar a data de modificação da planilha. O valor delas na tabela só é atualizado na carga completa de 24 horas, ou quando a planilha é editada. Linhas apagadas. Como a aba é regravada inteira, uma linha apagada na planilha sai da tabela na próxima vez que a aba é relida. Planilha ou aba indisponível. Se uma planilha do escopo foi apagada, foi para a lixeira ou deixou de ser compartilhada com a Service Account, ou se uma aba ligada sumiu, a tabela fica no Data Catalog com unavailable in source no começo da descrição. As linhas ficam, mas sem nenhum leitor. No modo “Espelhar a fonte”, elas ficam invisíveis até você tirar a planilha do escopo ou desligar a tabela. Depois das cargas, a camada clean é reconstruída, quando há modelos sobre estas tabelas.

​
API da fonte

O conector usa a Google Sheets API v4, a Google Drive API v3 e a Cloud Identity API v1, por HTTP. Rate limits. Limite da API: o Google Sheets aceita 300 leituras por minuto por projeto e 60 leituras por minuto por usuário por projeto. Para o conector, o usuário é a Service Account. Estourar a cota devolve 429 (documentação). O Drive tem cotas próprias, contadas à parte (documentação). Comportamento do conector: as leituras do Google Sheets são limitadas a 50 por minuto por processo, e o teste de conexão e o painel do Data Catalog seguem o mesmo limite. O 429 do Sheets não traz Retry-After, então o conector espera a janela de um minuto virar, com até 5 segundos a mais, e repete, até 10 vezes por chamada. No painel do Data Catalog, depois de duas esperas, o salvamento é recusado com a mensagem de cota esgotada e nada é salvo. Para 429 e limite de taxa (403) no Drive, 429 na Cloud Identity e erros 5xx, o conector repete com espera exponencial, até 64 segundos, em até 6 tentativas. Se as tentativas acabam na leitura de uma aba, a sincronização falha, e as abas já gravadas ficam como foram gravadas. Na leitura do compartilhamento, a planilha é adiada para a sincronização seguinte. Na leitura de um grupo, o grupo não é gravado naquela sincronização. Referência oficial: https://developers.google.com/workspace/sheets/api/reference/rest

​
Limitações conhecidas

  • O cabeçalho é sempre a linha 1. Não dá para escolher outra linha.
  • Todos os valores chegam como texto. Datas chegam no formato do idioma da planilha, e a conversão fica para a camada clean.
  • Fórmulas como NOW(), RAND(), IMPORTRANGE e GOOGLEFINANCE só são atualizadas na carga completa de 24 horas ou quando a planilha é editada.
  • Só abas de grade são lidas. Abas de gráfico ou imagem e abas de Connected Sheets ficam de fora, e uma tabela do Google Sheets dentro de uma aba não vira uma tabela própria.
  • Numa célula mesclada, só a primeira célula tem o valor.
  • O nome da tabela segue os títulos da planilha e da aba. Renomear na origem troca a tabela, e o SQL da camada clean precisa ser ajustado.
  • Duas abas que chegam ao mesmo nome não são carregadas juntas. Uma delas fica de fora até ser renomeada.
  • O escopo é por planilha. Não há seleção por pasta nem uma opção para todas as planilhas.
  • Uma aba criada depois que a planilha entrou no escopo começa desligada.
  • Cada salvamento do escopo aceita até 20 planilhas novas.
  • Com a Service Account como Leitor, o compartilhamento não é lido, e no modo “Espelhar a fonte” as linhas da planilha ficam invisíveis.
  • Grupos só são espelhados com o papel Groups Reader, e um grupo de outra empresa nunca é espelhado.
  • Só um domínio do Workspace é reconhecido. Compartilhamentos com outros domínios são ignorados.
  • Não há delegação em todo o domínio, login de usuário nem vínculo de conta.
  • Uma planilha que deixou de estar disponível continua no Data Catalog, sem leitores, até você tirá-la do escopo.
  • Uma coluna removida da planilha continua na tabela, com nulo, até você excluí-la no Data Catalog.
  • Instâncias que usam a mesma Service Account dividem a cota de 60 leituras por minuto do Google e ficam mais lentas.
  • Se a gravação de uma aba grande falha depois das primeiras 100 mil linhas, a tabela pode ficar regravada só em parte até a sincronização seguinte, que grava a aba de novo.

​
Troubleshooting

​
Próximos passos

Data Catalog

Veja como escolher as planilhas, ligar abas e marcar colunas com dados pessoais.

Data Pipelines

Entenda como as camadas raw e clean são construídas a partir das tabelas carregadas.
As credenciais do conector são configuradas pelo Console e guardadas no cofre de credenciais, não no .env. As variáveis abaixo definem onde esse cofre fica.