CalDAV API 开发者指南

CalDAV 是 WebDAV 的扩展，它提供了一种供客户端访问 远程服务器上的日历信息

Google 提供了 CalDAV 界面，可用于查看和管理日历 使用 CalDAV 协议

规格

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

• rfc4918：用于网络分布式创作和版本控制的 HTTP 扩展 (WebDAV)
  • 支持 HTTP 方法 GET、PUT、HEAD、DELETE、POST OPTIONS、PROPFIND 和 PROPPATCH。
  • 不支持 LOCK、UNLOCK、COPY、MOVE 或 MKCOL 或 If* 标头（If-Match 除外）。
  • 不支持任意（用户定义的）WebDAV 属性。
  • 不支持 WebDAV 访问控制 (rfc3744)。
• rfc4791：将日历扩展程序导入 WebDAV (CalDAV)
  • 支持 HTTP 方法 REPORT。除有空-忙碌-查询外的所有报告 。
  • 不支持 HTTP 方法 MKCALENDAR。
  • 不支持 AUDIO 操作。
• rfc5545：i 日历
  • CalDAV 接口中显示的数据会根据 i 日历规范
  • 目前不支持 VTODO 或 VJOURNAL 数据。
  • 不支持允许用户设置的网址属性的 Apple iCal® 扩展程序。
• rfc6578：WebDAV 的集合同步
  • 客户端应用程序必须在 初始同步。
• rfc6638：安排扩展程序到 CalDAV 的发送时间
  • 支持简单的“收件箱”（始终为空）。
  • 您收到的邀请会自动发送到您的“活动”中 而不是将其放入您的“收件箱”中
  • 不支持空闲/忙碌查找功能。
• caldav-ctag-02：CalDAV 中的日历集合实体标记 (CTag)
  • 日历 ctag 就像资源 etag；当出现任何情况时 日历中的变化。这样，客户端应用就可以 可快速判断出无需同步任何更改 事件。
• calendar-proxy：CalDAV 中的日历用户代理功能
  • 为了提高 iOS 设备（iOS 设备）的日历同步性能， 不支持委托功能，则使用 calendar-proxy-read-for 或 具有 iOS UserAgent 的 calendar-proxy-write-for 属性将失败。

目前，我们尚未全面实施所有相关的 。不过，对于许多客户端（例如 Apple 的日历应用） CalDAV 协议应该能正确互操作。

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

创建客户端 ID

要使用 CalDAV API Google 账号。 如果您已经拥有可以使用的账号，那么就大功告成了。

在向 CalDAV API 发送请求之前，您必须先注册 Google API 控制台。

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

下一步是激活 CalDAV API。

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

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

。 要执行 CalDAV API 请求，您需要 Client ID 和 Client Secret。

如需查找项目的客户端 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 服务器将拒绝对请求进行身份验证 除非该数据是通过 HTTPS 通过 Google 账号的 OAuth 2.0 身份验证进行的， 尝试通过 HTTP 连接或使用基本身份验证会导致 HTTP 401 Unauthorized 状态代码。

如果客户端程序（例如 Apple 的日历应用）要求使用 principal 集合作为起点，要连接的 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. 的商标。