Cette page a été traduite par l'API Cloud Translation.

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 l'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 interroger des contacts correspondant à des critères particuliers.

Spécifications

La spécification complète n'est pas mise en œuvre, mais de nombreux clients tels que Contacts Apple iOSTM et macOS devraient interagir correctement.

Pour chaque spécification pertinente, la prise en charge de CardDAV par Google est la suivante :

rfc2518: Extensions HTTP pour la création distribuée (WebDAV)
- Accepte les méthodes HTTP GET, PUT, DELETE, OPTIONS et PROPFIND
- N'accepte pas les méthodes HTTP LOCK, UNLOCK, COPY, MOVE ou MKCOL
- N'accepte pas les propriétés WebDAV arbitraires (définies par l'utilisateur).
- N'est pas compatible avec le contrôle d'accès WebDAV (rfc3744).
rfc5995: Utiliser la méthode POST pour ajouter des membres aux collections WebDAV
- Permet de créer des contacts sans spécifier d'ID.
rfc6352 : CardDAV : extensions vCard pour l'écriture 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 mise en œuvre.
- Permet de fournir une collection de comptes principaux et de contacts.
rfc6578 : Collection Synchronization for WebDAV
- Les applications clientes doivent passer à ce mode de fonctionnement une fois que le synchronisation initiale.
rfc6749: The OAuth 2.0 Authorization Framework 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'est compatible avec aucune autre méthode d'authentification. Pour assurer la sécurité des données de contact, nous exigeons que les connexions CardDAV utilisent le protocole HTTPS.
rfc6764 : Services de localisation pour les extensions de calendrier à WebDAV (CalDAV) et les extensions de vCard à WebDAV (CardDAV)
- Le démarrage des URL CardDAV doit se faire conformément à la section 6 de la RFC 6764.
Compatible caldav-ctag-02: balise d'entité de collection d'agendas (CTag) dans CalDAV, qui est partagé entre les spécifications CardDAV et CalDAV. Les contacts ctag est semblable à une ressource ETag. il change quand un élément du contact le carnet d'adresses a été modifié. Cela permet au programme client de déterminer rapidement qu'il n'a pas besoin de synchroniser les contacts modifiés.
Google utilise le format d'encodage de contacts VCard 3.0. Voir: rfc6350: VCard 3.0.

La norme CardDAV de Google requiert OAuth 2.0

L'interface CardDAV de Google requiert OAuth 2.0. Reportez-vous aux liens ci-dessous pour plus d'informations 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étecter les URI des ressources de carnet d'adresses et de contacts. Vous ne devez pas coder en dur d'URI, car ils peuvent changer à tout moment.

Les applications clientes doivent utiliser HTTPS, et l'authentification OAuth 2.0 doit être fournies au compte Google de l'utilisateur. Le serveur CardDAV ne authentifier une requête, sauf si elle arrive par HTTPS avec OAuth 2.0 d'authentification d'un compte Google et votre application est enregistrée sur DevConsole. Toute tentative de connexion via HTTP avec une authentification de base ou avec un e-mail/un mot de passe qui ne correspond pas à un compte Google entraîne un code de réponse HTTP 401 Unauthorized.

Pour utiliser CardDAV, votre programme client doit d'abord se connecter à l'URL canonique de découverte en effectuant une requête HTTP PROPFIND sur:

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

Une fois redirigé (HTTP 301) vers une ressource d'annuaire, votre programme client peut effectuer une PROPFIND dessus pour découvrir les propriétés DAV:current-user-principal, DAV:principal-URL et addressbook-home-set. Votre programme client peut alors découvrir le carnet d'adresses principal en en effectuant une PROPFIND sur addressbook-home-set et en recherchant Ressources addressbook et collection. Une description complète de ce processus dépasse le cadre de ce document. Pour en savoir plus, consultez la norme rfc6352.

Le chemin de redirection renvoyé dans la réponse HTTP 301 via une PROPFIND sur l'URI connu ne doit pas être mis en cache de façon permanente (conformément rfc6764). Les appareils doivent réessayer régulièrement la découverte des URI connus pour vérifier si le chemin mis en cache est toujours à jour et se synchroniser 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 de la section suivante. La structure peut et ne doivent pas être codés en dur. Les ressources doivent plutôt être découvertes conformément au document RFC.

Principal
- https://www.googleapis.com/carddav/v1/principals/userEmail
Home Set
- https://www.googleapis.com/carddav/v1/principals/userEmail/lists
Carnet d'adresses
- https://www.googleapis.com/carddav/v1/principals/userEmail/lists/default
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 acceptées. Développeurs consultez le document RFC approprié. Les requêtes et les réponses sont principalement encodées en XML. Voici les principales opérations utilisées par les applications clientes pour la synchronisation :

Utiliser le CTag
- Les programmes clients utilisent la requête PROPFIND getctag dans le carnet d'adresses. ressource pour déterminer si un contact a été modifié sur le serveur et et donc si une synchronisation est nécessaire. Valeur de cette propriété le changement est garanti si des contacts changent. Les applications clientes doivent stocker cette valeur et ne l'utiliser que lors de la synchronisation initiale et en remplacement lorsqu'un sync-token est invalidé. Interroger régulièrement les la propriété getctag entraîne une limitation.
Utiliser un jeton de synchronisation
- Les programmes clients utilisent la requête PROPFIND sync-token sur l'annuaire 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 depuis la dernière sync-token émise. Les jetons émis sont valables pendant 29 jours, et la réponse REPORT contient un nouveau sync-token.
Utiliser des ETags
- Les applications clientes envoient une requête getetag PROPFIND au niveau de l'adresse Ressource du livre (avec l'en-tête DEPTH égal à DEPTH_1). En maintenant la valeur ETag de chaque contact, un programme client peut demander la valeur des contacts dont ETag a été modifié.
Récupération des contacts
- Les applications clientes récupèrent les contacts en envoyant une requête REPORT addressbook-multiget. À 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 envoient 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 envoient une requête PUT au contact mis à jour dans 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 le paramètre ETag actuellement connu du contact. Le serveur rejette ensuite la requête PUT (avec HTTP 412) si le ETag actuel sur le serveur est différent de celui envoyé 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 à l'URI du contact.