Guida per gli sviluppatori dell'API CalDAV

CalDAV è un'estensione di WebDAV che fornisce uno standard per i client per accedere alle informazioni del calendario su un server remoto.

Google fornisce un'interfaccia CalDAV che puoi utilizzare per visualizzare e gestire i calendari utilizzando il protocollo CalDAV.

Specifiche

Per ciascuna delle specifiche pertinenti, il supporto CalDAV di Google è il seguente:

• rfc4918: Estensioni HTTP per il controllo delle versioni e la creazione distribuiti per il Web (WebDAV)
  • Supporta i metodi HTTP GET, PUT, HEAD, DELETE, POST, OPTIONS, PROPFIND e PROPPATCH.
  • Non supporta i metodi HTTP LOCK, UNLOCK, COPY, MOVE o MKCOL né l'intestazione If* (tranne If-Match).
  • Non supporta proprietà WebDAV arbitrarie (definite dall'utente).
  • Non supporta il controllo accesso WebDAV (rfc3744).
• rfc4791: Estensioni di Calendar per WebDAV (CalDAV)
  • Supporta il metodo HTTP REPORT. Vengono implementati tutti i report, tranne la query disponibile/occupato.
  • Non supporta il metodo HTTP MKCALENDAR.
  • Non supporta l'azione AUDIO.
• rfc5545: iCalendar
  • I dati esposti nell'interfaccia CalDAV sono formattati in base alla specifica iCalendar.
  • Al momento non supporta i dati VTODO o VJOURNAL.
  • Non supporta l'estensione Apple iCal® per consentire le proprietà degli URL impostabili dall'utente.
• rfc6578: Sincronizzazione delle raccolte per WebDAV
  • Le applicazioni client devono passare a questa modalità operativa dopo la sincronizzazione iniziale.
• rfc6638: pianificazione delle estensioni per CalDAV
  • Supporta una semplice "Posta in arrivo", che è sempre vuota.
  • Gli inviti che ricevi vengono recapitati automaticamente nella raccolta "Eventi" anziché nella "Posta in arrivo".
  • Non supporta la ricerca di informazioni sulla disponibilità.
• caldav-ctag-02: Tag dell'entità della raccolta del calendario (CTag) in CalDAV
  • Il calendario ctag è come una risorsa etag: cambia quando cambia qualcosa nel calendario. Ciò consente all'applicazione client di determinare rapidamente che non è necessario sincronizzare gli eventi modificati.
• calendar-proxy: funzionalità proxy utente Calendar in CalDAV
  • Per migliorare le prestazioni della sincronizzazione del calendario dai dispositivi iOS, che non supportano la delega, l'utilizzo delle proprietà calendar-proxy-read-for o calendar-proxy-write-for con uno UserAgent per iOS non riuscirà.

Non abbiamo ancora fornito un'implementazione completa di tutte le specifiche pertinenti. Tuttavia, per molti client, come l'app Calendar di Apple, il protocollo CalDAV dovrebbe interoperare correttamente.

Nota: per la sicurezza dell'account e per prevenire comportamenti illeciti, Google potrebbe impostare cookie su applicazioni client che accedono ai dati tramite CalDAV.

Creazione dell'ID client in corso...

Per utilizzare l'API CalDAV devi disporre di un Account Google. Se hai già un account utilizzabile, non devi fare altro.

Prima di poter inviare richieste all'API CalDAV, devi registrare il tuo client nella console API di Google creando un progetto.

Vai alla console dell'API di Google. Fai clic su Crea progetto, inserisci un nome e fai clic su Crea.

Il passaggio successivo prevede l'attivazione dell'API CalDAV.

Per abilitare un'API per il tuo progetto, segui questi passaggi:

1. Apri la libreria API nella console API di Google. Se richiesto, seleziona un progetto o creane uno nuovo. La libreria API elenca tutte le API disponibili, raggruppate per famiglia di prodotti e popolarità.
2. Se l'API che vuoi abilitare non è visibile nell'elenco, utilizza la ricerca per trovarla.
3. Seleziona l'API da abilitare e fai clic sul pulsante Abilita.
4. Se richiesto, abilita la fatturazione.
5. Se richiesto, accetta i Termini di servizio dell'API.

Per eseguire le richieste dell'API CalDAV, avrai bisogno dell'ID client e del client secret.

Per trovare l'ID client e il client secret del tuo progetto, segui questi passaggi:

1. Seleziona una credenziale OAuth 2.0 esistente o apri la pagina Credenziali.
2. Se non lo hai già fatto, crea le credenziali OAuth 2.0 del tuo progetto facendo clic su Crea credenziali > ID client OAuth e fornendo le informazioni necessarie per creare le credenziali.
3. Cerca l'ID client nella sezione ID client OAuth 2.0. Per maggiori dettagli, fai clic sull'ID client.

Connessione al server CalDAV di Google

Per utilizzare l'interfaccia CalDAV, un programma client si connette inizialmente al server di calendario in uno dei due punti di partenza. In entrambi i casi, la connessione deve essere effettuata tramite HTTPS e deve utilizzare lo schema di autenticazione OAuth 2.0. Il server CalDAV rifiuterà l'autenticazione di una richiesta a meno che non arrivi tramite HTTPS con l'autenticazione OAuth 2.0 di un Account Google. Quando provi a connetterti tramite HTTP o a utilizzare l'autenticazione di base, viene visualizzato un codice di stato HTTP 401 Unauthorized.

Se il programma client (ad esempio l'app Calendar di Apple) richiede una raccolta di entità come punto di partenza, l'URI a cui connettersi è:

https://apidata.googleusercontent.com/caldav/v2/calid/user

Dove calid deve essere sostituito con l'"ID calendario" del calendario a cui accedere. Puoi trovarlo tramite l'interfaccia web di Google Calendar come segue: nel menu a discesa accanto al nome del calendario, seleziona Impostazioni calendario. Nella pagina visualizzata, l'ID calendario è visualizzato in una sezione denominata Indirizzo calendario. L'ID calendario per il calendario principale di un utente è lo stesso dell'indirizzo email di quell'utente.

Se un programma client (come Mozilla Sunbird) richiede una raccolta di calendari come punto di partenza, l'URI a cui connettersi è:

https://apidata.googleusercontent.com/caldav/v2/calid/events

Il vecchio endpoint https://www.google.com/calendar/dav è deprecato e non è più supportato; utilizzalo a tuo rischio. Ti consigliamo di passare al nuovo formato dell'endpoint descritto sopra.

iCal® è un marchio di Apple Inc.