Como Ligar o Google Sheets à Sua Aplicação

Para ligar o Google Sheets à sua aplicação, ative a API do Google Sheets num projeto do Google Cloud, crie uma conta de serviço, partilhe a folha de cálculo com o endereço de email da conta de serviço e guarde a sua chave como segredo do lado do servidor. O seu servidor lê linhas com spreadsheets.values.get e acrescenta linhas com spreadsheets.values.append. Se os utilizadores precisarem de ligar as suas próprias folhas, use OAuth; e se a folha for totalmente pública, basta uma chave de API simples para leitura.

Este guia explica qual o método adequado, as chamadas que precisa, as quotas e os cuidados a ter, e sugestões de prompts para um criador de aplicações com IA. Os detalhes do Google vêm da documentação para programadores do Google a partir de setembro de 2026.

Porque ligar uma folha

Razões comuns:

• Manter o fluxo de trabalho da equipa. A equipa continua a editar uma lista de preços ou um horário no Sheets; a aplicação mostra-os.
• Recolher dados onde as pessoas já olham. Novos registos, encomendas ou respostas de formulários aparecem como linhas.
• Relatórios. Exportar dados da aplicação para uma folha para quem trabalha diariamente com folhas de cálculo.
• Um primeiro passo. Começar pela folha e, mais tarde, passar para uma base de dados própria. Veja como transformar uma folha de cálculo numa aplicação.

Escolha como a sua aplicação inicia sessão no Google

O guia de credenciais do Google descreve três tipos:

Para a maioria das aplicações, uma conta de serviço é a escolha certa: um conjunto de credenciais, que lhe pertence, com acesso apenas às folhas que partilhar explicitamente com ela.

Passo a passo com uma conta de serviço

1. Crie ou escolha um projeto do Google Cloud e ative a API do Google Sheets.
2. Crie uma conta de serviço e uma chave para ela. A chave é um ficheiro JSON; trate-a como uma palavra-passe.
3. Partilhe a folha de cálculo com o endereço de email da conta de serviço, como Leitor para apenas leitura ou Editor para escrever. O guia do Google indica que isto se faz através do ecrã normal de partilha.
4. Guarde a chave como segredo no seu servidor, por exemplo GOOGLE_SERVICE_ACCOUNT_JSON, e o ID da folha (a longa sequência no URL da folha) como SHEET_ID.
5. Chame a API a partir do servidor com a biblioteca cliente do Google para a sua linguagem.
6. Guarde leituras em cache se muitos visitantes virem os mesmos dados, para não atingir a quota.

As chamadas que vai usar

Do guia do Google sobre leitura e escrita de valores:

Os intervalos usam a notação A1. O Google indica que um intervalo sem nome de folha, como A1:B2, se aplica à primeira folha, por isso indique explicitamente o nome do separador para evitar surpresas quando alguém reordenar os separadores.

RAW vs USER_ENTERED

As escritas precisam de um valueInputOption:

• RAW guarda exatamente o que envia, como texto. =1+2 fica guardado como o texto =1+2.
• USER_ENTERED trata a entrada como se fosse escrita no Sheets: as datas tornam-se datas e =1+2 torna-se uma fórmula.

Se escrever texto que os utilizadores introduziram na sua aplicação, use RAW. Com USER_ENTERED, alguém poderia enviar uma fórmula que é executada quando um colega abre a folha.

Quotas e erros

A partir de setembro de 2026, a página de limites da API do Sheets do Google indica:

Não há limite diário desde que se mantenha dentro das quotas por minuto. Ultrapassá-las devolve 429: Too many requests, e o Google recomenda backoff exponencial truncado: esperar mais após cada tentativa falhada, com um atraso aleatório, até um máximo. Um único pedido que demore mais de 180 segundos expira.

Na prática: não chame a API em cada visualização de página. Guarde os dados da folha em cache durante um minuto ou mais, agrupe leituras com batchGet e agrupe escritas sempre que possível.

Opções e compromissos

Para qualquer coisa com muitos utilizadores ou dados sensíveis, uma base de dados é a fonte de verdade mais adequada. Veja o que é uma base de dados.

Prompts para dar ao seu criador com IA

Ler uma folha:

Mostre o separador “Menu” da nossa folha do Google na página de menu. Use a API do Google Sheets a partir do servidor com uma conta de serviço cuja chave JSON está no segredo GOOGLE_SERVICE_ACCOUNT_JSON, e o ID da folha em SHEET_ID. Leia o intervalo Menu!A2:D (nome, descrição, preço, categoria). Guarde o resultado em cache durante 5 minutos. Se a API falhar, mostre a última versão em cache. Nunca envie a chave para o navegador.

Escrever linhas:

Quando alguém enviar o formulário de contacto, guarde-o na nossa base de dados e acrescente também uma linha ao separador “Leads” (data, nome, email, mensagem) com spreadsheets.values.append e valueInputOption RAW. Se o Google devolver 429, tente novamente com backoff exponencial; se continuar a falhar, mantenha o contacto na base de dados e tente mais tarde.

Erros comuns

• Esquecer de partilhar a folha com o email da conta de serviço. A API devolve então um erro de permissões, mesmo com a chave correta.
• Chave no frontend ou no repositório. A chave JSON dá acesso a todas as folhas partilhadas com ela. Veja como manter as chaves de API seguras.
• Usar USER_ENTERED para dados introduzidos pelos utilizadores, o que permite injeção de fórmulas.
• Chamar a API em cada pedido e atingir a quota por minuto no primeiro pico de tráfego.
• Depender das posições das colunas. Alguém insere uma coluna e a aplicação lê os dados errados. Leia a linha de cabeçalho e faça a correspondência pelo nome, ou bloqueie o cabeçalho.
• Partilhar a folha mais do que o necessário. “Qualquer pessoa com a ligação” torna-a pública.
• Usar uma folha como base de dados multiutilizador. Escritas simultâneas e permissões em falta causam perda ou fuga de dados.

Lista de verificação

• API do Sheets ativada; conta de serviço criada
• Folha partilhada com o email da conta de serviço, com o papel mínimo necessário
• Chave e ID da folha guardados como segredos do servidor
• Todas as chamadas feitas a partir do servidor
• Nomes dos separadores usados nos intervalos
• RAW usado para texto fornecido pelo utilizador
• Leituras guardadas em cache; 429 tratado com backoff
• A aplicação funciona de forma degradada se o Sheets estiver indisponível
• Decidido qual lado é a fonte de verdade

Google Sheets na Mythex

A Mythex tem duas formas diferentes de trabalhar com o Sheets. Os conectores ligam a sua conta Google à Mythex para que o agente a possa usar enquanto constrói, por exemplo para ler uma folha e criar um painel a partir dela; a documentação diz que a credencial fica no serviço de ligação da Mythex e nunca chega ao seu código (veja Conectores, e aprove cada permissão que o Google pedir). Para que a aplicação publicada leia ou escreva numa folha por conta própria, a via fiável é a deste guia: uma chave de conta de serviço guardada como segredo do projeto e chamadas à API do Sheets a partir do servidor, como em Integrar qualquer API. Se estiver a ultrapassar a folha, peça ao agente que mova os dados para a base de dados do projeto e que construa um painel por cima dela.

Perguntas