BoxPlayer 实战：阿里云盘通讯录 API（contact）接口详解——列出、删除与备份添加

本篇技术指南以 BoxPlayer 仓库中整理的阿里云盘 SDK 接口文档里的通讯录（contact）模块为核心，完整讲解阿里云盘通讯录的三个核心接口：通讯录列出（contact/list）、通讯录删除（contact/delete）、通讯录备份添加（contact/add）。文档由仓库作者于 2022 年 3 月整理，与编程语言无关，适合任何需要对接阿里云盘通讯录备份/同步能力的开发者。读完本文，你将掌握这三个接口的完整请求参数、响应结构与 vCard 数据格式，并能结合 BoxPlayer 中 AliHttp 统一请求封装 的实现细节，正确地在自己的客户端中构建携带鉴权头的请求。

---

一、通讯录接口概览

阿里云盘通讯录接口均位于 https://api.aliyundrive.com/adrive/v1/contact/ 路径下，全部使用 POST 方法，请求体为 JSON。三个接口的功能与路径如下：

接口	HTTP 方法	完整路径	核心作用
通讯录列出	POST	https://api.aliyundrive.com/adrive/v1/contact/list	拉取当前账号备份的全部通讯录条目
通讯录删除	POST	https://api.aliyundrive.com/adrive/v1/contact/delete	按条目 id 批量删除已备份的联系人
通讯录备份添加	POST	https://api.aliyundrive.com/adrive/v1/contact/add	上传/备份新的 vCard 联系人，支持批量

从路径设计与返回结构看，这套接口在语义上对应网盘客户端的"通讯录备份"功能：联系人以 vCard 标准格式存储为服务端条目，每个条目拥有独立的 id，通过 hash 字段标识内容指纹，从而实现增量备份与去重。

与 BoxPlayer 项目的对应关系

BoxPlayer 是聚合网盘管理 + 影视聚合应用，其前端对阿里云盘所有接口的调用都收敛在 src/aliapi/alihttp.ts 的 AliHttp 类中。该类定义了：

• static baseApi = 'https://api.aliyundrive.com/'：所有 adrive/v1 系列接口统一拼接此基地址；
• Post(url, postData, user_id, share_token)：发送 POST 请求并注入 Authorization: Bearer <access_token>、x-device-id、x-signature、x-request-id 等头；
• 在 CatchError 中，遇到 AccessTokenInvalid / AccessTokenExpired 会通过 refresh_token 自动刷新令牌后重试，遇到 UserDeviceIllegality / UserDeviceOffline 会自动刷新 Session。

因此，在实现本文的三个通讯录接口时，可直接复用这套封装，无需自行处理令牌续期与设备签名。

---

二、通讯录列出（contact/list）

请求

POST: https://api.aliyundrive.com/adrive/v1/contact/list

请求体为空 JSON 对象：

{}

响应

{
  "items": [
    {
      "id": 223963400,
      "content": {
        "format": "vcard",
        "hash": "1a48648e8b140ae80be048f1681cfbe24a7b9579c2ffbabe2686eb79338dfe14",
        "value": "BEGIN:VCARD\r\nVERSION:4.0\r\nPRODID:ez-vcard 0.11.2\r\nKIND:individual\r\nFN:高青\r\nN:高;青;;;\r\nTEL;TYPE=cell:15000065001\r\nEND:VCARD\r\n",
        "version": "4.0"
      },
      "gmt_create": 1647864044589
    },
    {
      "id": 224054214,
      "content": {
        "format": "vcard",
        "hash": "978edd2d967b94b34d3a90c00cbd4819e239f21a6f72f6a2f87b522fe81a62f4",
        "value": "BEGIN:VCARD\r\nVERSION:4.0\r\nPRODID:ez-vcard 0.11.2\r\nKIND:individual\r\nFN:木门\r\nN:木;门;;;\r\nTEL;TYPE=cell:03100000981\r\nEND:VCARD\r\n",
        "version": "4.0"
      },
      "gmt_create": 1647864055972
    }
  ],
  "total_count": 2
}

响应字段解析

字段	类型	说明
items[].id	number	通讯录条目的服务端唯一标识，删除操作即依赖此 id
items[].content.format	string	内容格式，固定为 vcard
items[].content.hash	string	内容指纹（SHA-256 风格十六进制串），用于去重与增量判断
items[].content.value	string	完整的 vCard 4.0 文本（含 \r\n 换行），见下文格式解读
items[].content.version	string	vCard 版本号，此处为 4.0
items[].gmt_create	number	条目创建时间，Unix 毫秒时间戳，例如 1647864044589 对应 2022-03-21 左右
total_count	number	通讯录总条目数

从响应样例可以推断：list 接口一次返回全部条目（样例中 total_count 与 items 长度一致），适合作为全量拉取入口；结合 hash 字段与本地已备份数据比对，即可实现"仅上传新增/变更联系人"的增量备份策略。

vCard 数据格式解读

value 字段是标准 vCard 4.0 文本，由 Java 库 ez-vcard 0.11.2 生成（见 PRODID 行）。以第一个条目为例：

BEGIN:VCARD
VERSION:4.0
PRODID:ez-vcard 0.11.2
KIND:individual
FN:高青
N:高;青;;;
TEL;TYPE=cell:15000065001
END:VCARD

各属性含义：

• VERSION:4.0：遵循 vCard 4.0 规范；
• KIND:individual：条目类型为个人；
• FN：格式化姓名（Formatted Name）；
• N：结构化姓名，分号分隔的"姓;名;中间名;称号;后缀"，高;青;;; 即姓"高"、名"青"；
• TEL;TYPE=cell：电话号码及其类型（移动电话），值如 15000065001。

注意文本中实际使用 \r\n（CRLF）作为行分隔符，在 JSON 字符串中显示为 \r\n。解析 vCard 时务必按 CRLF 切分，否则易出现行拼接错误。

---

三、通讯录删除（contact/delete）

请求

POST: https://api.aliyundrive.com/adrive/v1/contact/delete

请求体传入待删除条目的 id 数组：

{ "ids": [224206708] }

响应

{}

删除接口支持批量删除（ids 为数组），成功时返回空 JSON 对象 {}。在实际客户端中，应优先从本地"已删除联系人"队列收集 id 后一次性提交，减少请求次数；同时建议对响应做非空校验，避免误判失败。

使用注意

• ids 必须来自 contact/list 返回的 items[].id，自行拼接无效 id 会导致删除失败；
• 删除为不可逆操作，涉及用户通讯录数据，建议在 UI 层二次确认，并在删除前保留本地缓存用于恢复。

---

四、通讯录备份添加（contact/add）

请求

POST: https://api.aliyundrive.com/adrive/v1/contact/add

请求体为 items 数组，每个元素包含 hash、version、value、avatar、format 五个字段：

{
  "items": [
    {
      "hash": "978edd2d967b94b34d3a90c00cbd4819e239f21a6f72f6a2f87b522fe81a62f4",
      "version": "4.0",
      "value": "BEGIN:VCARD\r\nVERSION:4.0\r\nN:木;门\r\nTEL;TYPE=cell:03000080981\r\nKIND:individual\r\nEND:VCARD\r\n",
      "avatar": "",
      "format": "vcard"
    }
  ]
}

响应

{
  "items": [
    {
      "id": 223963801,
      "content": {
        "format": "vcard",
        "hash": "978edd2d967b94b34d3a90c00cbd4819e239f21a6f72f6a2f87b522fe81a62f4",
        "version": "4.0"
      }
    }
  ]
}

请求参数说明

字段	类型	说明
items[].hash	string	内容哈希，与 list 响应中的 content.hash 同源。上传前先比对本地联系人哈希与云端哈希，哈希已存在的条目可跳过，实现去重
items[].version	string	vCard 版本，固定 4.0
items[].value	string	vCard 文本内容，换行符为 \r\n
items[].avatar	string	头像数据，可为空字符串
items[].format	string	格式标识，固定 vcard

响应解析与增量备份闭环

响应中的 items[].id 是服务端为新上传条目分配的 id（样例中 223963801），content 回显了 format、hash、version。结合三个接口，即可构成完整的通讯录备份闭环：

1. 全量拉取：调用 contact/list，得到云端全部条目与各自 hash；
2. 本地比对：将本地通讯录的每个联系人生成 vCard 文本并计算哈希，与云端 hash 比对；
3. 增量上传：仅对云端不存在的哈希调用 contact/add 上传，同步后把返回的 id 记入本地映射表；
4. 差异删除：本地已删除的联系人，用 contact/delete 按 id 批量清除；
5. 循环校验：再次 contact/list 对比 total_count，确认两端一致。

关于 hash 的生成

文档样例中的哈希长度为 64 个十六进制字符（如 978edd2d967b94b34d3a90c00cbd4819e239f21a6f72f6a2f87b522fe81a62f4），与 SHA-256 输出长度一致；但从仓库现有代码看，BoxPlayer 并未在 src/aliapi 中调用 contact 系列接口，因此 hash 的具体生成算法（如是否对规范化后的 vCard 文本取摘要）无法从仓库直接确认。建议以"服务端 list 返回的 hash 为准、上传时原样回填"的方式保证一致性——这也是备份类接口的常见做法。

---

五、鉴权与调用前置条件

阿里云盘开放接口的鉴权链路可参考 src/aliapi/alihttp.ts 的实现，调用本文三个接口前需要满足：

1. 持有有效 access_token：通过网页版登录 token/get 接口获取，请求头携带 Authorization: Bearer <access_token>；
2. 设备签名头：非 OpenAPI 路径（本系列接口属于 adrive/v1 且非 openapi.alipan.com）需要携带 x-device-id、x-signature、x-request-id，其中签名由 src/aliapi/utils.ts 的 GetSignature 生成（参见 user.ts 中的 Session 创建逻辑）；
3. Content-Type：application/json（见 alihttp.ts 中 _Post 对 aliyundrive 域的设置）；
4. Token 过期自动处理：AliHttp.CatchError 在收到 AccessTokenInvalid/AccessTokenExpired 时自动走 refresh_token 刷新，会话失效时自动重建 Session，客户端无需手动介入。

注意：文档整理于 2022 年 3 月（gmt_create 时间戳可佐证），接口字段与当前线上行为可能存在差异。实际接入时建议先用真实账号小流量验证，并关注响应中的错误码（如 UserDeviceIllegality 表示设备签名失效）。

---

六、小结

本文基于 adrive sdk/contact.md 完整还原了阿里云盘通讯录的三大接口：

• contact/list：空参 POST，返回 items（含 vCard 文本、hash、id）与 total_count，是全量同步的起点；
• contact/delete：按 ids 批量删除，返回空对象；
• contact/add：批量上传 vCard 条目（含 hash/version/value/avatar/format），返回服务端分配的 id。

三个接口配合 vCard 4.0 文本与 hash 指纹，可以构建完整的"拉取 → 比对 → 增量上传 → 差异删除"通讯录备份闭环。接入 BoxPlayer 时，直接复用 AliHttp 的统一 POST 封装与自动 Token/Session 刷新能力即可，无需重复实现鉴权细节。后续如需扩展，可继续查阅仓库中同批整理的用户信息接口、令牌接口等文档，构建更完整的云盘账号管理能力。