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

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

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

Характеристики

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

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

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

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

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

  • Использование CTag
    • Клиентские программы используют getctag PROPFIND к ресурсу адресной книги, чтобы определить, изменился ли какой-либо контакт на сервере и, следовательно, требуется ли синхронизация. Значение этого свойства гарантированно изменится при изменении любого контакта. Клиентские приложения должны хранить это значение и использовать его только при начальной синхронизации и в качестве запасного варианта, когда sync-token становится недействительным. Периодический опрос свойства getctag приведет к регулированию.
  • Использование токена синхронизации
    • Клиентские программы используют запрос PROPFIND sync-token синхронизации в адресной книге для получения 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 контакта.