Gestione dei contatti con il protocollo CardDAV
Mantieni tutto organizzato con le raccolte
Salva e classifica i contenuti in base alle tue preferenze.
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:
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
- 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
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.
Salvo quando diversamente specificato, i contenuti di questa pagina sono concessi in base alla licenza Creative Commons Attribution 4.0, mentre gli esempi di codice sono concessi in base alla licenza Apache 2.0. Per ulteriori dettagli, consulta le norme del sito di Google Developers. Java è un marchio registrato di Oracle e/o delle sue consociate.
Ultimo aggiornamento 2025-07-25 UTC.
[[["Facile da capire","easyToUnderstand","thumb-up"],["Il problema è stato risolto","solvedMyProblem","thumb-up"],["Altra","otherUp","thumb-up"]],[["Mancano le informazioni di cui ho bisogno","missingTheInformationINeed","thumb-down"],["Troppo complicato/troppi passaggi","tooComplicatedTooManySteps","thumb-down"],["Obsoleti","outOfDate","thumb-down"],["Problema di traduzione","translationIssue","thumb-down"],["Problema relativo a esempi/codice","samplesCodeIssue","thumb-down"],["Altra","otherDown","thumb-down"]],["Ultimo aggiornamento 2025-07-25 UTC."],[[["\u003cp\u003eGoogle Contacts can be accessed and managed using the CardDAV protocol, enabling client applications to create, edit, delete, and query contacts.\u003c/p\u003e\n"],["\u003cp\u003eGoogle's CardDAV implementation requires OAuth 2.0 for authentication and HTTPS for secure connections.\u003c/p\u003e\n"],["\u003cp\u003eClient applications should discover resource URIs dynamically instead of hardcoding them, as they are subject to change.\u003c/p\u003e\n"],["\u003cp\u003eContact synchronization can be achieved using CTag, sync-token, or ETags to efficiently track and update changes.\u003c/p\u003e\n"],["\u003cp\u003eGoogle's CardDAV utilizes VCard 3.0 for encoding contact data.\u003c/p\u003e\n"]]],["Google's CardDAV protocol allows managing contacts stored in a Google Account. Client applications can create, edit, delete, and query contacts using the CardDAV API. Key actions include using `PROPFIND` for discovery and obtaining `sync-token` and `getctag` for synchronization. Retrieving contacts is done with `addressbook-multiget REPORT`, while inserting, updating, and deleting contacts utilize `POST`, `PUT` (with `If-Match`), and `DELETE` requests, respectively. Authentication requires HTTPS and OAuth 2.0, and VCard 3.0 is the contact encoding format.\n"],null,["# Manage contacts with the CardDAV protocol\n\nYou can view and manage your contacts using Google's CardDAV protocol.\n\nContacts are stored in the user's Google Account; most Google services have\naccess to the contact list. Your client application can use the CardDAV API to\ncreate new contacts, edit or delete existing contacts, and query for contacts\nthat match particular criteria.\n\nSpecifications\n--------------\n\nThe full specification is not implemented, but many clients such as\n[Apple iOS™ Contacts](https://support.google.com/contacts/answer/2753077?co=GENIE.Platform%3DiOS)\nand macOS should interoperate correctly.\n\nFor each relevant specification, Google's CardDAV support is as follows:\n\n- [rfc2518: HTTP Extensions for Distributed Authoring (WebDAV)](https://tools.ietf.org/html/rfc2518)\n - Supports the HTTP methods `GET`, `PUT`, `DELETE`, `OPTIONS`, and `PROPFIND`.\n - Does *not* support the HTTP methods `LOCK`, `UNLOCK`, `COPY`, `MOVE`, or `MKCOL`.\n - Does *not* support arbitrary (user-defined) WebDAV properties.\n - Does *not* support WebDAV Access Control (rfc3744).\n- [rfc5995: Using POST to Add Members to WebDAV Collections](https://tools.ietf.org/html/rfc5995)\n - Supports creating new contacts without specifying an ID.\n- [rfc6352: CardDAV: vCard Extensions to Web Distributed Authoring and\n Versioning (WebDAV)](https://tools.ietf.org/html/rfc6352)\n - Supports the HTTP method `REPORT`, but not all defined reports are implemented.\n - Supports providing a principal collection and a contacts collection.\n- [rfc6578: Collection Synchronization for WebDAV](https://tools.ietf.org/html/rfc6578)\n - Client applications must switch to this mode of operation after the initial sync.\n- [rfc6749: The OAuth 2.0 Authorization Framework](https://tools.ietf.org/html/rfc6749) and [rfc6750: The OAuth 2.0 Authorization Framework: Bearer Token Usage](https://tools.ietf.org/html/rfc6750)\n - Supports authenticating CardDAV client programs using OAuth 2.0 HTTP Authentication. Google does not support any other authentication method. For security of contact data, we require CardDAV connections to use [HTTPS](https://en.wikipedia.org/wiki/HTTPS).\n- [rfc6764: Locating Services for Calendaring Extensions to WebDAV (CalDAV) and vCard Extensions to WebDAV (CardDAV)](https://tools.ietf.org/html/rfc6764)\n - Bootstrapping of CardDAV URLs must take place according to section 6 of rfc6764.\n- Supports [caldav-ctag-02: Calendar Collection Entity Tag (CTag) in CalDAV](https://github.com/apple/ccs-calendarserver/blob/master/doc/Extensions/caldav-ctag.txt), which is shared between the CardDAV and CalDAV specifications. The contacts `ctag` is like a resource `ETag`; it changes when anything in the contact address book has changed. This allows the client program to quickly determine that it does not need to synchronize any changed contacts.\n- Google uses VCard 3.0 as the contact encoding format. See: [rfc6350: VCard 3.0](https://tools.ietf.org/html/rfc6350).\n\nGoogle's CardDAV requires OAuth 2.0\n-----------------------------------\n\nGoogle's CardDAV interface requires OAuth 2.0. Refer to the linked\ndocumentation below for information on using OAuth 2.0 to access Google APIs:\n\n- [Using OAuth 2.0 to Access Google APIs](https://developers.google.com/identity/protocols/oauth2)\n- [Using OAuth 2.0 for Installed Applications](https://developers.google.com/identity/protocols/oauth2/native-app)\n\nConnecting to Google's CardDAV server\n-------------------------------------\n\nThe CardDAV protocol allows discovery of the address book and contact resources\nURIs. You must not hardcode any URI as they could change at any time.\n\nClient applications must use HTTPS, and `OAuth 2.0` authentication must be\nprovided for the user's Google account. The CardDAV server will not\nauthenticate a request unless it arrives over HTTPS with OAuth 2.0\nauthentication of a Google account, and your application is registered on\nDevConsole. Any attempt to connect over HTTP with Basic authentication or with\nan email/password that doesn't match a Google account results in an HTTP\n`401 Unauthorized` response code.\n\nTo use CardDAV, your client program must initially connect to the canonical\ndiscovery path by performing an HTTP `PROPFIND` on: \n\n https://www.googleapis.com/.well-known/carddav\n\nOnce redirected (`HTTP 301`) to an Address Book Resource, your client program\ncan then perform a `PROPFIND` on it to discover the\n`DAV:current-user-principal`, `DAV:principal-URL`, and `addressbook-home-set`\nproperties. Your client program can then discover the principal address book by\nperforming a `PROPFIND` on the `addressbook-home-set` and looking for the\n`addressbook` and `collection` resources. A full description of this process\nis beyond the scope of this document. See\n[rfc6352](https://tools.ietf.org/html/rfc6352) for more details.\n\nThe redirect path returned in the `HTTP 301` response through a `PROPFIND` on\nthe well-known URI must **not** be permanently cached (as per\n[rfc6764](https://tools.ietf.org/html/rfc6764)). Devices should retry well-known\nURI discovery periodically to verify if the cached path is still up to date and\nresync if the path ever changes. Google recommends a rate of every 2-4 weeks.\n\nResources\n---------\n\nCardDAV uses REST concepts. Client applications act on resources that are\ndesignated by their URIs. The current URI structure is specified here to help\ndevelopers understand the concepts in the following section. The structure may\nchange and must not be hardcoded. Rather, the resources should be discovered\naccording to the RFC.\n\n1. **Principal**\n - https://www.googleapis.com/carddav/v1/principals/\u003cvar class=\"apiparam\" translate=\"no\"\u003euserEmail\u003c/var\u003e\n2. **Home Set**\n - https://www.googleapis.com/carddav/v1/principals/\u003cvar class=\"apiparam\" translate=\"no\"\u003euserEmail\u003c/var\u003e/lists\n3. **Address Book**\n - https://www.googleapis.com/carddav/v1/principals/\u003cvar class=\"apiparam\" translate=\"no\"\u003euserEmail\u003c/var\u003e/lists/default\n4. **Contact**\n - https://www.googleapis.com/carddav/v1/principals/\u003cvar class=\"apiparam\" translate=\"no\"\u003euserEmail\u003c/var\u003e/lists/default/\u003cvar class=\"apiparam\" translate=\"no\"\u003econtactId\u003c/var\u003e\n\nSynchronizing Contacts\n----------------------\n\nThe following is a general description of the operations supported. Developers\nshould look for the details in the relevant RFC. Requests and responses are\nmostly encoded in XML. These are the main operations used by client\napplications for synchronization:\n\n- **Using CTag**\n - Client programs use the `getctag` `PROPFIND` request on the Address Book resource to determine if any contact has changed on the server and therefore whether a synchronization is needed. The value of this property is guaranteed to change if any contact changes. Client applications should store this value and use it only on the initial sync and as a fallback when a `sync-token` is invalidated. Periodically polling for the `getctag` property will result in throttling.\n- **Using sync-token**\n - Client programs use the `sync-token` `PROPFIND` request on the Address Book to obtain the `sync-token` representing its current state. Client applications must store this value and issue periodic `sync-collection` `REPORT` requests to determine changes since the last issued `sync-token`. Issued tokens are valid for 29 days, and the `REPORT` response will contain a new `sync-token`.\n- **Using ETags**\n - Client applications issue a `getetag` `PROPFIND` request on the Address Book resource (with `DEPTH` header equal to `DEPTH_1`). By maintaining the `ETag` value of each contact, a client program can request the value of contacts that had their `ETag` changed.\n- **Retrieving contacts**\n - Client applications retrieve contacts by issuing an `addressbook-multiget` `REPORT` request. Given a list of contact URIs, the report returns all the requested contacts as VCard 3.0 values. Each entry includes an `ETag` for the contact.\n- **Inserting a contact**\n - Client applications issue a `POST` request with the new contact in VCard 3.0 format. The response will contain the ID of the new contact.\n- **Updating a contact**\n - Client applications issue a `PUT` request with the updated contact in VCard 3.0 format. The contact is updated if the contact already exists in the address book.\n - Client applications should include an `If-Match` header with the contact's currently known `ETag`. The server will then reject the `PUT` request (with `HTTP 412`) if the current `ETag` on the server is different from the `ETag` sent by the client program. This allows for optimistic serialization of updates.\n- **Deleting a contact**\n - Client applications delete a contact by issuing a `DELETE` request against the contact URI."]]
