Puoi visualizzare e gestire i tuoi contatti utilizzando il protocollo CardDAV di Google.
I contatti vengono archiviati nell'Account Google dell'utente. la maggior parte dei servizi Google ha l'accesso all'elenco contatti. L'applicazione client può utilizzare l'API CardDAV per creare nuovi contatti, modificare o eliminare contatti esistenti ed eseguire query sui contatti che soddisfano determinati criteri.
Specifiche
La specifica completa non è implementata, ma molti client come Contatti di Apple iOS™ e macOS dovrebbero interoperare correttamente.
Per ogni specifica pertinente, il supporto CardDAV di Google è il seguente:
- rfc2518: Estensioni HTTP per l'autoreferenzialità (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: estensioni vCard per Web Distributed Authoring e
Controllo delle versioni (WebDAV)
- Supporta il metodo HTTP
REPORT
, ma non tutti i report definiti sono implementati. - Supporta la fornitura di una raccolta principale e 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: Framework di autorizzazione OAuth 2.0: utilizzo del token di connessione
- Supporta l'autenticazione dei programmi client CardDAV tramite OAuth 2.0 HTTP Autenticazione. Google non supporta nessun altro metodo di autenticazione. Per la sicurezza dei dati dei contatti, è necessario che le connessioni CardDAV utilizzino HTTPS.
- rfc6764: Localizzazione dei servizi per il calendario delle estensioni per 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: Tag entità raccolta calendario (CTag) in CalDAV,
che è condiviso tra le specifiche CardDAV e CalDAV. I contatti
ctag
è come una risorsaETag
; cambia quando è presente qualcosa nel contatto è cambiata. In questo modo, il programma client può 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. Fai riferimento ai documentazione 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 della rubrica e delle risorse di contatto per gli URI. Non devi codificare alcun URI, in quanto potrebbero cambiare in qualsiasi momento.
Le applicazioni client devono utilizzare HTTPS e l'autenticazione OAuth 2.0
deve essere
fornito per l'Account Google dell'utente. Il server CardDAV non
Autenticare una richiesta a meno che non arrivi tramite HTTPS con OAuth 2.0
l'autenticazione di un Account Google e la tua applicazione sia registrata
in DevConsole. Qualsiasi tentativo di connessione tramite HTTP con 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 programma client deve inizialmente connettersi al percorso di ricerca canonico eseguendo un PROPFIND
HTTP su:
https://www.googleapis.com/.well-known/carddav
Una volta reindirizzato (HTTP 301
) a una risorsa di rubrica, il programma client può eseguire un PROPFIND
per scoprire le proprietà DAV:current-user-principal
, DAV:principal-URL
e addressbook-home-set
. Il programma client può quindi scoprire la rubrica principale eseguendo un PROPFIND
sul addressbook-home-set
e cercando le risorse addressbook
e collection
. Una descrizione completa della procedura
esula dall'ambito di applicazione del presente documento. Consulta:
rfc6352 per ulteriori dettagli.
Il percorso di reindirizzamento restituito nella risposta HTTP 301
tramite un PROPFIND
sull'URI noto non deve essere memorizzato nella cache in modo permanente (come da rfc6764). I dispositivi dovrebbero riprovare (noti)
il rilevamento dell'URI periodicamente per verificare se il percorso memorizzato nella cache è ancora aggiornato
risincronizza se il percorso cambia. Google consiglia una frequenza di ogni 2-4 settimane.
Risorse
CardDAV utilizza i concetti REST. Le applicazioni client agiscono sulle risorse designate dai relativi URI. L'attuale struttura URI è specificata qui per aiutare gli sviluppatori hanno compreso i concetti nella sezione seguente. La struttura può modificare e non devono essere impostati come hardcoded. Le risorse devono essere rilevate in base all'RFC.
- Preside
- https://www.googleapis.com/carddav/v1/principals/
userEmail
- https://www.googleapis.com/carddav/v1/principals/
- Set per la casa
- 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 nell'RFC pertinente. Le richieste e le risposte sono principalmente codificate in XML. Queste sono le operazioni principali utilizzate dal client applicazioni per la sincronizzazione:
- Utilizzare CTag
- I programmi client utilizzano la richiesta
getctag
PROPFIND
nella rubrica risorsa per determinare se un contatto è stato modificato sul server e quindi se è necessaria una sincronizzazione. Il valore di questa proprietà è garantito per cambiare se un contatto cambia. Le applicazioni client devono memorizzare questo valore e utilizzarlo solo per la sincronizzazione iniziale e come alternativa quando unsync-token
viene invalidato. Sondaggio periodico pergetctag
proprietà comporterà una limitazione.
- I programmi client utilizzano la richiesta
- Utilizzo del token di sincronizzazione
- I programmi client utilizzano la richiesta
sync-token
PROPFIND
nell'Address Book per ottenere ilsync-token
che rappresenta il suo stato corrente. Cliente le applicazioni devono archiviare questo valore ed emettere periodicamentesync-collection
REPORT
richieste per determinare le modifiche dall'ultima emissionesync-token
. I token emessi sono validi per 29 giorni e la rispostaREPORT
contiene un nuovosync-token
.
- I programmi client utilizzano la richiesta
- Utilizzare gli ETag
- Le applicazioni client inviano una richiesta
getetag
PROPFIND
alla risorsa AddressBook (con intestazioneDEPTH
uguale aDEPTH_1
). Mantenendo il valoreETag
di ogni contatto, un programma client può richiedere il valore dei contatti di cui è stato modificato il valoreETag
.
- Le applicazioni client inviano una richiesta
- Recupero dei contatti
- Le applicazioni client recuperano i contatti tramite l'emissione di un
Richiesta
addressbook-multiget
REPORT
. Dato un elenco di URI di contatto, il report restituisce tutti i contatti richiesti come valori VCard 3.0. Ogni voce include unETag
per il contatto.
- Le applicazioni client recuperano i contatti tramite l'emissione di un
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 VCard 3.0. Il contatto viene aggiornato se esiste già. nella rubrica. - Le applicazioni client devono includere un'intestazione
If-Match
con ilETag
attualmente noto del contatto. Il server rifiuteràPUT
(conHTTP 412
) se l'attualeETag
sul server è diverso daETag
inviato dal programma client. Ciò consente una serializzazione ottimistica 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