使用 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，且 OAuth 2.0 身份验证必须使用 为用户的 Google 账号提供的值。除非请求通过 HTTPS 传入并使用 Google 账号的 OAuth 2.0 身份验证，并且您的应用已在 Play 管理中心注册，否则 CardDAV 服务器不会对请求进行身份验证。任何尝试通过 HTTP 使用基本身份验证或使用与 Google 账号不匹配的电子邮件地址/密码进行连接的行为都会导致 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。

HTTP 301 响应中通过 PROPFIND 返回的重定向路径 已知 URI 不得被永久缓存（根据 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 请求 Book 以获取表示其当前状态的 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。
  • 更新联系人
    • 客户端应用发出 PUT 请求，其中包含采用 VCard 3.0 格式的更新版联系人。如果联系人已存在于地址簿中，系统会更新该联系人。
    • 客户端应用应包含一个 If-Match 标头，其中包含联系人的当前已知 ETag。然后，服务器会拒绝 PUT 请求（包含 HTTP 412），前提是服务器上的当前 ETag 为 与客户端程序发送的 ETag 不同。这样， 乐观更新序列化。
  • 删除联系人
    • 客户端应用通过发出 DELETE 请求来删除联系人 与联系人 URI 进行比对。