Gérer les contacts avec le protocole CardDAV

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:

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.

  1. Compte principal
    • https://www.googleapis.com/carddav/v1/principals/userEmail
  2. Home set
    • https://www.googleapis.com/carddav/v1/principals/userEmail/lists
  3. Carnet d'adresses
    • https://www.googleapis.com/carddav/v1/principals/userEmail/lists/default
  4. Contact
    • https://www.googleapis.com/carddav/v1/principals/userEmail/lists/default/contactId

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'une sync-token n'est pas valide. L'interrogation périodique de la propriété getctag entraîne une limitation.
  • Utiliser le jeton de synchronisation
    • Les programmes clients utilisent la requête PROPFIND sync-token sur le carnet d'adresses pour obtenir le sync-token représentant son état actuel. Les applications clientes doivent stocker cette valeur et émettre des requêtes sync-collection REPORT périodiques pour déterminer les modifications apportées depuis le dernier sync-token. Les jetons émis sont valides pendant 29 jours, et la réponse REPORT contiendra un nouveau sync-token.
  • Utilisation des ETag
    • Les applications clientes émettent une requête PROPFIND getetag sur la ressource de carnet d'adresses (avec un en-tête DEPTH égal à DEPTH_1). En conservant la valeur ETag de chaque contact, un programme client peut demander la valeur des contacts dont le ETag a été modifié.
  • 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 un ETag pour le contact.
  • 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.
  • 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ément ETag actuellement connu du contact. Le serveur rejette ensuite la requête PUT (avec HTTP 412) si l'adresse ETag actuelle sur le serveur est différente de l'adresse ETag envoyée par le programme client. Cela permet une sérialisation optimiste des mises à jour.
  • Supprimer un contact
    • Les applications clientes suppriment un contact en envoyant une requête DELETE sur l'URI de contact.