此页面由 Cloud Translation API 翻译。

使用 CardDAV 协议管理联系人

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

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

规格

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

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

rfc2518：面向分布式创作的 HTTP 扩展 (WebDAV) <ph type="x-smartling-placeholder">
- 支持 HTTP 方法 GET、PUT、DELETE、OPTIONS 和 PROPFIND。
- 不支持 HTTP 方法 LOCK、UNLOCK、COPY、MOVE 或 MKCOL。
- 不支持任意（用户定义的）WebDAV 属性。
- 不支持 WebDAV 访问控制 (rfc3744)。
rfc5995：使用 POST 向 WebDAV 集合添加成员 <ph type="x-smartling-placeholder">
- 支持在不指定 ID 的情况下创建新联系人。
rfc6352：CardDAV：对 Web 分布式创作的 vCard 扩展，以及版本控制 (WebDAV) <ph type="x-smartling-placeholder">
- 支持 HTTP 方法 REPORT，但并非所有定义的报告都适用。
- 支持提供主账号集合和联系人集合。
rfc6578：WebDAV 的集合同步 <ph type="x-smartling-placeholder">
- 客户端应用程序必须在初始同步。
rfc6749：OAuth 2.0 授权框架和 rfc6750：OAuth 2.0 授权框架：不记名令牌使用
- 支持使用 OAuth 2.0 HTTP 对 CardDAV 客户端程序进行身份验证身份验证。Google 不支持任何其他身份验证方法。为了确保联系人数据的安全，我们要求使用 CardDAV 连接 HTTPS。
rfc6764：找到指向 WebDAV (CalDAV) 和 vCard Extensions to WebDAV (CardDAV) 的日历扩展程序的服务 <ph type="x-smartling-placeholder">
- CardDAV 网址的引导必须按照 rfc6764。
支持 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 的信息，请参见以下文档：

正在连接到 Google 的 CardDAV 服务器

CardDAV 协议可用于发现通讯簿和联系人资源 URI。您不得对任何 URI 进行硬编码，因为它们可能随时发生更改。

客户端应用必须使用 HTTPS，且 OAuth 2.0 身份验证必须使用为用户的 Google 账号提供的值。CardDAV 服务器不会对请求进行身份验证，除非请求通过 HTTPS 使用 OAuth 2.0 传送并且您的应用已在 DevConsole。任何尝试通过基本身份验证或与 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。

主账号 <ph type="x-smartling-placeholder">
- https://www.googleapis.com/carddav/v1/principals/userEmail
家居套装 <ph type="x-smartling-placeholder">
- https://www.googleapis.com/carddav/v1/principals/userEmail/lists
地址簿 <ph type="x-smartling-placeholder">
- https://www.googleapis.com/carddav/v1/principals/userEmail/lists/default
联系 <ph type="x-smartling-placeholder">
- https://www.googleapis.com/carddav/v1/principals/userEmail/lists/default/contactId

同步联系人

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

使用 CTag <ph type="x-smartling-placeholder">
- 客户端程序使用地址簿上的 getctag PROPFIND 请求确定服务器上是否有任何联系人已更改，从而判断是否需要进行同步。此属性的值如果任何联系人发生变化，我们保证会发生变化。客户端应用应存储此值，并仅在初次同步时将其用作在 sync-token 失效时进行回退。定期轮询 getctag 属性将导致节流。
使用 sync-token <ph type="x-smartling-placeholder">
- 客户端程序对地址使用 sync-token PROPFIND 请求 Book 以获取表示其当前状态的 sync-token。客户应用必须存储此值并定期发出 sync-collection REPORT 个请求用于确定自上次发出后发生的更改 sync-token。颁发的令牌的有效期为 29 天，并且REPORT 响应将包含新的 sync-token。
使用 ETag <ph type="x-smartling-placeholder">
- 客户端应用针对地址发出 getetag PROPFIND 请求图书资源（DEPTH 标题等于 DEPTH_1）。通过维护每个联系人的 ETag 值，客户端程序可以请求该值的联系人，其 ETag 发生了更改。
检索联系人 <ph type="x-smartling-placeholder">
- 客户端应用通过发出 addressbook-multiget REPORT 请求。根据给定的联系人 URI 列表报告会以 VCard 3.0 值返回所有请求的联系人。每个条目包含联系人的 ETag。
插入联系人 <ph type="x-smartling-placeholder">
- 客户端应用向 VCard 中的新联系人发出 POST 请求 3.0 格式。响应将包含新联系人的 ID。
更新联系人 <ph type="x-smartling-placeholder">
- 客户端应用向更新后的联系人发出 PUT 请求 VCard 3.0 格式。如果联系人已存在，系统会更新该联系人。
- 客户端应用应包含一个 If-Match 标头，该标头的联系人目前叫做 ETag。然后，服务器会拒绝 PUT 请求（包含 HTTP 412），前提是服务器上的当前 ETag 为与客户端程序发送的 ETag 不同。这样，乐观更新序列化。
删除联系人 <ph type="x-smartling-placeholder">
- 客户端应用通过发出 DELETE 请求来删除联系人与联系人 URI 进行比对。