Руководство разработчика 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 Access Control (rfc3744).
  • rfc4791: Расширения для работы с календарем в WebDAV (CalDAV)
    • Поддерживается HTTP-метод REPORT . Реализованы все типы отчетов, кроме запроса на определение занятости (free-busy-query).
    • Не поддерживает 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, необходимо зарегистрировать клиент в консоли Google API , создав проект.

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

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

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

  1. Откройте библиотеку API в консоли Google API. При появлении запроса выберите проект или создайте новый. В библиотеке 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» . Для получения подробной информации щелкните по идентификатору клиента.

Подключение к серверу 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/valid/user

В поле valid следует заменить «идентификатором календаря» (calendar ID), к которому необходимо получить доступ. Его можно найти в веб-интерфейсе Google Календаря следующим образом: в выпадающем меню рядом с названием календаря выберите «Настройки календаря» . На открывшейся странице идентификатор календаря отображается в разделе « Адрес календаря» . Идентификатор основного календаря пользователя совпадает с адресом электронной почты этого пользователя.

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

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

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

iCal® — товарный знак компании Apple Inc.