Руководство разработчика API CalDAV

CalDAV — это расширение WebDAV, которое предоставляет клиентам стандарт доступа к информации календаря на удаленном сервере.

Google предоставляет интерфейс CalDAV, который можно использовать для просмотра календарей и управления ими с помощью протокола CalDAV.

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

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

  • rfc4918: HTTP-расширения для распределенной веб-авторизации и управления версиями (WebDAV)
    • Поддерживает методы HTTP GET , PUT , HEAD , DELETE , POST , OPTIONS , PROPFIND и PROPPATCH .
    • Не поддерживает методы HTTP LOCK , UNLOCK , COPY , MOVE или MKCOL , а также заголовок If* (за исключением If-Match ).
    • Не поддерживает произвольные (определяемые пользователем) свойства WebDAV.
    • Не поддерживает контроль доступа WebDAV (rfc3744).
  • rfc4791: Расширения календаря для WebDAV (CalDAV)
    • Поддерживает HTTP-метод REPORT . Реализованы все отчеты, кроме запроса «свободно-занято».
    • Не поддерживает метод HTTP MKCALENDAR .
    • Не поддерживает действие AUDIO .
  • rfc5545: iCalendar
    • Данные, представленные в интерфейсе CalDAV, форматируются в соответствии со спецификацией iCalendar.
    • В настоящее время не поддерживает данные VTODO или VJOURNAL .
    • Не поддерживает расширение Apple iCal®, позволяющее настраивать свойства URL-адреса.
  • rfc6578: Синхронизация коллекции для WebDAV
    • Клиентские приложения должны перейти в этот режим работы после первоначальной синхронизации.
  • rfc6638: Планирование расширений для CalDAV
    • Поддерживает тривиальный «входящие», который всегда пуст.
    • Приглашения, которые вы получаете, автоматически доставляются в вашу коллекцию «события», а не в папку «Входящие».
    • Не поддерживает поиск свободного/занятого времени.
  • Caldav-ctag-02: Тег объекта коллекции календарей (CTag) в CalDAV
    • ctag календаря похож на etag ресурса; он меняется, когда что-то в календаре изменилось. Это позволяет клиентскому приложению быстро определить, что ему не требуется синхронизировать какие-либо измененные события.
  • Calendar-proxy: Функциональность пользовательского прокси-сервера календаря в CalDAV
    • Чтобы повысить производительность синхронизации календаря с устройств iOS, которые не поддерживают делегирование, использование свойств calendar-proxy-read-for или calendar-proxy-write-for с UserAgent iOS не удастся.

Мы еще не обеспечили полную реализацию всех соответствующих спецификаций. Однако для многих клиентов, таких как приложение Apple Calendar, протокол CalDAV должен корректно взаимодействовать.

Примечание. В целях безопасности учетной записи и предотвращения злоупотреблений Google может устанавливать файлы cookie в клиентских приложениях, которые получают доступ к данным через CalDAV.

Создание идентификатора клиента

Чтобы использовать CalDAV API, вам необходимо иметь учетную запись Google . Если у вас уже есть учетная запись, которую вы можете использовать, значит, все готово.

Прежде чем вы сможете отправлять запросы к CalDAV API, вы должны зарегистрировать свой клиент в консоли Google API, создав проект.

Перейдите в консоль Google API . Нажмите «Создать проект» , введите имя и нажмите «Создать» .

Следующий шаг — активация CalDAV API .

Чтобы включить API для вашего проекта, сделайте следующее:

  1. Откройте библиотеку API в консоли Google API. При появлении запроса выберите проект или создайте новый. В библиотеке API перечислены все доступные API, сгруппированные по семействам продуктов и популярности.
  2. Если API, который вы хотите включить, не отображается в списке, воспользуйтесь поиском, чтобы найти его.
  3. Выберите API, который вы хотите включить, затем нажмите кнопку «Включить» .
  4. Если будет предложено, включите выставление счетов.
  5. Если будет предложено, примите Условия обслуживания API.
Для выполнения запросов CalDAV API вам понадобится Client ID и Client Secret .

Чтобы узнать идентификатор и секрет клиента вашего проекта, выполните следующие действия:

  1. Выберите существующие учетные данные OAuth 2.0 или откройте страницу «Учетные данные» .
  2. Если вы еще этого не сделали, создайте учетные данные OAuth 2.0 для своего проекта, щелкнув Создать учетные данные > Идентификатор клиента OAuth и предоставив информацию, необходимую для создания учетных данных.
  3. Найдите идентификатор клиента в разделе «Идентификаторы клиентов OAuth 2.0» . Для получения подробной информации щелкните идентификатор клиента.

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

Чтобы использовать интерфейс CalDAV, клиентская программа первоначально подключается к серверу календаря в одной из двух начальных точек. В любом случае соединение должно осуществляться через HTTPS и использовать схему аутентификации OAuth 2.0 . Сервер CalDAV откажется аутентифицировать запрос, если он не поступит через HTTPS с аутентификацией OAuth 2.0 учетной записи Google. Попытка подключения через HTTP или использование базовой аутентификации приводит к коду состояния HTTP 401 Unauthorized .

Если клиентская программа (например, приложение «Календарь» Apple) требует в качестве отправной точки основную коллекцию, URI для подключения будет следующим:

https://apidata.googleusercontent.com/caldav/v2/calid/user

Где calid следует заменить на «идентификатор календаря» календаря, к которому осуществляется доступ. Это можно найти через веб-интерфейс Календаря Google следующим образом: в раскрывающемся меню рядом с названием календаря выберите «Настройки календаря» . На открывшейся странице идентификатор календаря отображается в разделе «Адрес календаря» . Идентификатор календаря основного календаря пользователя совпадает с адресом электронной почты этого пользователя.

Если клиентская программа (например, Mozilla Sunbird ) требует в качестве отправной точки коллекцию календарей, URI для подключения будет следующим:

https://apidata.googleusercontent.com/caldav/v2/calid/events

Старая конечная точка https://www.google.com/calendar/dav устарела и больше не поддерживается; используйте его на свой страх и риск. Мы рекомендуем вам перейти на новый формат конечной точки, описанный выше.

iCal® является торговой маркой Apple Inc.