Guida per gli sviluppatori dell'API CalDAV

CalDAV è un'estensione di WebDAV che fornisce uno standard per consentire ai client di 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 ognuna delle specifiche pertinenti, il supporto CalDAV di Google è il seguente:

  • rfc4918: HTTP Extensions for Web Distributed Authoring and Versioning (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* (ad eccezione di If-Match).
    • Non supporta le proprietà WebDAV arbitrarie (definite dall'utente).
    • Non supporta il controllo degli accessi WebDAV (rfc3744).
  • rfc4791: Calendaring Extensions to WebDAV (CalDAV)
    • Supporta il metodo HTTP REPORT. Sono implementati tutti i report, ad eccezione di free-busy-query.
    • 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à URL impostabili dall'utente.
  • rfc6578: Collection Synchronization for WebDAV
    • Le applicazioni client devono passare a questa modalità di funzionamento dopo la sincronizzazione iniziale.
  • rfc6638: Scheduling Extensions to CalDAV
    • Supporta una "posta in arrivo" banale, che è sempre vuota.
    • Gli inviti che ricevi vengono recapitati automaticamente nella raccolta "eventi" anziché nella "posta in arrivo".
    • Non supporta la ricerca della disponibilità.
  • caldav-ctag-02: Calendar Collection Entity Tag (CTag) in CalDAV
    • Il tag ctag del calendario è simile a un tag etag della risorsa; cambia quando viene modificato qualsiasi elemento del calendario. In questo modo, l'applicazione client può determinare rapidamente che non è necessario sincronizzare gli eventi modificati.
  • calendar-proxy: Calendar User Proxy Functionality in CalDAV
    • Per migliorare il rendimento 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 un UserAgent iOS non andrà a buon fine.

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

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

Creazione dell'ID client

Per utilizzare l'API CalDAV, devi avere un Account Google. Se hai già un account che puoi utilizzare, non devi fare altro.

Prima di poter inviare richieste all'API CalDAV, devi registrare il tuo client con la 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 consiste nell'attivare l'API CalDAV.

Per attivare un'API per il tuo progetto:

  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 attivare non è visibile nell'elenco, utilizza la ricerca per trovarla.
  3. Seleziona l'API che vuoi attivare, poi fai clic sul pulsante Attiva.
  4. Se richiesto, attiva 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:

  1. Seleziona una credenziale OAuth 2.0 esistente o apri la pagina Credenziali.
  2. Se non l'hai ancora 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 del calendario in uno dei due punti di partenza. In entrambi i casi, la connessione deve essere stabilita tramite HTTPS e deve utilizzare lo schema di autenticazione OAuth 2.0. Il server CalDAV rifiuterà di autenticare una richiesta a meno che non arrivi tramite HTTPS con l'autenticazione OAuth 2.0 di un Account Google. Il tentativo di connessione tramite HTTP o l'utilizzo dell'autenticazione di base genera un codice di stato HTTP 401 Unauthorized.

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

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

Dove valid deve essere sostituito dall'"ID calendario" del calendario a cui accedere. Puoi trovare questo ID tramite l'interfaccia web di Google Calendar nel seguente modo: nel menu a discesa accanto al nome del calendario, seleziona Impostazioni calendario. Nella pagina risultante, l'ID calendario viene visualizzato in una sezione denominata Indirizzo calendario. L'ID calendario del calendario principale di un utente è lo stesso dell'indirizzo email dell'utente.

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

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

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

iCal® è un marchio di Apple Inc.