Acesso Web às Planilhas Google

O acesso a Planilhas do Google segue a credencial que você traz. No site publicado há duas portas de entrada, lado a lado: entrar com o Google (OAuth), ou escolher um arquivo de chave de conta de serviço que o seu próprio navegador usa diretamente. O caminho Unity / local mantém sua chave de conta de serviço local da máquina, sem alterações.

No site publicado — OAuth, leitura e gravação

No site publicado, um usuário autenticado pode tanto ler quanto gravar Planilhas do Google usando o próprio token OAuth.

• Privilégio mínimo. Entrar pede o seu perfil básico e acesso a planilhas por arquivo (drive.file): o app só consegue ler e gravar os arquivos de planilha que você abriu explicitamente para ele. Nada em nível de conta — ele não consegue listar nem navegar pelo resto do seu Drive, e um arquivo que você não abriu para ele permanece invisível.
• O mesmo plano do core. Uma gravação na web roda através de exatamente o mesmo plano do core e da mesma verificação de lock otimista compartilhada que todo outro caminho — a planilha ao vivo é reverificada bem antes do envio, então uma célula que um terceiro mudou depois da sua importação é pulada, nunca sobrescrita. Apenas a camada de transporte difere: neste caminho ela carrega o bearer token OAuth.
• A ACL da planilha é a autoridade final. O SheetForge não decide quem pode gravar; o Google decide. Um 403 do Google é remapeado para uma mensagem honesta de permissão, em vez de uma gravação parcial, então uma recusa se lê como uma recusa.

O token OAuth é mantido no cookie de sessão (um JWT) e usado por server actions. A única exceção é o seletor de arquivos do Google, descrito a seguir: é um widget do Google que roda na página, então abri-lo entrega à página um token de acesso de curta duração para a sua própria sessão.

Comece pelo seletor — você nunca precisa de um ID

A aba de usuário conectado começa com Escolher uma planilha do Google: o próprio seletor de arquivos do Google abre sobre a página, você escolhe a planilha, o ID dela cai no painel e a importação roda sozinha. Escolher também é o que concede ao app acesso àquele arquivo sob drive.file, então um único gesto faz as duas coisas. Uma linha Planilha atual mostra para onde o painel está apontado.

Digitar um ID à mão continua funcionando — ele se mudou para uma seção recolhível Avançado: começar a partir de um id de planilha, e um ID salvo anteriormente continua funcionando exatamente como antes. A ressalva honesta é dita bem ali: o Google só abre arquivos que você escolheu pelo menos uma vez, então um ID de um arquivo nunca escolhido é recusado até você escolhê-lo (a linha Permitir acesso ao arquivo… abaixo cobre isso).

Abrindo um arquivo para o app — uma vez

Sob drive.file, a permissão cresce arquivo por arquivo. Se o app esbarra em uma planilha à qual ainda não tem acesso — um ID digitado em Avançado, um ID salvo depois de trocar de conta —, ele abre o próprio seletor de arquivos do Google, já com essa planilha localizada, no momento em que esbarra no erro de permissão. Escolha o arquivo uma vez, e a importação ou o push que você iniciou termina sozinho. Dali em diante, essa planilha se comporta exatamente como sempre se comportou.

• Nada para preparar com antecedência. Você não concede acesso de antemão; o seletor aparece exatamente quando é necessário, já apontado para o arquivo em questão, e a ação que você pediu tenta de novo automaticamente depois que você escolhe.
• Conceder de novo está sempre à mão. O painel do Google mantém uma linha Permitir acesso ao arquivo… que abre o mesmo seletor a qualquer momento — por exemplo, depois de trocar para outra conta do Google.
• Um limite honesto. O seletor é um widget do Google rodando na página, então, enquanto está em uso, a página guarda um token de acesso de curta duração (válido por no máximo uma hora) para a sua sessão, obtido de um endpoint de mesma origem que exige que você esteja conectado. É o mesmo tipo de confiança que o caminho do arquivo de chave, abaixo, deposita na página — o que protege isso é a Content Security Policy estrita do app. O token não é armazenado nem registrado em log.

A aba do arquivo de chave mantém o seu campo de ID de propósito: uma conta de serviço não tem uma sessão de navegação conectada com a qual escolher, então um ID — com a planilha compartilhada com a conta — continua sendo o caminho honesto de entrada ali.

No site publicado — um arquivo de chave de conta de serviço, assinado pelo seu navegador

A segunda aba do painel do Google recebe um arquivo de chave JSON de conta de serviço. Tudo o que essa chave faz acontece no seu navegador:

• A chave nunca chega ao servidor. O próprio navegador assina a solicitação de token e chama as APIs do Google diretamente, então a chave, a solicitação assinada, o token de acesso e os dados da sua planilha nunca tocam os servidores do SheetForge. As rotas de conta de serviço do lado do servidor permanecem fechadas por portão (501) no site publicado, exatamente como antes — este caminho adiciona uma capacidade sem abrir nenhuma.
• Lembrar a chave é honesto sobre o que é guardado. Se você escolher deixar a chave lembrada, o texto do arquivo é descartado imediatamente; o que é guardado — naquele dispositivo, no armazenamento do navegador — é uma chave de assinatura que os scripts da página podem usar, mas nunca conseguem ler de volta. Quem puder abrir aquele perfil do navegador ainda poderia recuperá-la, então trate o dispositivo como se contivesse o arquivo da chave. Esquecer chave a remove na hora, em toda aba aberta, e o app também pede ao Google para revogar o token de acesso atual.
• Mesmo plano, mesma verificação. Leituras e gravações rodam através do mesmo plano do core e da mesma verificação prévia ao envio que os outros caminhos.

O caminho Unity / local

A chave de conta de serviço usada pela Unity e pelo servidor de desenvolvimento local é lida a partir de um caminho local da máquina e nunca é enviada nem empacotada — a mesma chave descrita em Configuração da Planilha do Google; mantenha-a fora de Assets/ e fora do repositório. O repositório não contém nenhuma credencial.

Os dropdowns são atualizados a cada push

Depois de um push a partir do app web, os dropdowns de validação de dados da planilha são reescritos automaticamente — cada aba em um único lote, com o dropdown de uma coluna de referência escrito como um intervalo sobre a coluna-chave da planilha de destino, então ele cresce conforme registros são adicionados. Uma regra apontando para uma aba de planilha que não existe é pulada e reportada. Isso corresponde ao que o push do Google do editor grava.

Qual caminho faz o quê

O comportamento de gravação é idêntico onde quer que rode, porque todo caminho compartilha o plano do core e a verificação antes do envio. Apenas o transporte — um token de conta de serviço assinado pelo navegador, um bearer OAuth por usuário, ou a chave do servidor local — muda.

Páginas relacionadas

• Configuração da Planilha do Google — criando a conta de serviço e a chave JSON para o caminho Unity
• Fontes, Exportação e Envio — a cadeia de segurança do Push que o caminho de gravação web compartilha
• SheetForge Web — o aplicativo do navegador onde este acesso vive