Conectar um Google Calendar

Este guia mostra como conectar o Google Calendar a um espaço de trabalho. A conexão é por espaço de trabalho: ela sincroniza os eventos desse espaço no Control Center, somente leitura. Consulte Calendário e agendamento para ver o panorama completo.

Conectar uma conta

1. Abra Calendário na barra lateral.
2. Clique em Adicionar conta de calendário na barra lateral do calendário. (A mesma seção fica em Configurações → Espaço de trabalho → Perfil e identidade, no item Google Calendar.)
3. Escolha como autorizar:
   • Usar a app Google do Control Center — não há nada a configurar. Esta é a opção padrão quando a sua compilação já inclui um cliente.
   • Usar o meu cliente do Google Cloud — cole um ID de cliente e um segredo do seu próprio projeto (consulte Traga o seu próprio cliente do Google).
4. Clique em Conectar o Google Calendar. A caixa de diálogo mostra um código curto e um link para a página de dispositivos do Google.
5. Abra essa página em qualquer dispositivo, insira o código e aprove o acesso solicitado. A caixa de diálogo fecha sozinha e os seus eventos começam a sincronizar.

É o servidor, e não o seu dispositivo, que conduz essa troca e guarda o token de atualização resultante — por isso o código é aprovado em “qualquer dispositivo” e não especificamente neste app.

A conta é conectada somente ao espaço de trabalho ativo. Troque de espaço de trabalho e você verá os calendários desse outro espaço.

O fluxo de conexão solicita calendar.readonly e o seu e-mail — os mesmos escopos para o app integrado e para um cliente que você colar. O Control Center lê eventos; ele não cria, edita, exclui nem responde a convites no Google.

Como a sincronização funciona

O servidor é o dono da agenda: ele varre as contas conectadas de cada espaço de trabalho a cada dois minutos e grava os eventos no banco de dados do espaço de trabalho. Os clientes nunca falam com o Google — eles leem o que o servidor gravou.

A varredura é incremental. A primeira passagem por calendário busca uma janela móvel (60 dias para trás, 90 dias para frente) e captura o token de sincronização do Google; as passagens seguintes apresentam esse token e recebem apenas o que mudou, e é isso que torna viável uma cadência de dois minutos. A janela é reancorada com uma sincronização completa a cada 24 horas e sempre que o Google invalida o token.

Os tokens de atualização ficam no lado do servidor, em secrets.json, dentro do diretório de dados do servidor, gravados com permissão apenas para o proprietário (0600) — não no keychain do sistema operacional e nunca em um dispositivo cliente.

Conectar várias contas

Um espaço de trabalho pode conectar várias contas do Google (por exemplo, uma do trabalho e uma pessoal). Repita o passo de conexão para cada uma; os eventos delas são mesclados nas mesmas visualizações de mês / semana / agenda. Cada conta sincroniza e se atualiza de forma independente, e cada uma pode ser desconectada por conta própria.

Reconectar uma conta expirada

Se o Google invalidar em definitivo o token de uma conta (uma sessão revogada ou expirada há muito tempo), a sincronização para e o Control Center exibe um banner de Reconectar no calendário, além de uma notificação na área de trabalho. Clique em Reconectar e aprove um novo código; o banner some na próxima sincronização bem-sucedida.

Desconectar uma conta

Na barra lateral do calendário (ou em Configurações → Espaço de trabalho → Perfil e identidade), clique em Desconectar na conta. Isso exclui os eventos sincronizados dela e limpa os tokens armazenados no servidor.

Conectar a partir de um servidor headless

Um servidor sem interface gráfica conecta a mesma conta pelo próprio terminal:

GOOGLE_OAUTH_CLIENT_ID=<id> GOOGLE_OAUTH_CLIENT_SECRET=<secret> \
  cc_server calendar connect --data-dir <dir> --workspace <workspace-id>

Ele imprime um código e uma URL, espera a aprovação e então armazena os tokens e sincroniza na próxima varredura.

Uma compilação a partir do código-fonte não inclui nenhum cliente do Google, então o ID e o segredo são obrigatórios — defina GOOGLE_OAUTH_CLIENT_ID e GOOGLE_OAUTH_CLIENT_SECRET. Não existe nenhuma flag --google-client-id (flags desconhecidas são ignoradas). Sem o par de variáveis de ambiente, o comando termina com um erro de cliente ausente.

Traga o seu próprio cliente do Google (forks e auto-hospedagem)

As compilações de lançamento já incluem um cliente do Google, então a maioria das pessoas nunca mexe nisso. Traga o seu próprio se você compilar a partir do código-fonte, executar o seu próprio servidor ou quiser que a tela de consentimento exiba o nome do seu próprio projeto.

1. No Google Cloud Console, ative a Google Calendar API e configure a tela de consentimento do OAuth, adicionando os escopos calendar.readonly, openid e email. Enquanto o app não estiver verificado, adicione você mesmo como usuário de teste. Adicionar calendar.events na tela de consentimento não habilita a resposta a convites — o Control Center nunca solicita esse escopo.
2. Crie um ID de cliente OAuth do tipo de aplicativo TVs and limited input devices e copie tanto o ID de cliente quanto o segredo do cliente.
3. Forneça-os por conexão (escolha Usar o meu cliente do Google Cloud na caixa de diálogo) ou para o servidor todo com GOOGLE_OAUTH_CLIENT_ID e GOOGLE_OAUTH_CLIENT_SECRET.

Um par definido para o servidor todo substitui o integrado em todos os lugares, inclusive por trás da opção “usar a app Google do Control Center” — então, no seu próprio servidor, essa opção é o seu app.

O segredo do cliente nunca sai do servidor: nenhuma resposta RPC o carrega, e uma conta conectada pelo cliente do próprio servidor armazena um marcador em vez de uma cópia do par, então trocá-lo é só uma questão de reiniciar com um valor novo.

Solução de problemas

Sintoma	Causa provável
A caixa de diálogo não oferece nenhuma opção integrada	Esta compilação não inclui cliente do Google algum (é uma compilação a partir do código-fonte), ou o servidor foi iniciado com apenas uma metade do par. Tanto o ID quanto o segredo são obrigatórios
invalid_scope ao iniciar o fluxo	O Calendar não é permitido para um cliente de código de dispositivo nesse projeto do Cloud. Use um projeto de cliente loopback ou web em vez disso
invalid_client do Google	O cliente não é do tipo TVs and limited input devices, ou o ID e o segredo vêm de clientes diferentes
A aprovação é bem-sucedida, mas a sincronização fica vazia	A sua conta não é usuário de teste na tela de consentimento, ou calendar.readonly não foi concedido
O código expira antes de você aprová-lo	Os códigos de dispositivo duram pouco. Inicie a conexão de novo para obter um novo
“Não foi possível atualizar a sua resposta” em um RSVP	É o esperado: o fluxo de conexão nunca solicita calendar.events
A sincronização para com um aviso de atualização no log do servidor	A conta foi conectada com um cliente que não está mais configurado. Reconecte a conta ou restaure esse ID de cliente e segredo

Guias relacionados

• Gravar e resumir uma reunião: transforme um evento em uma gravação
• Executar um servidor headless: onde ficam os tokens e o cronograma de sincronização
• Configurar a integração com o GitHub

Conceitos relacionados

• Calendário e agendamento