Руководство разработчика 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 с iOS UserAgent завершится ошибкой.

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

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

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

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

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

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

Следующий шаг — активация 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.