Documentação · Nuvem

Conectar Google Cloud.

O Google Cloud não oferece uma API que devolva o custo. O caminho oficial é a exportação de billing para o BigQuery: o Google grava o uso e o custo de cada serviço numa tabela do seu projeto, e o GrandeTotal lê essa tabela com uma service account de só leitura. Por isso a conexão tem uma etapa a mais que as outras nuvens.

O que é pedido

A exportação de billing Standard usage cost ativa, gravando num dataset do BigQuery.
Uma service account com BigQuery Data Viewer no dataset da exportação e BigQuery Job User no projeto (para rodar consultas).
Dois valores: o nome da tabela (projeto.dataset.tabela) e a chave JSON da service account.

Dois avisos importantes. (1) A exportação não tem histórico: ela só grava a partir do momento em que é ativada, e os primeiros dados levam algumas horas para aparecer. Se quiser meses de histórico, o Google oferece um pedido de carga retroativa (veja “Histórico” abaixo). (2) Para o custo, a service account não lê o conteúdo dos seus recursos, só a tabela de billing (o inventário opcional, mais abaixo, lê só os metadados).

Antes de começar

Billing: papel Billing Account Administrator na conta de faturamento (para ativar a exportação) e acesso para criar um dataset no BigQuery.
Projeto: um projeto para guardar a exportação (pode ser o projeto que você já usa). Ative a API do BigQuery nele, se ainda não estiver ativa.
Tempo: cerca de 15 minutos; os dados aparecem algumas horas depois.

Passo 1. Crie o dataset da exportação

Console do Google Cloud → BigQuery → no projeto escolhido, ⋮ → Create dataset.
Dataset ID: billing (ou outro nome). Location: escolha uma região (por exemplo, US ou southamerica-east1) e lembre-se dela: a exportação e a leitura usam a mesma.

Passo 2. Ative a exportação de billing para o BigQuery

Menu ☰ → Billing → escolha a conta de faturamento → Billing export.
Na aba BigQuery export, na seção Standard usage cost, clique em Edit settings.
Escolha o projeto e o dataset do passo 1 e clique em Save.

O Google cria a tabela gcp_billing_export_v1_<ID_DA_CONTA_DE_FATURAMENTO> (com traços do ID trocados por sublinhados). Ela aparece no dataset em algumas horas, quando o primeiro dado chega. A exportação “Detailed usage cost” (gcp_billing_export_resource_v1_…) também funciona, mas é bem maior; use a padrão.

O que se perde sem “Detailed usage cost” e “Pricing”

O Google oferece três exportações. O GrandeTotal só precisa da Standard usage cost, e as outras duas ficam desligadas sem prejuízo para o painel de hoje.

Detailed usage cost acrescenta o recurso individual (resource.name e resource.global_name: qual VM, disco ou bucket gerou a linha). Sem ela, o custo é por serviço, SKU e projeto, e não por recurso. Você não consegue apontar “esta VM custou X”, nem achar um disco órfão pelo custo. A tabela é bem maior, o que aumenta o custo da consulta no BigQuery.
Pricing exporta a tabela de preços (preço de lista, faixas de uso e preço efetivo por SKU). Sem ela, não dá para comparar o que você pagou com o preço de lista, nem estimar quanto custaria trocar de configuração ou de faixa. Ela não traz nenhum custo seu, só preços.
O que continua funcionando: custo diário e mensal por serviço, créditos e descontos, conversão para reais, tendências e a análise dos agentes. A Standard tem tudo isso.

Se um dia você quiser custo por recurso, ative a Detailed e informe a tabela gcp_billing_export_resource_v1_…. Essa visão ainda não existe no painel. A exportação só vale a partir da ativação, então ligá-la cedo guarda o histórico para quando ela for usada.

Passo 3. Crie a service account

Menu ☰ → IAM & Admin → Service Accounts → Create service account, no mesmo projeto.
Name: grandetotal-leitura. Clique em Create and continue.
No passo “Grant this service account access to project”, escolha o papel BigQuery Job User (ele permite apenas rodar consultas; não dá acesso a dados). Clique em Done.
Copie o e-mail da conta (grandetotal-leitura@SEU-PROJETO.iam.gserviceaccount.com).

Passo 4. Dê leitura só ao dataset da exportação

Em BigQuery, clique no dataset billing → Sharing → Permissions → Add principal.
Em New principals cole o e-mail da service account; em Role escolha BigQuery Data Viewer; clique em Save.

Por linha de comando, os passos 3 e 4 ficam assim (troque SEU-PROJETO):

gcloud iam service-accounts create grandetotal-leitura --project SEU-PROJETO

gcloud projects add-iam-policy-binding SEU-PROJETO \
  --member "serviceAccount:grandetotal-leitura@SEU-PROJETO.iam.gserviceaccount.com" \
  --role roles/bigquery.jobUser

bq add-iam-policy-binding \
  --member "serviceAccount:grandetotal-leitura@SEU-PROJETO.iam.gserviceaccount.com" \
  --role roles/bigquery.dataViewer SEU-PROJETO:billing

Passo 5. Crie a chave JSON

IAM & Admin → Service Accounts → clique na conta → aba Keys → Add key → Create new key.
Escolha JSON e Create. O arquivo é baixado uma única vez; guarde-o.

Se o botão estiver bloqueado, a sua organização aplica a política iam.disableServiceAccountKeyCreation. Um administrador da organização precisa liberá-la para esse projeto.
A chave JSON dá acesso de leitura a essa tabela, então trate-a como senha: não a envie por e-mail ou chat; cole só no formulário do GrandeTotal.
Se a chave foi colada em algum lugar indevido (chat, e-mail, repositório), apague-a em Keys (o ID aparece em private_key_id), crie outra e cole só no formulário. Depois de conectar, apague o arquivo baixado.

Passo 6. Descubra o nome da tabela

No BigQuery, expanda o projeto e o dataset billing: a tabela se chama gcp_billing_export_v1_XXXXXX_XXXXXX_XXXXXX. O valor que o painel pede junta tudo com pontos:

SEU-PROJETO.billing.gcp_billing_export_v1_XXXXXX_XXXXXX_XXXXXX

Se a tabela ainda não existe, a exportação ainda não recebeu dados; volte em algumas horas.

Mais de uma conta de faturamento ou de projeto

Vários projetos na mesma conta de faturamento: uma exportação só. Ela traz o custo de todos os projetos ligados à conta (a tabela tem a coluna project.id). Faça os passos uma vez, no projeto que vai guardar o dataset.
Mais de uma conta de faturamento (por exemplo, uma criada pelo Firebase e outra sua): repita o passo 2 para cada conta, apontando todas para o mesmo dataset. Cada uma cria a própria tabela (gcp_billing_export_v1_<ID_DA_CONTA>). A mesma service account lê as duas, sem passos extras. No painel, cole uma tabela por linha (até 5).
Se as contas cobrarem em moedas diferentes (uma em USD e outra em BRL), a conexão avisa e recusa somar. Nesse caso conecte só as tabelas que usam a mesma moeda.
O painel soma por serviço; ainda não separa por projeto.
Projetos com “Billing is disabled” não geram custo e não aparecem na exportação. Para saber quais contas importam, abra ☰ → Billing → Account management: só as contas com projetos vinculados precisam de exportação. Uma conta sem projetos pode ficar de fora. Se um projeto for ligado a ela depois, ative a exportação nela e acrescente a tabela no painel.
Projetos novos ligados a uma conta que já exporta entram sozinhos, sem mexer na conexão.

Tempo de espera e o primeiro dado

A tabela só passa a existir quando o Google grava o primeiro dado, em geral algumas horas e, às vezes, até 24 h depois de ativar a exportação. Antes disso o painel responde “Tabela não encontrada”, e isso é esperado: tente de novo mais tarde.
A exportação só vale a partir da ativação. O Google não preenche o período anterior, então o painel começa vazio e cresce dia a dia.
Confira o nome da tabela em BigQuery Studio antes de colar. Os traços do ID da conta de faturamento viram sublinhados: 01C8DA-535ACB-0BA32D vira 01C8DA_535ACB_0BA32D.

Passo 7. Cole os valores no painel

Em /painel/conectar, clique em Conectar Google Cloud, cole a tabela e o conteúdo inteiro do arquivo JSON, e clique em Verificar e conectar. O GrandeTotal faz o login, roda uma consulta dos últimos dois dias e, se tudo estiver certo, a conexão fica conectada.

Passo 8. Sincronize e confira

Use o botão de sincronizar. O custo de cada dia é a soma de cost mais os credits (descontos e créditos), por serviço, no dia do horário do Pacífico, como o relatório do console do Google.
Compare com Billing → Reports (agrupado por Service): os totais devem bater. O Google ainda pode ajustar os últimos dias; é normal haver pequenas diferenças recentes.
A moeda vem da sua conta de faturamento (por exemplo, BRL ou USD); convertemos USD para reais pela PTAX.

Histórico

A exportação só contém dados a partir da ativação. Para trazer meses anteriores, abra um pedido de carga retroativa com o suporte do Google Cloud (o Google costuma preencher até 12 meses para tabelas novas). Depois disso, a cada atualização o painel traz mais 30 dias de histórico, até completar 12 meses (veja em Sincronização).

Custo da consulta

A tabela de billing costuma ter poucos MB e as consultas ficam bem abaixo da cota gratuita do BigQuery (1 TB por mês). Cada consulta tem um teto de 1 GB lido; se a tabela for maior, a consulta é recusada em vez de cobrar. O custo de armazenar a exportação é seu e é de centavos por mês.

Opcional: inventário de recursos e rótulos

Com a conexão de custo, o painel também pode listar o que existe no projeto da chave (VMs, discos, instâncias Cloud SQL, clusters GKE, buckets e IPs: os reservados e o IP externo de cada VM) em /painel/gcp-inventario e medir os rótulos para o Especialista em Tags. A leitura usa a Cloud Asset API e pede duas coisas a mais no projeto, ambas de leitura:

gcloud services enable cloudasset.googleapis.com --project <PROJECT_ID>
gcloud projects add-iam-policy-binding <PROJECT_ID> \
  --member serviceAccount:<EMAIL_DA_SERVICE_ACCOUNT> \
  --role roles/cloudasset.viewer

Só o projeto da chave é lido. Outros projetos da mesma conta de faturamento não entram no inventário (o custo deles continua vindo da exportação de billing).
Rótulos criados pelo próprio Google (goog-*) não contam no padrão. Discos sem uso, Cloud Run, funções e datasets do BigQuery ainda não entram.
O Cloud Asset Viewer lê os metadados dos recursos (nome, local, estado e rótulos), não os dados dentro deles. Para tirar o acesso, remova o papel da service account.

Ainda não validado num projeto real. O formato das respostas segue a documentação do Google. Na primeira leitura, confira o resultado com o console; se algo faltar, o painel mostra o motivo.

Erros comuns

Tabela não encontrada: o nome está errado (confira projeto, dataset e tabela) ou a exportação ainda não gravou o primeiro dado.
Falta a permissão de rodar consultas (bigquery.jobs.create): dê BigQuery Job User à service account no projeto.
Sem permissão de leitura nessa tabela: dê BigQuery Data Viewer à service account no dataset da exportação (passo 4). A permissão leva alguns minutos para valer.
O Google recusou a chave (invalid_grant): a chave foi apagada ou desativada. Crie outra no passo 5.
O BigQuery recusou a consulta: a tabela não é a exportação padrão de billing (faltam as colunas usage_start_time, service, cost e credits).
Passou do limite de 1 GB: a tabela tem outros dados além do billing; use um dataset só para a exportação.
Moeda desconhecida: aceitamos conversão de USD e BRL. Contas em outra moeda são recusadas com aviso.

Como guardamos a chave

A chave é cifrada no banco antes de ser gravada e nunca volta para a tela nem para a API do painel. Ela só é decifrada, na memória, no instante de falar com o Google. Para a análise por IA, só vão custos agregados (nunca a chave, o e-mail da service account ou o nome da tabela). Veja Segurança e acesso.

Trocar ou revogar o acesso

Trocar a chave: crie uma nova no passo 5, atualize as credenciais no painel e apague a antiga.
Revogar: apague a chave, remova a permissão do dataset ou apague a service account. A próxima sincronização falha e a conexão aparece como erro. Não é necessário avisar o GrandeTotal.