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
ePROPFIND
. - Non supporta i metodi HTTP
LOCK
,UNLOCK
,COPY
,MOVE
oMKCOL
. - Non supporta proprietà WebDAV arbitrarie (definite dall'utente).
- Non supporta il controllo dell'accesso WebDAV (rfc3744).
- Supporta i metodi HTTP
- 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.
- Supporta il metodo HTTP
- 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 risorsaETag
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:
- Utilizzare OAuth 2.0 per accedere alle API di Google
- Utilizzare OAuth 2.0 per le applicazioni installate
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
- https://www.googleapis.com/carddav/v1/principals/
- Set Home
- https://www.googleapis.com/carddav/v1/principals/
userEmail
/lists
- https://www.googleapis.com/carddav/v1/principals/
- Rubrica
- https://www.googleapis.com/carddav/v1/principals/
userEmail
/lists/default
- https://www.googleapis.com/carddav/v1/principals/
- Contatto
- https://www.googleapis.com/carddav/v1/principals/
userEmail
/lists/default/contactId
- https://www.googleapis.com/carddav/v1/principals/
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 unsync-token
viene invalidato. Il polling periodico della proprietàgetctag
comporterà una limitazione.
- I programmi client utilizzano la richiesta
- Utilizzo del token di sincronizzazione
- I programmi client utilizzano la richiesta
sync-token
PROPFIND
nella rubrica per ottenere ilsync-token
che rappresenta il suo stato attuale. Le applicazioni client devono archiviare questo valore ed emettere richiestesync-collection
REPORT
periodiche per determinare le modifiche dall'ultima emissionesync-token
. I token emessi sono validi per 29 giorni e la rispostaREPORT
conterrà un nuovosync-token
.
- I programmi client utilizzano la richiesta
- Utilizzo degli ETag
- Le applicazioni client emettono una richiesta
PROPFIND
getetag
nella risorsa rubrica (con intestazioneDEPTH
uguale aDEPTH_1
). Mantenendo il valoreETag
di ciascun contatto, un programma client può richiedere il valore dei contatti che hanno modificato il valoreETag
.
- Le applicazioni client emettono una richiesta
- 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 unETag
per il contatto.
- Le applicazioni client recuperano i contatti mediante l'invio di una richiesta
- 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.
- Le applicazioni client inviano una richiesta
- 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'intestazioneETag
attualmente nota del contatto. Il server rifiuterà quindi la richiestaPUT
(conHTTP 412
) se l'attualeETag
sul server è diverso dalETag
inviato dal programma client. Ciò consente una serializzazione ottimale degli aggiornamenti.
- Le applicazioni client inviano una richiesta
- Eliminare un contatto
- Le applicazioni client eliminano un contatto inviando una richiesta
DELETE
contro l'URI del contatto.
- Le applicazioni client eliminano un contatto inviando una richiesta