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 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

Le specifiche complete non sono implementate, ma molti client come Contatti Apple iOSTM e macOS dovrebbe interoperare correttamente.

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

rfc2518: Estensioni HTTP per la creazione distribuita (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 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: estensioni vCard per Web Distributed Authoring e Controllo delle versioni (WebDAV)
- Supporta il metodo HTTP REPORT, ma non tutti i report definiti lo sono implementate.
- Supporta la fornitura di una raccolta di entità e 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: 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 altri metodi di autenticazione. Per proteggere i dati di contatto, richiediamo l'utilizzo delle connessioni CardDAV HTTPS.
rfc6764: Localizzazione dei servizi per il calendario delle estensioni per WebDAV (CalDAV) e delle estensioni vCard per WebDAV (CardDAV)
- L'avvio degli URL CardDAV deve avvenire in conformità alla sezione 6 di rfc6764
Supporta caldav-ctag-02: Tag dell'entità della raccolta del calendario (CTag) in CalDAV, condiviso tra le specifiche CardDAV e CalDAV. I contatti ctag è come una risorsa ETag; cambia quando è presente qualcosa nel contatto è cambiata. Ciò consente al programma client di determinare rapidamente che non sia necessario sincronizzare i contatti modificati.
Google utilizza VCard 3.0 come formato di codifica dei contatti. Consulta: 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:

Connessione al server CardDAV di Google

Il protocollo CardDAV consente il rilevamento della rubrica e delle risorse di contatto per gli URI. Non devi impostare alcun URI come hardcoded perché potrebbe 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 l'autenticazione di base o con Se un'email/una password non corrisponde a un Account Google, viene generato un messaggio HTTP Codice di risposta 401 Unauthorized.

Per utilizzare CardDAV, il tuo programma client deve inizialmente connettersi alla versione canonica del percorso di rilevamento eseguendo un PROPFIND HTTP su:

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

Dopo il reindirizzamento (HTTP 301) a una risorsa della rubrica, il programma client può quindi eseguire un PROPFIND per scoprire DAV:current-user-principal, DAV:principal-URL e addressbook-home-set proprietà. Il tuo programma client può quindi trovare la rubrica principale eseguendo un PROPFIND in addressbook-home-set e cercando il Risorse addressbook e collection. Una descrizione completa della procedura esula dall'ambito di applicazione del presente documento. Consulta rfc6352 per ulteriori dettagli.

Percorso di reindirizzamento restituito nella risposta HTTP 301 tramite PROPFIND su l'URI noto non deve essere memorizzato in modo permanente nella cache (come 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 ogni 2-4 settimane.

Risorse

CardDAV utilizza i concetti REST. Le applicazioni client agiscono su risorse designati dai rispettivi 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. Piuttosto, le risorse devono essere secondo RFC.

Preside
- https://www.googleapis.com/carddav/v1/principals/userEmail
Set per la casa
- 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. Sviluppatori deve cercare i dettagli nel documento RFC pertinente. Le richieste e le risposte vengono principalmente codificati in XML. Queste sono le operazioni principali utilizzate dal client applicazioni per la sincronizzazione:

Utilizzo di 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à la modifica dei contatti è garantita. Applicazioni client dovrebbe archiviare questo valore e utilizzarlo solo nella sincronizzazione iniziale e come di riserva quando un sync-token viene invalidato. Sondaggio periodico per getctag proprietà comporterà una limitazione.
Utilizzo del token di sincronizzazione
- I programmi client utilizzano la richiesta sync-token PROPFIND all'indirizzo Libro per ottenere il sync-token che rappresenta il suo stato attuale. Cliente le applicazioni devono archiviare questo valore ed emettere periodicamente sync-collection REPORT richieste per determinare le modifiche dall'ultima emissione sync-token. I token emessi sono validi per 29 giorni e il REPORT la risposta conterrà un nuovo sync-token.
Utilizzo degli ETag
- Le applicazioni client inviano una richiesta getetag PROPFIND all'indirizzo Risorsa libro (con intestazione DEPTH uguale a DEPTH_1). Mantenendo il valore ETag di ogni contatto, un programma client può richiedere il valore di contatti a cui è stato modificato il valore ETag.
Recupero dei contatti
- Le applicazioni client recuperano i contatti tramite l'emissione di un Richiesta addressbook-multiget REPORT. Dato un elenco di URI dei contatti, Il report restituisce tutti i contatti richiesti come valori VCard 3.0. Ciascuna voce include un ETag per il contatto.
Inserimento di un contatto
- Le applicazioni client inviano una richiesta POST con il nuovo contatto in 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 VCard 3.0. Il contatto viene aggiornato se esiste già. nella rubrica.
- Le applicazioni client devono includere un'intestazione If-Match con attualmente noto del contatto ETag. Il server rifiuterà PUT (con HTTP 412) se l'attuale ETag sul server è diverso da ETag inviato dal programma client. Ciò consente serializzazione ottimista degli aggiornamenti.
Eliminare un contatto
- Le applicazioni client eliminano un contatto inviando una richiesta DELETE e l'URI del contatto.