使用 CardDAV 协议管理联系人

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

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

规格

完整的规范并未实现,但许多客户端(如 Apple iOSTM 通讯录和 macOS)应该可以正确互操作。

对于每个相关规范,Google 的 CardDAV 支持如下:

Google 的 CardDAV 要求使用 OAuth 2.0

Google 的 CardDAV 界面要求使用 OAuth 2.0。如需了解如何使用 OAuth 2.0 访问 Google API,请参阅下方链接的文档:

正在连接到 Google 的 CardDAV 服务器

CardDAV 协议允许发现通讯簿和联系人资源 URI。您不得对任何 URI 进行硬编码,因为它们随时都可能发生变化。

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

如需使用 CardDAV,您的客户端程序必须先通过对以下对象执行 HTTP PROPFIND 来连接到规范化发现路径:

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

将 (HTTP 301) 重定向到地址簿资源后,您的客户端程序可以对其执行 PROPFIND 以发现 DAV:current-user-principalDAV:principal-URLaddressbook-home-set 属性。然后,您的客户端程序可以通过对 addressbook-home-set 执行 PROPFIND 并查找 addressbookcollection 资源来发现主账号地址簿。有关此过程的完整说明不在本文档的讨论范围内。如需了解详情,请参阅 rfc6352

HTTP 301 响应中通过知名 URI 上的 PROPFIND 返回的重定向路径不得永久缓存(根据 rfc6764)。设备应定期重试众所周知的 URI 发现,以验证缓存路径是否仍是最新的,并在路径发生变化时重新同步。Google 建议每 2-4 周检查一次频率。

资源

CardDAV 使用 REST 概念。客户端应用对由其 URI 指定的资源执行操作。此处指定当前的 URI 结构,以帮助开发者了解下一部分中的概念。结构可能会发生变化,因此不得采用硬编码。而是应根据 RFC 发现这些资源。

  1. 主账号
    • https://www.googleapis.com/carddav/v1/principals/userEmail
  2. Home Set
    • 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
  • 插入联系人
    • 客户端应用向新联系人发出 POST 请求(采用 VCard 3.0 格式)。响应将包含新联系人的 ID。
  • 更新联系人
    • 客户端应用以 VCard 3.0 格式发出包含更新后的联系人的 PUT 请求。如果通讯簿中已存在该联系人,则系统会更新该联系人。
    • 客户端应用应包含一个 If-Match 标头,该标头包含联系人当前已知的 ETag。然后,如果服务器上当前的 ETag 与客户端程序发送的 ETag 不同,服务器将拒绝 PUT 请求(返回 HTTP 412)。这样便可对更新进行乐观的序列化。
  • 删除联系人
    • 客户端应用通过针对联系人 URI 发出 DELETE 请求来删除联系人。