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

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 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: 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.
• 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 risorsa ETag; 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.

1. Preside
   • https://www.googleapis.com/carddav/v1/principals/userEmail
2. Set per la casa
   • https://www.googleapis.com/carddav/v1/principals/userEmail/lists
3. Rubrica
   • https://www.googleapis.com/carddav/v1/principals/userEmail/lists/default
4. 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 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 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 nell'Address Book per ottenere il sync-token che rappresenta il suo stato corrente. 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 la risposta REPORT contiene un nuovo sync-token.
• Utilizzare gli ETag
  • Le applicazioni client inviano una richiesta getetag PROPFIND alla risorsa AddressBook (con intestazione DEPTH uguale a DEPTH_1). Mantenendo il valore ETag di ogni contatto, un programma client può richiedere il valore dei contatti di 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 di contatto, il report 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 VCard 3.0. Il contatto viene aggiornato se esiste già. nella rubrica.
  • Le applicazioni client devono includere un'intestazione If-Match con il ETag attualmente noto del contatto. Il server rifiuterà PUT (con HTTP 412) se l'attuale ETag sul server è diverso da ETag inviato dal programma client. Ciò consente una serializzazione ottimistica degli aggiornamenti.
• Eliminare un contatto
  • Le applicazioni client eliminano un contatto inviando una richiesta DELETE contro l'URI del contatto.