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

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

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

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

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

  • 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 . Реализованы все отчеты, кроме free-busy-query.
    • Не поддерживает метод HTTP MKCALENDAR .
    • Не поддерживает действие AUDIO .
  • rfc5545: iКалендарь
    • Данные, отображаемые в интерфейсе 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 не удастся.

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

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

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

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

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

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

Следующим шагом будет активация CalDAV API .

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

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

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

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

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

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

Если клиентская программа (такая как Apple iCal ) требует основной коллекции в качестве отправной точки, 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.