BigQuery do cliente e Sheets por conta de serviço

Selo de estado: Preview (teto atual do produto) · Curso ACD-210 — Conectores e conexões · Aula 5 de 8 · Atualizado em 2026-10-04.

Objetivo#

Ao final desta aula você vai configurar SA; distinguir projeto de dados × billing — e autorizar uma planilha por compartilhamento, sem pedir a senha do Google de ninguém.

Vídeo#

Identificador no manifesto: acd-210-05-bigquery-e-google-sheets · duração-alvo 8 min · tela do produto: /conexoes.

Roteiro de gravação (6 capítulos):

Conteúdo#

Os dois conectores desta aula são Disponível (maturidade GA-candidato) e compartilham a mesma ideia: autenticação por conta de serviço do Google, não por usuário e senha.

BigQuery: os seis campos que importam

Projeto de dados × projeto de billing

É a distinção que decide quem paga e qual IAM conceder. Os jobs de consulta do BigQuery são cobrados no projeto onde rodam, não onde os dados estão.

Os dois sintomas de IAM são inconfundíveis quando você conhece a divisão: Access Denied: … dataViewer é falta de leitura no projeto de dados; User does not have bigquery.jobs.create é falta de jobUser no projeto de billing.

Na carga, o produto cria o job de consulta e faz um probe de 1 linha (descartada) para validar SQL e partição antes de enviar qualquer fragmento — assim um retry nunca duplica dado na landing. Tabelas com require_partition_filter são tratadas automaticamente: o produto monta um predicado que cobre todas as linhas, em vez de falhar. O filtro incremental usa parâmetro nomeado (@since), nunca concatenação.

Google Sheets: autorização por compartilhamento

O Sheets não pede senha do Google nem acesso ao Drive inteiro. Você compartilha a planilha com o e-mail de uma conta de serviço, com permissão de Leitor.

Com saMode = plataforma você não cola chave nenhuma: a tela mostra o e-mail da conta de serviço a autorizar, e o seu único trabalho é compartilhar a planilha com ele. Com saMode = propria, você traz a sua própria conta de serviço e cola o JSON. O "Testar conexão" indica o e-mail a autorizar e, quando a autorização existe, a descoberta lista as abas e colunas.

Cada aba vira uma tabela na Bronze. Uma aba renomeada não derruba as demais: o erro fica naquela tabela e o laço segue.

Limites e custo

• Paginação: teto duro por execução (default 10.000 páginas / 5.000.000 linhas), com guarda anti-loop.
• BigQuery: extração fragmentada com batchSize default 5.000 (100–50.000) e maxRows default 200.000 (até 5.000.000).
• Sheets: paginação por janela de linhas, com checkpoint; carga SaaS default batchSize 5.000, maxRows 200.000 por recurso.
• Quem paga o quê: as consultas ao seu BigQuery são cobradas no seu projeto de billing (modelo on-demand). A carga para a Bronze consome load job do lado do produto. Custo faturado real = NÃO MEDIDO. A leitura da planilha é R$ 0.

No workspace Aurora Varejo

A Comércio Aurora já tem exportações de marketing num BigQuery próprio: projeto de dados aurora-dados-example, custos centralizados em aurora-billing-example. Maria escolhe billingMode = separate, informa os dois Project IDs, dataset = marketing, location = southamerica-east1 e cola o JSON de uma conta de serviço de treino. O teste volta User does not have bigquery.jobs.create — faltou roles/bigquery.jobUser no projeto de billing, não no de dados. Concedido o papel, a descoberta lista as tabelas.

Em paralelo, a planilha Metas 2026 (sintética) fica com saMode = plataforma: Maria copia o e-mail da conta de serviço que a tela mostra, compartilha a planilha como Leitor e deixa sheetTitles vazio para trazer todas as abas, com headerRow = 1.

Erros comuns

Faça você mesmo#

No workspace de treino Aurora Varejo, como dono, com uma planilha sintética sua e identificadores *-example.

1. Crie uma planilha de treino com duas abas (Metas e Filiais), cabeçalho na linha 1 e três linhas fictícias em cada.
2. Em /conexoes, use Nova conexão → Google Sheets. Cole o link da planilha no campo spreadsheet e confirme que o produto aceita o link (sem você extrair o ID).
3. Deixe saMode = plataforma, copie o e-mail da conta de serviço que a tela mostra e compartilhe a planilha com ele como Leitor.
4. Deixe sheetTitles vazio e headerRow = 1. Use Testar conexão e confirme que a descoberta lista as duas abas, com as colunas do cabeçalho.
5. Agora preencha sheetTitles com um nome de aba inexistente (Vendas) e teste de novo: registre a diferença na descoberta. Depois volte a deixar vazio e salve com Salvar conexão.
6. Abra uma segunda tentativa, agora BigQuery, e preencha projectId = aurora-dados-example. Alterne billingMode entre same e separate e confirme que o campo Projeto de billing só aparece em separate.
7. Escreva, em duas linhas, qual papel IAM você pediria em qual projeto para esse cenário (dataViewer em dados, jobUser em billing) — e Cancele a tentativa, sem salvar.

Você terminou quando a conexão do Sheets está salva com as duas abas descobertas via compartilhamento (sem nenhuma senha do Google), e você sabe dizer, sem consultar, qual dos dois papéis IAM vai em qual dos dois projetos do BigQuery.

Checagem rápida#

Três perguntas no final da aula, corrigidas no servidor. A aula só conta como concluída depois da checagem.

Documentação relacionada#

• data/tutoriais/conectar-bigquery
• data/conectores/bigquery
• data/conectores/google_sheets
• data/custo-limites-seguranca — tetos e custo por workspace

Capacidades ensinadas#

C04.1 — o selo exibido na aula é sempre o estado mais conservador entre as capacidades citadas; nada aqui é "GA".