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

CalDAV is an extension of WebDAV that provides a standard for clients to access calendar information on a remote server.

Google provides a CalDAV interface that you can use to view and manage calendars using the CalDAV protocol.

The CalDAV API has the same quota limits as the Calendar API. For more information, see Usage limits .

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

For each of the relevant specifications, Google's CalDAV support is as follows:

  • rfc4918: HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV)

    • Supports the HTTP methods GET , PUT , HEAD , DELETE , POST , OPTIONS , PROPFIND , and PROPPATCH .
    • Doesn't support the HTTP methods LOCK , UNLOCK , COPY , MOVE , MKCOL , or the If* header (except for If-Match ).
    • Не поддерживает произвольные (определяемые пользователем) свойства WebDAV.
    • Не поддерживает WebDAV Access Control (rfc3744).

  • rfc4791: Calendaring Extensions to WebDAV (CalDAV)

    • Supports the HTTP method REPORT . All reports except free-busy-query are implemented.
    • Не поддерживает HTTP-метод MKCALENDAR .
    • Не поддерживает действие AUDIO .

  • rfc5545: iCalendar

    • Data exposed in the CalDAV interface is formatted according to the iCalendar specification.
    • Doesn't support VTODO or VJOURNAL data.
    • Doesn't support the Apple iCal extension to allow user-settable URL properties.

  • rfc6578: Collection Synchronization for WebDAV

    • Client applications must switch to this mode of operation after the initial sync.

  • rfc6638: Scheduling Extensions to CalDAV

    • Supports a trivial "inbox," which is always empty.
    • Invitations you receive are automatically delivered into your "events" collection rather than being placed into your "inbox."
    • Doesn't support free-busy lookup.

  • caldav-ctag-02: Calendar Collection Entity Tag (CTag) in CalDAV

    • ctag похожа на метку ресурса etag ; она изменяется при изменении любых событий в календаре. Это позволяет клиентскому приложению быстро определить, что синхронизация измененных событий не требуется.

  • calendar-proxy: Calendar User Proxy Functionality in CalDAV

    • Для повышения производительности синхронизации календаря запросы, содержащие свойства calendar-proxy-read-for или calendar-proxy-write-for будут завершаться с ошибкой, связанной с iOS UserAgent, поскольку устройства iOS не поддерживают делегирование.

Although our CalDAV implementation doesn't cover every specification, it works correctly for many clients, including Apple Calendar.

Create your client ID

Для использования API CalDAV вам необходима учетная запись Google .

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

Go to the Google API Console . Click Create project , enter a name, and click Create .

You next need to activate the CalDAV API .

To enable an API for your project, do the following:

  1. Откройте библиотеку API в консоли Google API. При появлении запроса выберите проект или создайте новый. В библиотеке API отображаются все доступные API, сгруппированные по семействам продуктов и популярности.
  2. If the API you want to enable isn't visible in the list, use search to find it.
  3. Выберите API, который хотите включить, затем нажмите кнопку «Включить» .
  4. If prompted, enable billing.
  5. If prompted, accept the API's Terms of Service.

Для выполнения запросов к API CalDAV вам необходимы идентификатор клиента (Client ID ) и секретный ключ клиента (Client Secret) .

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

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

Connect to Google's CalDAV server

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

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

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

Замените CALENDAR_ID на идентификатор календаря, к которому вы хотите получить доступ.

Чтобы найти идентификатор календаря через веб-интерфейс, выберите **Настройки календаря** в раскрывающемся меню рядом с названием календаря. Идентификатор календаря отображается в разделе « Адрес календаря» . Идентификатор основного календаря пользователя совпадает с адресом электронной почты этого пользователя.

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

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