您可以使用 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)。
- 支持 HTTP 方法
- rfc5995:使用 POST 将成员添加到 WebDAV 集合
- 支持在不指定 ID 的情况下创建新联系人。
- rfc6352:CardDAV:针对网络分布式编写和版本控制 (WebDAV) 的 vCard 扩展
- 支持 HTTP 方法
REPORT
,但并非所有定义的报告都会实现。 - 支持提供主账号集合和联系人集合。
- 支持 HTTP 方法
- rfc6578:WebDAV 的集合同步
- 客户端应用在初始同步后必须切换到此操作模式。
- rfc6749:OAuth 2.0 授权框架和 rfc6750:OAuth 2.0 授权框架:不记名令牌使用
- 支持使用 OAuth 2.0 HTTP 身份验证对 CardDAV 客户端程序进行身份验证。Google 不支持任何其他身份验证方法。为保证联系人数据的安全,我们要求 CardDAV 连接使用 HTTPS。
- rfc6764:查找 WebDAV (CalDAV) 的日历扩展和 WebDAV 的 vCard 扩展 (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,请参阅下方链接的文档:
正在连接到 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-principal
、DAV:principal-URL
和 addressbook-home-set
属性。然后,您的客户端程序可以通过对 addressbook-home-set
执行 PROPFIND
并查找 addressbook
和 collection
资源来发现主账号地址簿。有关此过程的完整说明不在本文档的讨论范围内。如需了解详情,请参阅 rfc6352。
HTTP 301
响应中通过知名 URI 上的 PROPFIND
返回的重定向路径不得永久缓存(根据 rfc6764)。设备应定期重试众所周知的 URI 发现,以验证缓存路径是否仍是最新的,并在路径发生变化时重新同步。Google 建议每 2-4 周检查一次频率。
资源
CardDAV 使用 REST 概念。客户端应用对由其 URI 指定的资源执行操作。此处指定当前的 URI 结构,以帮助开发者了解下一部分中的概念。结构可能会发生变化,因此不得采用硬编码。而是应根据 RFC 发现这些资源。
- 主账号
- https://www.googleapis.com/carddav/v1/principals/
userEmail
- https://www.googleapis.com/carddav/v1/principals/
- Home Set
- https://www.googleapis.com/carddav/v1/principals/
userEmail
/lists
- https://www.googleapis.com/carddav/v1/principals/
- 地址簿
- https://www.googleapis.com/carddav/v1/principals/
userEmail
/lists/default
- https://www.googleapis.com/carddav/v1/principals/
- 联系
- https://www.googleapis.com/carddav/v1/principals/
userEmail
/lists/default/contactId
- https://www.googleapis.com/carddav/v1/principals/
同步联系人
以下是对支持的操作的一般说明。开发者应在相关 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
)。这样便可对更新进行乐观的序列化。
- 客户端应用以 VCard 3.0 格式发出包含更新后的联系人的
- 删除联系人
- 客户端应用通过针对联系人 URI 发出
DELETE
请求来删除联系人。
- 客户端应用通过针对联系人 URI 发出