CalDAV API 开发者指南

CalDAV 是 WebDAV 的扩展，为客户端访问远程服务器上的日历信息提供了标准。

Google 提供了一个 CalDAV 接口，您可以使用该接口通过 CalDAV 协议查看和管理日历。

CalDAV API 的配额限制与 Calendar API 相同。如需了解详情，请参阅使用量 限制。

规格

对于每个相关规范，Google 的 CalDAV 支持如下：

  • rfc4918：用于 Web 分布式创作和版本控制 (WebDAV) 的 HTTP 扩展

    • 支持 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：iCalendar

    • CalDAV 接口中公开的数据按照 iCalendar 规范进行格式化。
    • 不支持 VTODO 或 VJOURNAL 数据。
    • 不支持 Apple iCal 扩展，以允许用户设置网址属性。

  • rfc6578：WebDAV 的集合同步

    • 客户端应用必须在初始同步后切换到此操作模式。

  • rfc6638：CalDAV 的安排扩展

    • 支持一个简单的“收件箱”，该收件箱始终为空。
    • 您收到的邀请会自动发送到您的“活动”集合，而不是放入您的“收件箱”。
    • 不支持 free-busy 查找。

  • caldav-ctag-02：CalDAV 中的日历集合实体标记 (CTag)

    • 日历 ctag 类似于资源 etag；当日历中的任何内容发生更改时，它也会随之更改。这样，客户端应用就可以快速确定它不需要同步任何已更改的活动。

  • calendar-proxy：CalDAV 中的日历用户代理功能

    • 为了提高日历同步性能，包含 calendar-proxy-read-for 或 calendar-proxy-write-for 属性的请求将因 iOS 设备不支持委托而失败，并显示 iOS UserAgent。

虽然我们的 CalDAV 实现未涵盖所有规范，但它适用于许多客户端（包括 Apple 日历）。

创建客户端 ID

如需使用 CalDAV API，您需要拥有 Google 账号。

在向 CalDAV API 发送请求之前，您必须通过创建项目在 Google Cloud 控制台 中注册您的 客户端。

转到 Google API 控制台。点击创建项目， 输入名称，然后点击创建。

接下来，您需要激活 CalDAV API 。

如需为您的项目启用 API，请执行以下操作：

  1. 在 Google API 控制台中打开 API 库。如果系统提示，请选择一个项目或创建一个新项目。API 库中列出了所有可用的 API（按产品系列和热门程度分组）。
  2. 如果列表中没有显示您要启用的 API，请使用搜索功能查找该 API。
  3. 选择您要启用的 API，然后点击启用 按钮。
  4. 如果系统提示，请启用结算功能。
  5. 如果系统提示，请接受该 API 的服务条款。

如需执行 CalDAV API 请求，您需要 Client ID 和客户端密钥 。

如需查找项目的客户端 ID 和客户端密钥，请执行以下操作：

  1. 选择现有 OAuth 2.0 凭据，或打开“凭据”页面。
  2. 如果您尚未创建项目的 OAuth 2.0 凭据，请点击 创建凭据 > OAuth 客户端 ID ，然后 提供创建凭据所需的信息。
  3. 在 OAuth 2.0 客户端 ID 部分中查找 Client ID 。 如需了解详情，请点击客户端 ID。

连接到 Google 的 CalDAV 服务器

如需使用 CalDAV 接口，客户端程序最初会从两个起始点之一连接到日历服务器。无论哪种情况，连接都必须通过 HTTPS 进行，并且必须使用 OAuth 2.0 身份验证方案。除非请求通过 HTTPS 传入并使用 Google 账号的 OAuth 2.0 身份验证，否则 CalDAV 服务器会拒绝验证请求。尝试通过 HTTP 连接或使用基本身份验证会导致 HTTP 401 Unauthorized 状态代码。

如果客户端程序（例如 Apple 的日历应用）需要主集合作为起始点，则连接的 URI 为：

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

将 CALENDAR_ID 替换为要 访问的日历的 ID。

如需通过 Web 界面查找日历 ID，请在日历名称旁边的下拉菜单中选择 ** Calendar Settings** 。日历 ID 会显示在名为 Calendar Address 的部分中。用户主日历的日历 ID 与该用户的电子邮件地址相同。

如果客户端程序（例如 Mozilla Thunderbird）需要日历 集合作为出发地，请使用以下 URI：

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