Collega un Google Calendar

Questa guida mostra come collegare Google Calendar a uno spazio di lavoro. Il collegamento è per spazio di lavoro: sincronizza in sola lettura gli eventi di quello spazio in Control Center. Per il quadro completo, vedi Calendario e pianificazione.

Collega un account

Apri Calendario nella barra laterale.
Fai clic su Aggiungi account calendario nella barra laterale del calendario. (La stessa sezione si trova in Impostazioni → Spazio di lavoro → Profilo e identità, sotto Google Calendar.)
Scegli come autorizzare:
- Usa l’app Google di Control Center — non c’è nulla da configurare. È l’opzione predefinita quando la tua build ne include una.
- Usa il mio client Google Cloud — incolla un ID client e un secret dal tuo progetto (vedi Porta il tuo client Google).
Fai clic su Collega Google Calendar. La finestra di dialogo mostra un codice breve e un link alla pagina dei dispositivi di Google.
Apri quella pagina su qualsiasi dispositivo, inserisci il codice e approva l’accesso richiesto. La finestra di dialogo si chiude da sola e i tuoi eventi iniziano a sincronizzarsi.

Lo scambio lo esegue il server, non il tuo dispositivo, ed è il server a conservare il token di aggiornamento che ne risulta — per questo il codice si approva su «qualsiasi dispositivo» e non in questa app in particolare.

L’account è collegato solo allo spazio di lavoro attivo. Cambia spazio di lavoro e vedrai i calendari di quello spazio.

Il flusso di collegamento richiede calendar.readonly più la tua email — gli stessi scope per l’app integrata e per un client che incolli tu. Control Center legge gli eventi; non li crea, non li modifica, non li elimina e non risponde agli inviti su Google.

Come funziona la sincronizzazione

È il server a governare la pianificazione: ogni due minuti esamina gli account collegati di ogni spazio di lavoro e scrive gli eventi nel database dello spazio di lavoro. I client non parlano mai con Google — leggono ciò che ha scritto il server.

La scansione è incrementale. La prima passata per ogni calendario recupera una finestra mobile (60 giorni indietro, 90 giorni avanti) e memorizza il token di sincronizzazione di Google; le passate successive presentano quel token e ricevono solo ciò che è cambiato, ed è questo che rende sostenibile una cadenza di due minuti. La finestra viene riancorata con una sincronizzazione completa ogni 24 ore e ogni volta che Google invalida il token.

I token di aggiornamento risiedono sul server, in secrets.json nella directory dati del server, scritti con i soli permessi del proprietario (0600) — non nel portachiavi del sistema operativo e mai su un dispositivo client.

Collega più account

Uno spazio di lavoro può collegare diversi account Google (ad esempio quello di lavoro e quello personale). Ripeti il passaggio di collegamento per ciascuno; i loro eventi confluiscono nelle stesse viste mese / settimana / agenda. Ogni account si sincronizza e si aggiorna in modo indipendente e ciascuno può essere disconnesso per conto suo.

Riconnetti un account scaduto

Se Google invalida definitivamente il token di un account (una sessione revocata o scaduta da tempo), la sincronizzazione si ferma e Control Center mostra sul calendario un banner Riconnetti, più una notifica desktop. Fai clic su Riconnetti e approva un nuovo codice; il banner scompare alla successiva sincronizzazione riuscita.

Disconnetti un account

Dalla barra laterale del calendario (o da Impostazioni → Spazio di lavoro → Profilo e identità), fai clic su Disconnetti sull’account. Questo elimina i suoi eventi sincronizzati e cancella i token memorizzati sul server.

Collega da un server headless

Un server senza interfaccia grafica collega lo stesso account dal proprio terminale:

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

Stampa un codice e un URL, attende l’approvazione, poi memorizza i token e sincronizza alla scansione successiva.

Una build dai sorgenti non include alcun client Google, quindi l’ID e il secret sono obbligatori — imposta GOOGLE_OAUTH_CLIENT_ID e GOOGLE_OAUTH_CLIENT_SECRET. Non esiste alcun flag --google-client-id (i flag sconosciuti vengono ignorati). Senza la coppia di variabili d’ambiente il comando termina con un errore di client mancante.

Porta il tuo client Google (fork e self-hosting)

Le build pubblicate includono un client Google, quindi quasi nessuno arriva mai a toccare questa parte. Porta il tuo se compili dai sorgenti, gestisci un server tuo o vuoi che la schermata di consenso rechi il nome del tuo progetto.

Nella Google Cloud Console, abilita la Google Calendar API e configura la schermata di consenso OAuth, aggiungendo gli scope calendar.readonly, openid ed email. Finché l’app non è verificata, aggiungi te stesso come utente di test. Aggiungere calendar.events nella schermata di consenso non abilita la risposta agli inviti — Control Center non richiede mai quello scope.
Crea un ID client OAuth di tipo applicazione TVs and limited input devices e copia sia l’ID client sia il secret client.
Forniscili per singolo collegamento (scegli Usa il mio client Google Cloud nella finestra di dialogo) oppure a livello di server con GOOGLE_OAUTH_CLIENT_ID e GOOGLE_OAUTH_CLIENT_SECRET.

Una coppia impostata a livello di server sostituisce quella integrata ovunque, anche dietro l’opzione «usa l’app Google di Control Center» — quindi sul tuo server quell’opzione è la tua app.

Il secret client non lascia mai il server: nessuna risposta RPC lo trasporta e un account collegato tramite il client del server memorizza un marcatore invece di una copia della coppia, quindi ruotarlo è solo questione di riavviare con un nuovo valore.

Risoluzione dei problemi

Sintomo	Causa probabile
La finestra di dialogo non offre l’opzione integrata	Questa build non include alcun client Google (una build dai sorgenti), oppure il server è stato avviato con una sola metà della coppia. Sia l’ID sia il secret sono obbligatori
`invalid_scope` all’avvio del flusso	Il calendario non è consentito per un client con codice dispositivo in quel progetto Cloud. Usa invece un progetto con client loopback o web
`invalid_client` da Google	Il client non è un client di tipo TVs and limited input devices, oppure l’ID e il secret provengono da client diversi
L’approvazione riesce ma la sincronizzazione è vuota	Il tuo account non è un utente di test nella schermata di consenso, oppure `calendar.readonly` non è stato concesso
Il codice scade prima che tu lo approvi	I codici dispositivo sono di breve durata. Avvia di nuovo il collegamento per ottenerne uno nuovo
«Impossibile aggiornare la tua risposta» quando rispondi a un invito	È previsto: il flusso di collegamento non richiede mai `calendar.events`
La sincronizzazione si ferma con un avviso di aggiornamento del token nel log del server	L’account è stato collegato con un client che non è più configurato. Ricollega l’account, oppure ripristina quell’ID client e quel secret

Guide correlate

Registra e riassumi una riunione: trasforma un evento in una registrazione
Esegui un server headless: dove risiedono i token e la pianificazione della sincronizzazione
Configura l’integrazione GitHub

Concetti correlati

Calendario e pianificazione