Conexões com o Google
Uma conexão com o Google deixa um flow trabalhar no Google Sheets e no Google Drive de uma pessoa sem ninguém entregar senha. Você clica em Conectar com o Google, o Google pede para você permitir o acesso, e o Waiso guarda um token de longa duração como variável secreta do projeto. Por trás do botão existe um app do Google — configurado uma vez por instalação, de graça.
- Saber o que o Conectar com o Google pede — e o que nunca pede
- Acompanhar uma conexão da tela de consentimento até a variável secreta
- Conectar de novo quando o acesso se perde, e entender os erros de conexão
- Configurar o app do Google da instalação no Google Cloud
O que é uma conexão com o Google
Google Sheets e Google Drive são tipos de conexão próprios, no grupo Serviços de Integrações, e passos próprios no menu de adicionar passo — Google Sheets (“Lê, adiciona ou atualiza linhas de planilhas”) e Google Drive (“Lista, baixa ou envia arquivos”). Um passo escolhe uma conexão; a conexão guarda o direito de agir como a pessoa que a conectou.
Ninguém digita token. A conexão é criada pela resposta do Google: você dá um nome, clica em Conectar com o Google (“O Google traz você de volta para cá assim que você permitir o acesso.”), escolhe a conta Google, permite o acesso e volta para onde estava. O card passa a mostrar o endereço da conta e Conectado por … · quando. O que o Google devolveu — um refresh token — fica guardado como a variável secreta GSHEETS_<NOME>_REFRESH_TOKEN (ou GDRIVE_…), e cada passo transforma esse token num access token de curta duração quando roda.
Conecte com uma chave de conta de serviço
Uma conta de serviço é uma conta Google para software. Ela não precisa de tela de consentimento nem de app do Google, então funciona na hora em qualquer instalação. No Google Cloud, ative as APIs do Sheets e do Drive, crie uma conta de serviço, crie uma chave JSON para ela e solte esse arquivo no diálogo (ou cole). O Waiso confere o arquivo e guarda só duas variáveis secretas — GSHEETS_<NOME>_CLIENT_EMAIL e GSHEETS_<NOME>_PRIVATE_KEY; o resto do arquivo nunca é guardado.
A conta de serviço alcança só o que você compartilhar com o e-mail dela (mostrado no diálogo com um botão Copiar), como se fosse uma pessoa. Os passos listam exatamente esses arquivos, e aceitam um endereço colado do Sheets ou do Drive. Uma conta de serviço não tem armazenamento próprio: para criar arquivos, escolha uma pasta num Drive compartilhado, ou substitua um arquivo existente.
Os passos Google Sheets e Google Drive
Google Sheets trabalha numa aba de uma planilha. Escolha a planilha — no seletor do próprio Google (Conectar com o Google) ou na lista compartilhada (conta de serviço) — ou escolha Criar uma planilha em vez disso. Depois Fazer: Ler linhas (opcionalmente só onde uma coluna é igual a um valor), Adicionar uma linha, Atualizar uma linha, Atualizar ou adicionar uma linha, Excluir linhas ou Criar uma planilha. Colunas mostra uma linha de vínculo por cabeçalho da aba; ligue rows a uma lista para gravar várias de uma vez. Atualizar, atualizar-ou-adicionar e excluir comparam pela coluna escolhida em Comparar pela coluna; uma atualização que não encontra nada não muda nada e diz matched: false.
Google Drive lista uma pasta, baixa um arquivo escolhido (um arquivo que um passo Arquivo pode ler em linhas) ou envia um arquivo de um passo anterior — como arquivo novo numa pasta, ou substituindo um arquivo escolhido. Todo Rodar teste que grava pergunta antes.
{
"spreadsheetId": "1AbC…",
"url": "https://docs.google.com/spreadsheets/d/1AbC…/edit",
"tab": {
"id": 0,
"name": "Sheet1"
}
}O que o Waiso pede ao Google
Um escopo é a permissão que a tela de consentimento pede. O Waiso pede o mais estreito que cada serviço precisa, além de openid email para saber qual conta foi conectada — e um teste no código falha se alguém acrescentar um escopo mais amplo:
| Serviço | Escopo | O que permite |
|---|---|---|
| Google Sheets, Google Drive | drive.file | Só os arquivos que você escolher ou que um passo criar — “nunca o seu Drive inteiro” |
| Gmail | gmail.send | Enviar e-mail em seu nome — “ele nunca lê a sua caixa de entrada” |
Por causa do drive.file, uma planilha que você nunca escolheu é invisível para o Waiso, mesmo no seu próprio Drive. É por isso que os passos escolhem arquivos pelo seletor do próprio Google: escolher um arquivo é o que dá acesso a ele.
Como o login é protegido
- O link de login fica ligado a você e expira em 10 minutos; ele não pode ser reaproveitado.
- O Google só consegue mandar você de volta para uma página desta instalação — nunca para um endereço passado num link.
- Excluir ou desconectar a conexão também revoga o token no Google, e depois remove a variável.
Conectar de novo e erros
Uma conexão pode perder o acesso: você removeu o Waiso da sua conta Google, trocou a senha, ou a instalação passou a usar outro app do Google. O card então mostra O acesso ao Google foi perdido — conecte de novo. e Os passos que usam esta conexão falham até lá. Clique em Conectar de novo, permita o acesso outra vez, e a mesma conexão — mesmo nome, mesma variável — volta a funcionar; nenhum flow precisa de edição.
| Quando a conexão não é feita… | Significa |
|---|---|
| O acesso não foi permitido na tela de consentimento. | Você clicou em Cancelar no Google. |
| O login levou mais de 10 minutos. Comece de novo. | O link expirou antes de você voltar. |
| O provedor não devolveu um acesso de longa duração. | O Google já tinha uma permissão para este app. Remova o acesso do app na sua conta Google e conecte de novo. |
| Ainda não há um app do Google configurado para este projeto. | Ninguém configurou o app do Google (próxima seção). O botão é trocado por Configure o app do Google primeiro. |
| Já existe uma variável com o nome desta conexão. | Renomeie a conexão e conecte de novo. |
Configure o app do Google
Todo Conectar com o Google passa por um único app OAuth registrado no Google Cloud. Numa instalação self-hosted, um super admin cria esse app uma vez em Configurações → App do Google (“O app do Google Cloud que todos os projetos usam no Conectar com o Google.”); Como configuro isto? abre os mesmos passos de baixo, com o seu endereço de retorno exato já preenchido.
- Crie um projeto no Google Cloud
No console do Google Cloud, crie um projeto para o Waiso. Não precisa de conta de faturamento — nada aqui é pago.
- Ative as quatro APIs
Em APIs e serviços → Biblioteca, ative a Google Sheets API, a Google Drive API, a Gmail API e a Google Picker API.
- Configure a tela de consentimento
Escolha Externo — ou Interno se todos estão na sua organização do Google Workspace. Adicione só os escopos
drive.fileegmail.sende publique o app Em produção: um app deixado em Teste perde o acesso depois de 7 dias. - Crie o cliente OAuth
Em Credenciais, crie um ID do cliente OAuth do tipo Aplicativo da Web com o Endereço de retorno que o painel mostra como URI de redirecionamento autorizado (ele termina em
/api/oauth/callback). Cole o Client ID e o Client secret. - Adicione a chave do Picker e salve
Crie uma chave de API restrita à Google Picker API, copie o Número do projeto do painel do projeto, preencha Chave de API do Picker e Número do projeto e clique em Salvar.
O client secret entra e nunca mais volta: depois o campo mostra Client secret · salvo com Substituir. Salvar um cliente diferente avisa Outro cliente: as conexões feitas com o anterior vão precisar conectar de novo.
Limites
- Uma conexão age como uma conta Google — a que clicou em Conectar, ou a conta de serviço. Arquivos que essa conta não abre, os passos também não abrem (
google_not_found, indicando o arquivo). - Só arquivos escolhidos pelo seletor do Google, ou criados por um passo, ficam acessíveis (
drive.file). - Uma conexão com o Google não pode ser criada digitando um token nem por um cliente MCP: ela nasce da resposta do Google a uma pessoa que clicou no botão, ou de uma pessoa que enviou uma chave de conta de serviço.
- O refresh token e a chave privada da conta de serviço são segredos do projeto, então, como toda variável, também ficam visíveis para os scripts do projeto como variáveis de ambiente.