Questa pagina è stata tradotta dall'API Cloud Translation.

Gestione dei contatti con il protocollo CardDAV

Puoi visualizzare e gestire i tuoi contatti utilizzando il protocollo CardDAV di Google.

I contatti vengono memorizzati nell'Account Google dell'utente; la maggior parte dei servizi Google ha accesso all'elenco contatti. L'applicazione client può utilizzare l'API CardDAV per creare nuovi contatti, modificare o eliminare contatti esistenti ed eseguire query per contatti che corrispondono a criteri specifici.

Specifiche

La specifica completa non è implementata, ma molti client come i contatti Apple iOSTM e macOS dovrebbero interagire correttamente.

Per ogni specifica pertinente, il supporto CardDAV di Google è il seguente:

rfc2518: HTTP Extensions for Distributed Authoring (WebDAV)
- Supporta i metodi HTTP GET, PUT, DELETE, OPTIONS e PROPFIND.
- Non supporta i metodi HTTP LOCK, UNLOCK, COPY, MOVE o MKCOL.
- Non supporta proprietà WebDAV arbitrarie (definite dall'utente).
- Non supporta il controllo dell'accesso WebDAV (rfc3744).
rfc5995: utilizzo di POST per aggiungere membri alle raccolte WebDAV
- Supporta la creazione di nuovi contatti senza specificare un ID.
rfc6352: CardDAV: vCard Extensions to Web Distributed Authoring and Versioning (WebDAV)
- Supporta il metodo HTTP REPORT, ma non tutti i report definiti sono implementati.
- Supporta la fornitura di una raccolta di entità e di una raccolta di contatti.
rfc6578: Sincronizzazione delle raccolte per WebDAV
- Le applicazioni client devono passare a questa modalità operativa dopo la sincronizzazione iniziale.
rfc6749: Il framework di autorizzazione OAuth 2.0 e rfc6750: Il framework di autorizzazione OAuth 2.0: utilizzo del token di connessione
- Supporta l'autenticazione dei programmi client CardDAV utilizzando l'autenticazione HTTP OAuth 2.0. Google non supporta altri metodi di autenticazione. Per la sicurezza dei dati dei contatti, richiediamo le connessioni CardDAV per utilizzare HTTPS.
rfc6764: Individuazione dei servizi per il calendario delle estensioni in WebDAV (CalDAV) e delle estensioni vCard per WebDAV (CardDAV)
- Il bootstrap degli URL CardDAV deve avvenire in base alla sezione 6 di rfc6764.
Supporta caldav-ctag-02: Calendar Collection Entity Tag (CTag) in CalDAV, che è condiviso tra le specifiche CardDAV e CalDAV. Il contatto ctag è come una risorsa ETag e cambia ogni volta che viene modificata una voce nella rubrica dei contatti. Ciò consente al programma client di determinare rapidamente che non è necessario sincronizzare i contatti modificati.
Google utilizza VCard 3.0 come formato di codifica dei contatti. Vedi: rfc6350: VCard 3.0.

CardDAV di Google richiede OAuth 2.0

L'interfaccia CardDAV di Google richiede OAuth 2.0. Consulta la documentazione collegata di seguito per informazioni sull'utilizzo di OAuth 2.0 per accedere alle API di Google:

Connessione al server CardDAV di Google

Il protocollo CardDAV consente il rilevamento degli URI della rubrica e delle risorse di contatto. Non devi codificare in modo hardcoded gli URI, poiché potrebbero essere modificati in qualsiasi momento.

Le applicazioni client devono utilizzare HTTPS e deve essere fornita l'autenticazione OAuth 2.0 per l'Account Google dell'utente. Il server CardDAV non autentica le richieste a meno che non arrivi tramite HTTPS con autenticazione OAuth 2.0 di un Account Google e che l'applicazione non sia registrata su DevConsole. Qualsiasi tentativo di connessione tramite HTTP con l'autenticazione di base o con un'email/password che non corrisponde a un Account Google genera un codice di risposta HTTP 401 Unauthorized.

Per utilizzare CardDAV, il tuo programma client deve inizialmente connettersi al percorso di rilevamento canonico eseguendo un PROPFIND HTTP su:

https://www.googleapis.com/.well-known/carddav

Una volta reindirizzato (HTTP 301) a una risorsa rubrica, il tuo programma client può eseguire un PROPFIND su di essa per scoprire le proprietà DAV:current-user-principal, DAV:principal-URL e addressbook-home-set. Il programma cliente può quindi trovare la rubrica principale eseguendo una PROPFIND sulla addressbook-home-set e cercando le risorse addressbook e collection. Una descrizione completa di questo processo non rientra nell'ambito di questo documento. Per ulteriori dettagli, consulta rfc6352.

Il percorso di reindirizzamento restituito nella risposta HTTP 301 tramite un PROPFIND nell'URI noto non deve essere memorizzato nella cache in modo permanente (come da rfc6764). I dispositivi devono ritentare periodicamente il rilevamento URI noto per verificare se il percorso memorizzato nella cache è ancora aggiornato e risincronizzarsi in caso di modifiche. Google consiglia una frequenza di 2-4 settimane.

Risorse

CardDAV utilizza i concetti REST. Le applicazioni client agiscono sulle risorse designate dai rispettivi URI. La struttura dell'URI attuale è specificata qui per aiutare gli sviluppatori a comprendere i concetti nella sezione seguente. La struttura potrebbe cambiare e non deve essere impostata come hardcoded. Piuttosto, le risorse dovrebbero essere rilevate in base alla RFC.

Entità
- https://www.googleapis.com/carddav/v1/principals/userEmail
Set Home
- https://www.googleapis.com/carddav/v1/principals/userEmail/lists
Rubrica
- https://www.googleapis.com/carddav/v1/principals/userEmail/lists/default
Contatto
- https://www.googleapis.com/carddav/v1/principals/userEmail/lists/default/contactId

Sincronizzazione dei contatti

Di seguito è riportata una descrizione generale delle operazioni supportate. Gli sviluppatori devono cercare i dettagli nella RFC pertinente. Le richieste e le risposte sono per lo più codificate in XML. Di seguito sono riportate le operazioni principali utilizzate dalle applicazioni client per la sincronizzazione:

Utilizzo di CTag
- I programmi client utilizzano la richiesta getctag PROPFIND sulla risorsa della rubrica per determinare se sono stati modificati contatti sul server e, quindi, se è necessaria una sincronizzazione. Il valore di questa proprietà può variare in caso di variazioni del contatto. Le applicazioni client devono archiviare questo valore e utilizzarlo solo durante la sincronizzazione iniziale e come riserva quando un sync-token viene invalidato. Il polling periodico della proprietà getctag comporterà una limitazione.
Utilizzo del token di sincronizzazione
- I programmi client utilizzano la richiesta sync-token PROPFIND nella rubrica per ottenere il sync-token che rappresenta il suo stato attuale. Le applicazioni client devono archiviare questo valore ed emettere richieste sync-collection REPORT periodiche per determinare le modifiche dall'ultima emissione sync-token. I token emessi sono validi per 29 giorni e la risposta REPORT conterrà un nuovo sync-token.
Utilizzo degli ETag
- Le applicazioni client emettono una richiesta PROPFIND getetag nella risorsa rubrica (con intestazione DEPTH uguale a DEPTH_1). Mantenendo il valore ETag di ciascun contatto, un programma client può richiedere il valore dei contatti che hanno modificato il valore ETag.
Recupero dei contatti
- Le applicazioni client recuperano i contatti mediante l'invio di una richiesta addressbook-multiget REPORT. Fornito un elenco di URI di contatto, il rapporto restituisce tutti i contatti richiesti come valori VCard 3.0. Ogni voce include un ETag per il contatto.
Inserimento di un contatto
- Le applicazioni client inviano una richiesta POST con il nuovo contatto in formato VCard 3.0. La risposta conterrà l'ID del nuovo contatto.
Aggiornare un contatto
- Le applicazioni client inviano una richiesta PUT con il contatto aggiornato in formato VCard 3.0. Il contatto viene aggiornato se esiste già nella rubrica.
- Le applicazioni client devono includere un'intestazione If-Match con l'intestazione ETag attualmente nota del contatto. Il server rifiuterà quindi la richiesta PUT (con HTTP 412) se l'attuale ETag sul server è diverso dal ETag inviato dal programma client. Ciò consente una serializzazione ottimale degli aggiornamenti.
Eliminare un contatto
- Le applicazioni client eliminano un contatto inviando una richiesta DELETE contro l'URI del contatto.