Pular para o conteúdo
SheetForge

Configuração da Planilha do Google — Conta de Serviço e Chave JSON

O SheetForge lê Planilhas do Google em dois modos.

  • ExportUrl não exige nenhuma credencial: compartilhe a planilha por link, registre o valor #gid= de cada aba e importe. É somente leitura.
  • SheetsApi autentica como uma conta de serviço do Google e desbloqueia tudo o mais: planilhas privadas, gravação de volta (reflect) e Push.

Esta página percorre a configuração do SheetsApi de ponta a ponta — criando a conta de serviço, baixando sua chave JSON, compartilhando sua planilha com ela e apontando o SheetForge para a chave. Nenhuma experiência prévia com o Google Cloud é necessária; cada etapa acontece em um navegador web e não custa nada.

O fluxo completo:

  1. Crie um projeto do Google Cloud.
  2. Ative a API do Google Sheets nele.
  3. Crie uma conta de serviço.
  4. Baixe a chave JSON da conta.
  5. Compartilhe sua planilha com o endereço de e-mail da conta.
  6. Aponte o SheetForge para a chave.

1. Crie um projeto do Google Cloud

  1. Abra console.cloud.google.com e faça login com uma conta do Google — ela não precisa ser a dona da planilha. Uma conta pessoal sempre funciona; algumas organizações Google Workspace corporativas desativam o download de chaves de conta de serviço por política, o que faz a etapa 4 falhar com um erro de política organizacional (veja "Se algo falhar" abaixo). No primeiro acesso, aceite o aviso de Terms of Service para chegar ao console.
  2. Na barra superior, clique no seletor de projeto (o menu suspenso ao lado do logo do Google Cloud) e, em seguida, em New project.
  3. Digite qualquer nome (por exemplo, sheetforge-sheets) e clique em Create. Deixe organização e localização nos valores padrão.
  4. Quando a notificação "project created" aparecer, selecione o novo projeto no seletor. Tudo abaixo acontece dentro deste projeto, então garanta que ele permaneça selecionado.

Um projeto é apenas um contêiner para configurações de API. Criar um é gratuito, e o uso da API do Sheets neste guia não tem custo.

2. Ative a API do Google Sheets

  1. Abra o menu à esquerda (☰) e vá para APIs & Services ▸ Library.
  2. Pesquise por Google Sheets API e abra o resultado.
  3. Clique em Enable. Se o botão mostrar Manage, a API já está ativada — nada a fazer.

3. Crie uma conta de serviço

Uma conta de serviço é uma identidade de máquina com seu próprio endereço de e-mail. O SheetForge faz login como essa identidade — sua senha pessoal do Google nunca entra em jogo.

  1. Vá para APIs & Services ▸ Credentials.
  2. Clique em + Create credentials ▸ Service account.
  3. Digite um nome (por exemplo, sheetforge-reader); o ID da conta é preenchido automaticamente. Clique em Create and continue.
  4. As etapas "Grant this service account access to project" e "Grant users access" são opcionais — pule as duas e clique em Done. O acesso à sua planilha é concedido compartilhando a planilha (etapa 5), não por papéis do projeto.
  5. Se o console sugerir configurar uma OAuth consent screen, ignore — contas de serviço não usam isso.

4. Baixe a chave JSON

  1. De volta na página Credentials, clique na conta de serviço que você acabou de criar (em "Service accounts").
  2. Abra a aba Keys.
  3. Clique em Add key ▸ Create new key, escolha JSON e clique em Create.
  4. O navegador baixa um arquivo com um nome parecido com sheetforge-sheets-1a2b3c.json. Esta é a única cópia — o Google não a mantém para novo download. Se você a perder, exclua a chave na aba Keys e crie uma nova.

Trate esse arquivo como uma senha:

  • Mova-o para algum lugar fora do seu projeto Unity e do repositório — por exemplo, C:/keys/sheetforge.json.
  • Nunca o coloque em Assets/ — tudo ali é commitado junto com o projeto, e uma referência perdida (ou uma pasta Resources/StreamingAssets) pode levá-lo para dentro de um build.
  • Se a chave algum dia vazar, exclua-a na aba Keys (isso a revoga imediatamente) e crie uma nova.

5. Compartilhe a planilha com a conta de serviço

A chave sozinha não concede nada. A conta de serviço só consegue ler planilhas que foram explicitamente compartilhadas com ela — exatamente como um colaborador humano.

  1. Abra o arquivo JSON baixado em qualquer editor de texto e copie o valor de client_email. Ele se parece com sheetforge-reader@sheetforge-sheets.iam.gserviceaccount.com.
  2. Abra sua planilha no Google Sheets e clique em Share.
  3. Cole o endereço e escolha um papel:
    • Viewer é suficiente para importar.
    • Editor é necessário para gravação de volta — reflect da autoria e Push.
  4. Desative "Notify people" (o endereço não tem caixa de entrada) e confirme.
  5. Se o Google avisar sobre compartilhamento fora da sua organização, confirme — uma conta de serviço não pertence a nenhuma organização.

Pular esta etapa é o erro de configuração mais comum — toda requisição então falha com um erro de permissão, não importa quão correta a chave esteja.

6. Aponte o SheetForge para a chave

  1. No seu asset de configurações de importação, defina a origem como GoogleSheet e o modo de acesso como SheetsApi.
  2. Preencha spreadsheetId com o ID longo da URL da planilha: https://docs.google.com/spreadsheets/d/<this part>/edit.
  3. Diga ao SheetForge onde está o arquivo de chave, de uma das duas formas:
    • Recomendado — variável de ambiente. Defina SHEETFORGE_SHEETS_KEY com o caminho absoluto do arquivo JSON. Cada desenvolvedor define a sua própria; nenhum caminho jamais entra no repositório, e ela tem precedência sobre o campo de configurações.
      • No Windows: setx SHEETFORGE_SHEETS_KEY "C:\keys\sheetforge.json" em um terminal, depois reinicie o Unity e o Unity Hub (processos já em execução mantêm o ambiente antigo).
      • No macOS/Linux: exporte-a no seu perfil de shell e inicie o Unity a partir desse shell, ou use launchctl setenv no macOS.
    • Ou — campo de configurações. Coloque o caminho em serviceAccountKeyPath, apontando para fora do repositório.
  4. Pressione ↓ Pull from source em Tools ▸ SheetForge ▸ Data Studio. Um relatório de sucesso significa que toda a cadeia — projeto, API, conta, compartilhamento, chave — está funcionando.

Se algo falhar

  • Erro de permissão (PERMISSION_DENIED / 403): a planilha não está compartilhada com o endereço client_email (etapa 5) — o ID aponta para uma planilha real que a conta de serviço não consegue ver.
  • Requested entity was not found (404): o spreadsheetId está errado — copie exatamente o trecho entre /d/ e /edit na URL da planilha.
  • "Service account key creation is disabled" / erro de política organizacional na etapa 4: sua organização Google Workspace impõe iam.disableServiceAccountKeyCreation. Peça a um administrador para permitir a criação de chaves para este projeto, ou crie o projeto sob uma conta pessoal do Google — a planilha pode ser compartilhada com a conta de serviço desse projeto, não importa quem seja o dono da planilha.
  • "Google Sheets API has not been used in project … or it is disabled": a API não está ativada no projeto que emitiu a chave (etapa 2) — ative-a lá, não em outro projeto. Uma API recém-ativada pode levar alguns minutos para propagar.
  • Arquivo de chave não encontrado: o caminho tem um erro de digitação, ou o Unity foi iniciado antes de a variável de ambiente existir — defina a variável, depois reinicie o Unity e o Unity Hub.
  • Chave comprometida ou perdida: exclua-a na aba Keys da conta de serviço, crie uma nova chave JSON e substitua o arquivo. Nada mais muda — o endereço de e-mail e o compartilhamento da planilha continuam válidos.

Páginas relacionadas