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.

L'API CalDAV ha gli stessi limiti di quota dell'API Calendar. Per ulteriori informazioni, consulta Limiti di utilizzo.

Specifiche

Per ciascuna 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, MKCOL, o l'intestazione If* (tranne 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 tranne 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.
    • 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 inviati automaticamente alla raccolta "eventi" anziché essere inseriti nella "posta in arrivo".
    • Non supporta la ricerca free-busy.

  • 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 le prestazioni di sincronizzazione del calendario, le richieste che includono le proprietà calendar-proxy-read-for o calendar-proxy-write-for non andranno a buon fine con un UserAgent iOS perché i dispositivi iOS non supportano la delega.

Sebbene la nostra implementazione CalDAV non copra tutte le specifiche, funziona correttamente per molti client, tra cui Apple Calendar.

Creare l'ID client

Per utilizzare l'API CalDAV devi avere un Account Google.

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

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

Ora devi attivare l'API CalDAV.

Per abilitare un'API per il tuo progetto:

  1. Apri la libreria API nella console dell'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 che vuoi abilitare, poi 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 , devi disporre di un ID client e di un 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.

Connettersi 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 rifiuta 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 Calendar di Apple) richiede una raccolta principale come punto di partenza, l'URI a cui connettersi è:

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

Sostituisci CALENDAR_ID con l'ID del calendario a cui accedere.

Per trovare l'ID calendario tramite l'interfaccia web, seleziona ** Impostazioni calendario** nel menu a discesa accanto al nome del calendario. 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 Thunderbird) richiede una raccolta di calendari come punto di partenza, utilizza il seguente URI:

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