使用 CardDAV 协议管理联系人

您可以使用 Google 的 CardDAV 协议查看和管理您的联系人。

联系人存储在用户的 Google 帐号中；大多数 Google 服务都可以访问联系人列表。您的客户端应用可以使用 CardDAV API 创建新联系人、修改或删除现有联系人，以及查询符合特定条件的联系人。

规范

完整规范尚未实现，但 Apple iOSTM 通讯录和 macOS 等许多客户端都应该能够正确互操作。

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

• rfc2518：适用于分布式开发的 HTTP 扩展程序 (WebDAV)
  • 支持 HTTP 方法 GET、PUT、DELETE、OPTIONS 和 PROPFIND。
  • 不支持 HTTP 方法 LOCK、UNLOCK、COPY、MOVE 或 MKCOL。
  • 不支持任意 WebDAV 属性。
  • 不支持 WebDAV 访问权限控制 (rfc3744)。
• rfc5995：使用 POST 将成员添加到 WebDAV 集合
  • 支持在不指定 ID 的情况下创建新联系人。
• rfc6352：CardDAV：用于网页分布式编写和版本控制 (WebDAV) 的 vCard 扩展
  • 支持 HTTP 方法 REPORT，但并非所有已定义的报告都会实现。
  • 支持提供主要集合和联系人集合。
• rfc6578：WebDAV 的集合同步
  • 客户端应用必须在初始同步后切换到此操作模式。
• rfc6749：OAuth 2.0 授权框架和 rfc6750：OAuth 2.0 授权框架：不记名令牌使用情况
  • 支持使用 OAuth 2.0 HTTP Authentication 对 CardDAV 客户端程序进行身份验证。Google 不支持任何其他身份验证方法。 为保证联系人数据的安全，我们要求 CardDAV 连接使用 HTTPS。
• rfc6764：查找用于 WebDAV (CalDAV) 和 vCard 扩展的 WebDAV 扩展 (CardDAV) 服务
  • 必须根据 rfc6764 的第 6 节引导 CardDAV 网址。
• 支持 Caldav-ctag-02：CalDAV 中的日历集合实体标记 (CTag)，该标记在 CardDAV 和 CalDAV 规范之间共享。联系人 ctag 就像是资源 ETag；当联系人通讯簿中的任何内容发生更改时，它也会随之更改。这样，客户端程序就可以快速确定它不需要同步任何已更改的联系人。
• Google 使用 VCard 3.0 作为联系人编码格式。请参阅：rfc6350: VCard 3.0。

Google 的 CardDAV 需要 OAuth 2.0

Google 的 CardDAV 接口需要使用 OAuth 2.0。请参阅下面链接的文档，了解如何使用 OAuth 2.0 访问 Google API：

• 使用 OAuth 2.0 访问 Google API
• 对安装的应用使用 OAuth 2.0

连接到 Google 的 CardDAV 服务器

CardDAV 协议支持发现地址簿 URI 和联系人资源 URI。您不得对任何 URI 进行硬编码，因为它们可能会随时发生变化。

客户端应用必须使用 HTTPS，并且必须为用户的 Google 帐号提供 OAuth 2.0 身份验证。CardDAV 服务器不会对请求进行身份验证，除非请求通过 Google 帐号的 OAuth 2.0 身份验证通过 HTTPS 到达，并且您的应用已在 DevOps 控制台中注册。如果您尝试通过基本身份验证或与 Google 帐号不匹配的电子邮件地址/密码通过 HTTP 进行连接，则会产生 HTTP 401 Unauthorized 响应代码。

如需使用 CardDAV，您的客户端程序必须先通过在以下各项上执行 HTTP PROPFIND 来连接到规范发现路径：

https://www.googleapis.com/.well-known/carddav

重定向 (HTTP 301) 到地址簿资源后，您的客户端程序即可对其执行 PROPFIND，以发现 DAV:current-user-principal、DAV:principal-URL 和 addressbook-home-set 属性。然后，您的客户端程序便可以对 addressbook-home-set 执行 PROPFIND，并查找 addressbook 和 collection 资源，以此发现主地址簿。此流程的完整说明不在本文档的讨论范围内。如需了解详情，请参阅 rfc6352。

不得通过针对常用 URI 的 PROPFIND 在 HTTP 301 响应中返回的重定向路径必须永久缓存（如 rfc6764 所示）。设备应定期重新尝试已知 URI 发现，以验证缓存的路径是否仍是最新的，并在路径发生变化时重新同步。Google 建议税率为每 2-4 周一次。

资源

CardDAV 使用 REST 概念。客户端应用根据其 URI 指定的资源执行操作。我们在此处指定当前的 URI 结构，以帮助开发者了解下一部分中的概念。该结构可能会发生更改，且不得硬编码。相反，资源应根据 RFC 进行发现。

1. 主帐号
   • https://www.googleapis.com/carddav/v1/principals/userEmail
2. 家居套装
   • https://www.googleapis.com/carddav/v1/principals/userEmail/lists
3. 地址簿
   • https://www.googleapis.com/carddav/v1/principals/userEmail/lists/default
4. 联系人
   • https://www.googleapis.com/carddav/v1/principals/userEmail/lists/default/contactId

同步联系人

以下是支持的操作的一般说明。开发者应在相关 RFC 中查找详细信息。请求和响应主要使用 XML 进行编码。以下是客户端应用用于同步的主要操作：

• 使用 CTag
  • 客户端程序会对地址簿资源使用 getctag PROPFIND 请求，以确定服务器上是否有任何联系人发生更改，从而确定是否需要进行同步。如果有任何联系人发生变化，此属性的值肯定会发生变化。客户端应用应存储此值，并仅在首次同步时使用，并在 sync-token 失效时用作后备值。定期轮询 getctag 属性会导致节流。
• 使用 sync-token
  • 客户端程序使用地址簿上的 sync-token PROPFIND 请求获取代表其当前状态的 sync-token。客户端应用必须存储此值并定期发出 sync-collection REPORT 请求，以确定自上次发出 sync-token 以来的更改。颁发的令牌的有效期为 29 天，REPORT 响应将包含新的 sync-token。
• 使用 ETag
  • 客户端应用对地址簿资源发出 getetag PROPFIND 请求（DEPTH 标头等于 DEPTH_1）。通过维护每个联系人的 ETag 值，客户端程序可以请求更改 ETag 的联系人的值。
• 检索联系人
  • 客户端应用通过发出 addressbook-multiget REPORT 请求来检索联系人。根据联系人 URI 列表，报告会以 VCard 3.0 值的形式返回请求的所有联系人。每个条目都包含联系人的 ETag。
• 插入联系人
  • 客户端应用向 VCard 3.0 格式的新联系人发出 POST 请求。响应中将包含新联系人的 ID。
• 更新联系人
  • 客户端应用使用 VCard 3.0 格式发出包含更新后的联系人的 PUT 请求。如果地址簿中已有该联系人，则系统会更新该联系人。
  • 客户端应用应包含 If-Match，其中包含联系人当前已知的 ETag。如果服务器上的当前 ETag 与客户端程序发送的 ETag 不同，服务器将拒绝 PUT 请求（通过 HTTP 412）。这样可以对更新进行序列化。
• 删除联系人
  • 客户端应用通过针对联系人 URI 发出 DELETE 请求来删除联系人。