Управляйте контактами с помощью протокола CardDAV

Вы можете просматривать свои контакты и управлять ими с помощью протокола Google CardDAV.

Контакты хранятся в учетной записи Google пользователя; большинство сервисов Google имеют доступ к списку контактов. Ваше клиентское приложение может использовать API CardDAV для создания новых контактов, редактирования или удаления существующих контактов, а также запроса контактов, соответствующих определенным критериям.

Технические характеристики

Полная спецификация не реализована, но многие клиенты, такие как Apple iOS™ Contacts и macOS, должны корректно взаимодействовать.

Для каждой соответствующей спецификации поддержка CardDAV от Google выглядит следующим образом:

Google CardDAV требует OAuth 2.0.

Интерфейс Google CardDAV требует OAuth 2.0. Обратитесь к связанной документации ниже для получения информации об использовании OAuth 2.0 для доступа к API Google:

Подключение к серверу Google CardDAV

Протокол CardDAV позволяет обнаруживать URI адресной книги и контактных ресурсов. Вы не должны жестко запрограммировать какие-либо URI, поскольку они могут измениться в любое время.

Клиентские приложения должны использовать HTTPS, а для учетной записи Google пользователя должна быть предусмотрена аутентификация OAuth 2.0 . Сервер CardDAV не будет аутентифицировать запрос, если он не поступает по HTTPS с аутентификацией OAuth 2.0 учетной записи Google и ваше приложение не зарегистрировано в DevConsole. Любая попытка подключения по HTTP с базовой аутентификацией или с использованием адреса электронной почты/пароля, не совпадающего с учетной записью Google, приводит к появлению кода ответа HTTP 401 Unauthorized .

Чтобы использовать CardDAV, ваша клиентская программа должна сначала подключиться к каноническому пути обнаружения, выполнив HTTP PROPFIND для:

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

После перенаправления ( HTTP 301 ) на ресурс адресной книги ваша клиентская программа может выполнить для него PROPFIND , чтобы обнаружить свойства DAV:current-user-principal , DAV:principal-URL и addressbook-home-set . Затем ваша клиентская программа может обнаружить основную адресную книгу, выполнив PROPFIND для addressbook-home-set и выполнив поиск ресурсов addressbook и collection . Полное описание этого процесса выходит за рамки данного документа. Дополнительную информацию см. в rfc6352 .

Путь перенаправления, возвращаемый в ответе HTTP 301 через PROPFIND по известному URI, не должен постоянно кэшироваться (согласно rfc6764 ). Устройства должны периодически повторять попытку обнаружения известного URI, чтобы проверить, актуален ли кэшированный путь, и выполнять повторную синхронизацию, если путь когда-либо изменится. Google рекомендует каждые 2–4 недели.

Ресурсы

CardDAV использует концепции REST. Клиентские приложения работают с ресурсами, которые обозначены их URI. Здесь указана текущая структура URI, чтобы помочь разработчикам понять концепции, изложенные в следующем разделе. Структура может меняться и не должна быть жестко запрограммирована. Скорее, ресурсы должны быть обнаружены в соответствии с RFC.

  1. Главный
    • userEmail
  2. Домашний набор
    • https://www.googleapis.com/carddav/v1/principals/userEmail / userEmail
  3. Адресная книга
    • https://www.googleapis.com/carddav/v1/principals/userEmail userEmail lists/default
  4. Контакт
    • https://www.googleapis.com/carddav/v1/principals/userEmail userEmail lists/default/ contactId

Синхронизация контактов

Ниже приводится общее описание поддерживаемых операций. Подробности разработчикам следует искать в соответствующем RFC. Запросы и ответы в основном кодируются в XML. Вот основные операции, используемые клиентскими приложениями для синхронизации:

  • Использование CTag
    • Клиентские программы используют запрос getctag PROPFIND к ресурсу адресной книги, чтобы определить, изменился ли какой-либо контакт на сервере и, следовательно, необходима ли синхронизация. Значение этого свойства гарантированно изменится при изменении любого контакта. Клиентские приложения должны хранить это значение и использовать его только при начальной синхронизации и в качестве резервного варианта, когда sync-token становится недействительным. Периодический опрос свойства getctag приведет к регулированию.
  • Использование токена синхронизации
    • Клиентские программы используют запрос sync-token PROPFIND в адресной книге для получения sync-token представляющего ее текущее состояние. Клиентские приложения должны хранить это значение и периодически выдавать запросы REPORT sync-collection чтобы определить изменения с момента последнего выдачи sync-token . Выданные токены действительны в течение 29 дней, а ответ REPORT будет содержать новый sync-token .
  • Использование ETag
    • Клиентские приложения выдают запрос getetag PROPFIND к ресурсу адресной книги (с заголовком DEPTH , равным DEPTH_1 ). Сохраняя значение ETag каждого контакта, клиентская программа может запрашивать значение контактов, у которых был изменен ETag .
  • Получение контактов
    • Клиентские приложения извлекают контакты, отправляя запрос REPORT addressbook-multiget . Учитывая список URI контактов, отчет возвращает все запрошенные контакты в виде значений VCard 3.0. Каждая запись включает ETag для контакта.
  • Вставка контакта
    • Клиентские приложения отправляют запрос POST с новым контактом в формате VCard 3.0. Ответ будет содержать идентификатор нового контакта.
  • Обновление контакта
    • Клиентские приложения выдают запрос PUT с обновленным контактом в формате VCard 3.0. Контакт обновляется, если контакт уже существует в адресной книге.
    • Клиентские приложения должны включать заголовок If-Match с известным на данный момент ETag контакта. Затем сервер отклонит запрос PUT (с HTTP 412 ), если текущий ETag на сервере отличается от ETag , отправленного клиентской программой. Это обеспечивает оптимистичную сериализацию обновлений.
  • Удаление контакта
    • Клиентские приложения удаляют контакт, отправляя запрос DELETE на URI контакта.