Vous pouvez afficher et gérer vos contacts à l'aide du protocole CardDAV de Google.
Les contacts sont stockés dans le compte Google de l'utilisateur. La plupart des services Google ont accès à la liste de contacts. Votre application cliente peut utiliser l'API CardDAV pour créer des contacts, modifier ou supprimer des contacts existants, et rechercher des contacts correspondant à des critères spécifiques.
Caractéristiques
La spécification complète n'est pas implémentée, mais de nombreux clients tels que Apple iOSTM Contacts et macOS doivent fonctionner correctement.
Pour chaque spécification pertinente, Google est compatible avec CardDAV comme suit:
- rfc2518: Extensions HTTP pour la création distribuée (WebDAV)
- Compatible avec les méthodes HTTP
GET
,PUT
,DELETE
,OPTIONS
etPROPFIND
. - N'est pas compatible avec les méthodes HTTP
LOCK
,UNLOCK
,COPY
,MOVE
ouMKCOL
. - N'est pas compatible avec les propriétés WebDAV arbitraires (définies par l'utilisateur).
- N'est pas compatible avec le contrôle des accès WebDAV (rfc3744).
- Compatible avec les méthodes HTTP
- rfc5995: Utilisation de POST pour ajouter des membres aux collections WebDAV
- Permet de créer des contacts sans spécifier d'identifiant.
- rfc6352: CardDAV: extensions vCard vers la création et la gestion des versions distribuées sur le Web (WebDAV)
- Accepte la méthode HTTP
REPORT
, mais tous les rapports définis ne sont pas implémentés. - Permet de fournir une collection principale et une collection de contacts.
- Accepte la méthode HTTP
- rfc6578: synchronisation des collections pour WebDAV
- Les applications clientes doivent passer à ce mode de fonctionnement après la synchronisation initiale.
- rfc6749: Framework d'autorisation OAuth 2.0 et rfc6750: Framework d'autorisation OAuth 2.0: utilisation des jetons de support
- Compatible avec l'authentification des programmes clients CardDAV à l'aide de l'authentification HTTP OAuth 2.0. Google n'accepte aucune autre méthode d'authentification. Pour des raisons de sécurité, les connexions CardDAV doivent utiliser HTTPS.
- rfc6764: Localisation de services pour les extensions d'agenda sur WebDAV (CalDAV) et les extensions vCard vers WebDAV (CardDAV)
- L'amorçage des URL CardDAV doit avoir lieu conformément à la section 6 de rfc6764.
- Compatibilité avec caldav-ctag-02: Calendar Collection Entity Tag (CTag) dans CalDAV, qui est partagé entre les spécifications CardDAV et CalDAV. Le contact
ctag
est semblable à une ressourceETag
: il change lorsqu'un élément du carnet d'adresses du contact change. Cela permet au programme client de déterminer rapidement qu'il n'a pas besoin de synchroniser les contacts modifiés. - Google utilise VCard 3.0 comme format d'encodage des contacts. Consultez l'article rfc6350: VCard 3.0.
Le protocole CardDAV de Google nécessite OAuth 2.0
L'interface CardDAV de Google nécessite OAuth 2.0. Consultez la documentation associée ci-dessous pour en savoir plus sur l'utilisation d'OAuth 2.0 pour accéder aux API Google:
Se connecter au serveur CardDAV de Google
Le protocole CardDAV permet de découvrir les URI du carnet d'adresses et des ressources de contact. Vous ne devez pas coder en dur les URI, car ils pourraient être modifiés à tout moment.
Les applications clientes doivent utiliser HTTPS, et l'authentification OAuth 2.0
doit être fournie pour le compte Google de l'utilisateur. Le serveur CardDAV n'authentifie pas une requête, sauf s'il arrive sur HTTPS avec l'authentification OAuth 2.0 d'un compte Google et que votre application est enregistrée sur DevConsole. Toute tentative de connexion via HTTP avec une authentification de base ou avec une adresse e-mail/mot de passe ne correspondant pas à un compte Google entraîne un code de réponse HTTP 401 Unauthorized
.
Pour utiliser CardDAV, votre programme client doit initialement se connecter au chemin de découverte canonique en exécutant une requête HTTP PROPFIND
sur:
https://www.googleapis.com/.well-known/carddav
Une fois redirigé (HTTP 301
) vers une ressource de carnet d'adresses, votre programme client peut exécuter une requête PROPFIND
sur celle-ci pour découvrir les propriétés DAV:current-user-principal
, DAV:principal-URL
et addressbook-home-set
. Votre programme client peut ensuite découvrir le carnet d'adresses principal en exécutant une requête PROPFIND
sur le addressbook-home-set
et en recherchant les ressources addressbook
et collection
. Une description complète de ce processus
ne relève pas de ce document. Pour en savoir plus, consultez le document rfc6352.
Le chemin de redirection renvoyé dans la réponse HTTP 301
via un PROPFIND
sur l'URI connu ne doit pas être mis en cache de manière permanente (conformément à rfc6764). Les appareils doivent relancer régulièrement la découverte d'URI connus pour vérifier si le chemin d'accès mis en cache est toujours à jour et se resynchroniser si le chemin change. Google recommande un taux toutes les deux à quatre semaines.
Ressources
CardDAV utilise les concepts REST. Les applications clientes agissent sur les ressources désignées par leurs URI. La structure d'URI actuelle est spécifiée ici pour aider les développeurs à comprendre les concepts présentés dans la section suivante. La structure peut changer et ne doit pas être codée en dur. Les ressources doivent plutôt être découvertes selon le RFC.
- Compte principal
- https://www.googleapis.com/carddav/v1/principals/
userEmail
- https://www.googleapis.com/carddav/v1/principals/
- Home set
- https://www.googleapis.com/carddav/v1/principals/
userEmail
/lists
- https://www.googleapis.com/carddav/v1/principals/
- Carnet d'adresses
- https://www.googleapis.com/carddav/v1/principals/
userEmail
/lists/default
- https://www.googleapis.com/carddav/v1/principals/
- Contact
- https://www.googleapis.com/carddav/v1/principals/
userEmail
/lists/default/contactId
- https://www.googleapis.com/carddav/v1/principals/
Synchronisation des contacts
Vous trouverez ci-dessous une description générale des opérations prises en charge. Les développeurs doivent consulter les RFC pertinentes pour en savoir plus. Les requêtes et les réponses sont pour la plupart encodées au format XML. Voici les principales opérations utilisées par les applications clientes pour la synchronisation:
- Utiliser la CTag
- Les programmes clients utilisent la requête
getctag
PROPFIND
sur la ressource Carnet d'adresses pour déterminer si un contact a été modifié sur le serveur et, par conséquent, si une synchronisation est nécessaire. La valeur de cette propriété changera forcément en cas de changement de contact. Les applications clientes doivent stocker cette valeur et l'utiliser uniquement lors de la synchronisation initiale et en remplacement lorsqu'unesync-token
n'est pas valide. L'interrogation périodique de la propriétégetctag
entraîne une limitation.
- Les programmes clients utilisent la requête
- Utiliser le jeton de synchronisation
- Les programmes clients utilisent la requête
PROPFIND
sync-token
sur le carnet d'adresses pour obtenir lesync-token
représentant son état actuel. Les applications clientes doivent stocker cette valeur et émettre des requêtessync-collection
REPORT
périodiques pour déterminer les modifications apportées depuis le derniersync-token
. Les jetons émis sont valides pendant 29 jours, et la réponseREPORT
contiendra un nouveausync-token
.
- Les programmes clients utilisent la requête
- Utilisation des ETag
- Les applications clientes émettent une requête
PROPFIND
getetag
sur la ressource de carnet d'adresses (avec un en-têteDEPTH
égal àDEPTH_1
). En conservant la valeurETag
de chaque contact, un programme client peut demander la valeur des contacts dont leETag
a été modifié.
- Les applications clientes émettent une requête
- Récupérer des contacts
- Les applications clientes récupèrent les contacts en émettant une requête
addressbook-multiget
REPORT
. À partir d'une liste d'URI de contact, le rapport renvoie tous les contacts demandés sous forme de valeurs VCard 3.0. Chaque entrée inclut unETag
pour le contact.
- Les applications clientes récupèrent les contacts en émettant une requête
- Insérer un contact
- Les applications clientes émettent une requête
POST
avec le nouveau contact au format VCard 3.0. La réponse contiendra l'ID du nouveau contact.
- Les applications clientes émettent une requête
- Mettre à jour un contact
- Les applications clientes émettent une requête
PUT
avec le contact mis à jour au format VCard 3.0. Le contact est mis à jour s'il existe déjà dans le carnet d'adresses. - Les applications clientes doivent inclure un en-tête
If-Match
avec l'élémentETag
actuellement connu du contact. Le serveur rejette ensuite la requêtePUT
(avecHTTP 412
) si l'adresseETag
actuelle sur le serveur est différente de l'adresseETag
envoyée par le programme client. Cela permet une sérialisation optimiste des mises à jour.
- Les applications clientes émettent une requête
- Supprimer un contact
- Les applications clientes suppriment un contact en envoyant une requête
DELETE
sur l'URI de contact.
- Les applications clientes suppriment un contact en envoyant une requête