CalDAV API 开发者指南

CalDAV 是 WebDAV 的扩展，可让客户端访问远程服务器上的日历信息。

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

规范

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

• rfc4918：适用于 Web 分布式编写和版本控制的 Web 扩展 (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® 扩展程序，以允许设置可由用户设置的网址属性。
• rfc6578：WebDAV 的集合同步
  • 客户端应用必须在初始同步后切换到此操作模式。
• rfc6638：安排扩展程序到 CalDAV
  • 支持琐碎的“收件箱”，其始终为空。
  • 您收到的邀请会自动发送到“活动”集合，而不是放入“收件箱”中。
  • 不支持空闲/忙碌查找。
• caldav-ctag-02：CalDAV 中的日历集合实体标记 (CTag)
  • 日历 ctag 类似于资源 etag；当日历中的任何内容发生更改时，日历也会随之更改。这样，客户端应用就可以快速确定它不需要同步任何已更改的事件。
• calendar-proxy：CalDAV 中的 Google 日历用户代理功能
  • 为了提升从不支持委托的 iOS 设备同步日历的性能，将 calendar-proxy-read-for 或 calendar-proxy-write-for 属性与 iOS UserAgent 结合使用将会失败。

我们尚未提供所有相关规范的完整实现。但是，对于许多客户端（例如 Apple iCal），CalDAV 协议应该可以正确进行互操作。

注意：为保证帐号安全并防止滥用行为，Google 可能会在通过 CalDAV 访问数据的客户端应用上设置 Cookie。

创建客户端 ID

如需使用 CalDAV API，您需要拥有一个 Google 帐号。如果您已经拥有可以使用的帐号，就一切就绪了。

您必须先创建项目，在 Google API 控制台中注册您的客户端，然后才能向 CalDAV API 发送请求。

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

下一步是激活 CalDAV API。

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

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

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

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

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

连接到 Google 的 CalDAV 服务器

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

如果客户端程序（例如 Apple iCal）要求以主集合作为起点，则要连接的 URI 为：

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

其中，calid 应替换为要访问的日历的“日历 ID”。您可以通过 Google 日历网页界面找到该日历，具体操作方法如下：在日历名称旁边的下拉菜单中，选择日历设置。在随后出现的页面上，日历 ID 会显示在标记为日历地址的部分。用户主日历的日历 ID 与用户的电子邮件地址相同。

如果客户端程序（例如 Mozilla Sunbird）需要收集日历作为起点，则要连接的 URI 为：

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

旧端点 https://www.google.com/calendar/dav 已被弃用，不再受支持；使用时请自行承担风险。我们建议您改用上述新的端点格式。

iCal 是 Apple Inc. 的商标