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 effectuer des recherches sur des contacts ; qui correspondent à des critères spécifiques.

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, le service d'assistance CardDAV de Google est assuré comme suit:

rfc2518: Extensions HTTP pour la création distribuée (WebDAV) <ph type="x-smartling-placeholder">
- 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 <ph type="x-smartling-placeholder">
- Permet de créer des contacts sans spécifier d'ID.
rfc6352: CardDAV: extensions vCard pour la création distribuée sur Web et Gestion des versions (WebDAV) <ph type="x-smartling-placeholder">
- 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: Synchronisation des collections pour WebDAV <ph type="x-smartling-placeholder">
- 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 <ph type="x-smartling-placeholder">
- Prend en charge l'authentification des programmes clients CardDAV à l'aide du protocole HTTP OAuth 2.0 Authentification. Google ne propose aucune autre méthode d'authentification. Pour la sécurité des données de contact, les connexions CardDAV doivent être utilisées HTTPS :
rfc6764: Localisation de services pour les extensions d'agenda sur WebDAV (CalDAV) et des extensions vCard vers WebDAV (CardDAV) <ph type="x-smartling-placeholder">
- L'amorçage des URL CardDAV doit s'effectuer conformément à la section 6 de la rfc6764.
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é. Le programme client peut ainsi 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. Voir: rfc6350: VCard 3.0.

La norme CardDAV de Google requiert OAuth 2.0

L'interface CardDAV de Google nécessite OAuth 2.0. Reportez-vous aux liens ci-dessous pour en savoir plus sur l'utilisation d'OAuth 2.0 pour accéder aux API Google:

Connexion au serveur CardDAV de Google

Le protocole CardDAV permet de découvrir le carnet d'adresses et les ressources de contact. URI. Vous ne devez pas coder en dur les URI, car ils peuvent être modifiés à 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 HTTP avec une authentification de base ou avec une adresse e-mail/mot de passe qui ne correspond pas à un compte Google génère Code de réponse 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 de carnet d'adresses, votre programme client vous pouvez ensuite effectuer une opération PROPFIND sur celui-ci pour découvrir DAV:current-user-principal, DAV:principal-URL et addressbook-home-set propriétés. 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. Voir rfc6352 pour en savoir plus.

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 relancer la connexion la découverte d'URI régulièrement pour vérifier si le chemin mis en cache est toujours à jour et resynchroniser si le chemin d'accès change. Google recommande un taux toutes les deux à quatre semaines.

Ressources

CardDAV utilise les concepts REST. Les applications clientes agissent sur des ressources désignés 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.

Compte principal <ph type="x-smartling-placeholder">
- https://www.googleapis.com/carddav/v1/principals/userEmail
Home Set <ph type="x-smartling-placeholder">
- https://www.googleapis.com/carddav/v1/principals/userEmail/lists
Carnet d'adresses <ph type="x-smartling-placeholder">
- https://www.googleapis.com/carddav/v1/principals/userEmail/lists/default
Contact <ph type="x-smartling-placeholder">
- 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. Développeurs consultez le document RFC approprié. Les requêtes et les réponses principalement encodée en XML. Voici les principales opérations utilisées par le client applications de synchronisation:

Utiliser le CTag <ph type="x-smartling-placeholder">
- 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 s'assure que le contact change. Applications clientes doit stocker cette valeur et l'utiliser uniquement lors de la synchronisation initiale et comme création de remplacement lorsqu'un sync-token n'est plus valide. Interroger régulièrement les la propriété getctag entraîne une limitation.
Utiliser un jeton de synchronisation <ph type="x-smartling-placeholder">
- Les programmes clients utilisent la requête PROPFIND sync-token sur l'adresse Réservez pour obtenir le sync-token représentant son état actuel. Client les applications doivent stocker cette valeur et émettre régulièrement des sync-collection Requêtes REPORT pour déterminer les modifications depuis la dernière émission sync-token Les jetons émis sont valides pendant 29 jours, et le REPORT contiendra un nouveau sync-token.
Utiliser des ETags <ph type="x-smartling-placeholder">
- 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érer des contacts <ph type="x-smartling-placeholder">
- Les applications clientes récupèrent les contacts en émettant une addressbook-multiget requête 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 l'entrée inclut un ETag pour le contact.
Insérer un contact <ph type="x-smartling-placeholder">
- Les applications clientes envoient une requête POST au nouveau contact dans VCard. 3.0. La réponse contiendra l'ID du nouveau contact.
Modifier un contact <ph type="x-smartling-placeholder">
- 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 refusera ensuite PUT (avec HTTP 412) si la valeur ETag actuelle sur le serveur est différent du ETag envoyé par le programme client. Cela permet une sérialisation optimiste des mises à jour.
Supprimer un contact <ph type="x-smartling-placeholder">
- Les applications clientes suppriment un contact en émettant une requête DELETE. par l'URI de contact.