BoxPlayer 中的阿里云盘用户 API 接口全解析：用户信息、容量、设备与福利社接口实战

原创2026-10-03 18:17:071,729 阅读

文章标签：桌面应用音视频AI Agent人工智能

BoxPlayer 中的阿里云盘用户 API 接口全解析：用户信息、容量、设备与福利社接口实战

导读

本文基于 BoxPlayer 仓库 adrive sdk/user.md 整理的阿里云盘（AliyunDrive）用户域 HTTP 接口文档，围绕"用户"这一主题系统讲解官方接口的请求路径、请求体与响应结构。文章不仅完整继承原文档的全部接口定义，还结合仓库源码 src/aliapi/user.ts 中的真实调用实现，说明每个接口在 BoxPlayer 客户端中如何被消费、字段如何被解析与展示，帮助读者在自研网盘客户端、SDK 或自动化脚本中快速落地这些接口。读完本文，你将掌握阿里云盘用户信息的查询/修改、容量与 VIP 权益读取、登录设备管理、福利码兑换与福利社任务查询的完整接口调用方案。

背景说明：该文档系列是 2022-03 整理的阿里云盘 SDK 接口数据，共 144 个接口，与编程语言无关，只记录官方接口参数，便于据此开发（见 adrive sdk/ReadMe.md）。本文聚焦其中的用户（user）域接口。

一、接口调用前的鉴权约定

用户域接口大多位于 api.aliyundrive.com 或 member.aliyundrive.com 域名下，统一使用 POST 方法。调用前需要先通过登录换取 access_token。

网页版登录接口（见 adrive sdk/token.md）：

POST: https://api.aliyundrive.com/token/get

请求体：

{ "code": "f98788cef51641728f2aad9c64a96a63", "loginType": "normal", "deviceId": "CPH800000000AbfFPI5QSJjO" }

响应中返回 access_token、refresh_token、default_drive_id、user_id、nick_name、expires_in（7200 秒）等关键字段，之后所有用户域接口都需要携带该 access_token（Authorization: Bearer <token>）以及用户会话标识。

从源码看，BoxPlayer 对 token 的管理非常工程化。在 src/aliapi/user.ts 中定义了多组令牌/会话的防重入锁与限频时间戳：

export const TokenReTimeMap = new Map<string, number>()
export const TokenLockMap = new Map<string, number>()
export const OpenApiTokenReTimeMap = new Map<string, number>()
export const OpenApiTokenLockMap = new Map<string, number>()
export const SessionLockMap = new Map<string, number>()
export const SessionReTimeMap = new Map<string, number>()

TokenLockMap / TokenReTimeMap：普通 access_token 的并发锁与 5 分钟限频时间戳；
OpenApiTokenLockMap / OpenApiTokenReTimeMap：开放平台 token（openapi.alipan.com）的同类机制；
SessionLockMap / SessionReTimeMap：登录会话（session_expires_in）的同类机制。

ApiTokenRefreshAccount（src/aliapi/user.ts）通过 https://auth.aliyundrive.com/v2/account/token 用 refresh_token 换新 token，并在成功后回写 user_id、nick_name、avatar、default_drive_id 等字段；ApiSessionRefreshAccount（src/aliapi/user.ts）则通过 https://api.aliyundrive.com/users/v1/users/device/create_session 刷新会话签名（signature、pubKey），会话有效期约 30 分钟。这些实现印证了用户域接口的鉴权基础：稳定持有有效的 access_token 与会话签名。

二、用户信息：查询与修改

2.1 查询用户信息（v2/user/get）

获取当前登录用户的基础档案。

POST: https://api.aliyundrive.com/v2/user/get

请求体：

{}

响应：

{
  "domain_id": "bj29",
  "user_id": "9400000000bc480bbcbbb1e074f55a7f",
  "avatar": "https://ccp-bj29-bj-1592982087.oss-cn-beijing.aliyuncs.com/2GhCur3G%2F...",
  "created_at": 1623212076923,
  "updated_at": 1636164094577,
  "email": "",
  "nick_name": "mynane",
  "phone": "15100000111",
  "role": "user",
  "status": "enabled",
  "user_name": "151***111",
  "description": "",
  "default_drive_id": "9600002",
  "user_data": {},
  "deny_change_password_by_self": false,
  "need_change_password_next_login": false,
  "creator": "",
  "permission": null
}

关键字段说明：

字段	含义
`user_id`	用户唯一 ID，全接口通用的账号标识
`domain_id`	用户所属区域节点，如 `bj29`
`nick_name` / `user_name`	昵称 / 脱敏登录名（如 `151***111`）
`avatar`	头像 URL（OSS 直链）
`phone` / `email`	手机号 / 邮箱
`role`	角色（普通用户为 `user`）
`status`	账号状态（`enabled` 等）
`default_drive_id`	默认资源库 driveId，几乎所有文件操作的基础
`created_at` / `updated_at`	创建 / 更新时间戳（毫秒）

BoxPlayer 源码中对应实现为 ApiUserDriveInfo（src/aliapi/user.ts），它调用 https://user.aliyundrive.com/v2/user/get（注意此处 host 为 user.aliyundrive.com），并把响应映射到本地 token 结构：

token.default_drive_id = resp.body.default_drive_id
token.backup_drive_id = resp.body.backup_drive_id || resp.body.default_drive_id
token.resource_drive_id = resp.body.resource_drive_id
token.sbox_drive_id = resp.body.sbox_drive_id || ''

也就是说，客户端只关心其中的 driveId 体系（default_drive_id、backup_drive_id、resource_drive_id、sbox_drive_id），因为它们决定了后续所有文件、相册、保险箱操作的落盘位置。源码注释还保留了一条开放平台等价接口 https://openapi.alipan.com/adrive/v1.0/user/getDriveInfo 作为可切换实现。

2.2 修改用户信息（v2/user/update）

修改昵称、简介与头像（原文档注释明确：用户可以修改自己的 description、nick_name、avatar）。

POST: https://api.aliyundrive.com/v2/user/update

请求体：

{ "user_id": "9400000000bc480bbcbbb1e074f55a7f", "nick_name": "n_mynane4" }

响应：结构与 v2/user/get 相同（同上 userinfo）。

注意：user_id 为必传参数，只能修改上述三个字段，手机号、邮箱、角色等不可通过该接口变更。

三、空间用量与容量明细

3.1 已用空间（adrive/v1/user/driveCapacityDetails）

查询各资源库（网盘、备份盘、资源库、相册、保险箱、共享相册等）的占用字节数。

POST: https://api.aliyundrive.com/adrive/v1/user/driveCapacityDetails

请求体：

响应：

{ "drive_used_size": 7436100078094 }

原文档只给出了 drive_used_size 一项，但根据 BoxPlayer 源码 src/aliapi/user.ts 的解析逻辑，该接口实际返回的是一个细分结构，客户端会逐项取出：

const detail: IAliUserDriveDetails = {
  album_drive_used_size: 0,
  backup_drive_used_size: 0,
  default_drive_used_size: 0,
  drive_total_size: 0,
  drive_used_size: 0,
  note_drive_used_size: 0,
  resource_drive_used_size: 0,
  sbox_drive_used_size: 0,
  share_album_drive_used_size: 0
}

对应类型定义见 src/aliapi/models.ts：

export interface IAliUserDriveDetails {
  album_drive_used_size: number
  backup_drive_used_size: number
  default_drive_used_size: number
  drive_total_size: number
  drive_used_size: number
  note_drive_used_size: number
  resource_drive_used_size: number
  sbox_drive_used_size: number
  share_album_drive_used_size: number
}

字段对应关系：

响应字段	含义
`drive_used_size`	全部空间已用字节数
`drive_total_size`	全部空间总字节数
`default_drive_used_size`	默认资源库已用
`backup_drive_used_size`	备份盘已用
`resource_drive_used_size`	资源库已用
`album_drive_used_size`	相册已用
`note_drive_used_size`	笔记已用
`sbox_drive_used_size`	保险箱已用
`share_album_drive_used_size`	共享相册已用

3.2 容量明细（adrive/v1/user/capacityDetails）

该接口对应官方客户端中的"容量管理"页面（原文档记录其前端地址为 https://pages.aliyundrive.com/mobile-page/capacitymanager.html?disableNav=YES），用于列出每一笔容量来源及其有效期。

POST: https://api.aliyundrive.com/adrive/v1/user/capacityDetails

请求体：

响应：

{
  "capacity_details": [
    { "type": "MEMBER_TASK", "size": 107374182400, "expired": "2022-10-14T05:01:48.935Z", "description": "完成福利社任务", "latest_receive_time": "2021-07-09T11:15:42.845Z" },
    { "type": "NEW_USER", "size": 107374182400, "expired": "permanent", "description": "新用户赠礼", "latest_receive_time": "2021-05-14T07:11:03.521Z" },
    { "type": "REWARD_CODE", "size": 536870912000, "expired": "permanent", "description": "兑换福利码", "latest_receive_time": "2022-02-21T12:08:58.000Z" },
    { "type": "BETA", "size": 3298534883328, "expired": "permanent_condition", "description": "内测专享", "latest_receive_time": "2021-03-18T05:01:21.118Z" },
    { "type": "MEMBER_TASK", "size": 107374182400, "expired": "2021-07-08T11:15:42.905Z", "description": "完成福利社任务", "latest_receive_time": "2021-03-18T05:02:28.160Z" }
  ]
}

字段含义：

type：容量来源类型，常见取值包括 NEW_USER（新用户赠礼）、REWARD_CODE（兑换福利码）、MEMBER_TASK（福利社任务）、BETA（内测专享）等；
size：该笔容量字节数（如 107374182400 = 100GB，536870912000 = 500GB）；
expired：到期时间（ISO 8601），特殊取值 permanent（永久）、permanent_condition（永久但需每年激活）；
description：容量说明；
latest_receive_time：最近一次领取时间。

BoxPlayer 的 ApiUserCapacityDetails（src/aliapi/user.ts）在拿到 capacity_details 列表后，会对 expired 做本地化归类：

if (item.expired == 'permanent_condition') expiredstr = '永久有效，每年激活'
else if (item.expired == 'permanent') expiredstr = '永久有效'
else {
  const data = new Date(item.expired)
  if (data > today) expiredstr = humanDateTimeDateStr(item.expired) + ' 到期'
  else expiredstr = '已过期'
}

随后通过 humanSize(item.size) 换算可读容量文案，并按 latest_receive_time 升序排序返回。客户端据此可以在设置/账户页向用户展示"100GB 新用户赠礼（永久）""500GB 兑换福利码（永久）"之类的容量构成清单。

3.3 用户信息（VIP + 空间权益，v2/databox/get_personal_info）

一次性同时获取会员权益（personal_rights_info）与空间用量（personal_space_info），是展示账户状态的最核心接口。

POST: https://api.aliyundrive.com/v2/databox/get_personal_info

请求体：

{}

响应：

{
  "personal_rights_info": {
    "spu_id": "non-vip",
    "name": "普通用户",
    "is_expires": false,
    "privileges": [
      { "feature_id": "download", "feature_attr_id": "speed_limit", "quota": -1 },
      { "feature_id": "drive", "feature_attr_id": "size_limit", "quota": 107374182400 },
      { "feature_id": "safe_box", "feature_attr_id": "size_limit", "quota": 53687091200 },
      { "feature_id": "upload", "feature_attr_id": "size_limit", "quota": 2199023255552 },
      { "feature_id": "video", "feature_attr_id": "backup", "quota": 1 },
      { "feature_id": "video", "feature_attr_id": "clarity_limit", "quota": 3 }
    ]
  },
  "personal_space_info": { "used_size": 7436100078094, "total_size": 8946416877568 }
}

结构解读：

personal_rights_info.spu_id：权益套餐 ID，non-vip 表示普通用户；
personal_rights_info.name：套餐名称（普通用户 / 会员等）；
personal_rights_info.is_expires：权益是否已到期；
personal_rights_info.privileges：权益明细数组，每个元素由 feature_id（功能域：download 下载、drive 网盘、safe_box 保险箱、upload 上传、video 视频）、feature_attr_id（属性：speed_limit 限速、size_limit 大小限制、backup、clarity_limit 清晰度限制）与 quota（配额，-1 表示无限制）组成；
personal_space_info.used_size / total_size：已用 / 总空间字节数。

BoxPlayer 的 ApiUserInfo（src/aliapi/user.ts）正是消费该接口，并据此生成账户卡片展示数据：

token.used_size = resp.body.personal_space_info.used_size
token.total_size = resp.body.personal_space_info.total_size
token.spu_id = resp.body.personal_rights_info.spu_id
token.is_expires = resp.body.personal_rights_info.is_expires
token.name = resp.body.personal_rights_info.name
token.spaceinfo = humanSize(token.used_size) + ' / ' + humanSize(token.total_size)

即"已用 / 总量（如 6.76TB / 8.14TB）"的展示文案由 personal_space_info 计算而来，权益名称与 spu_id 则决定客户端是否展示会员标识。此外源码还有 ApiUserVip（src/aliapi/user.ts），通过 business/v1.0/users/vip/info 拉取 VIP 到期信息，按 expire 倒序取最晚到期的一项，过期则回退显示"免费用户"。

四、相册相关接口

4.1 获取相册 driveId（adrive/v1/user/albums_info）

返回当前用户的相册资源库信息（相册是独立的 drive）。

POST: https://api.aliyundrive.com/adrive/v1/user/albums_info

请求体：

{}

响应：

{ "code": "200", "message": "success", "data": { "driveId": "9600002", "driveName": "alibum" }, "resultCode": "200" }

注意该接口的响应与多数接口不同，是"code/message/data/resultCode"的外层包装结构，data.driveId 才是真正要用的相册 driveId。

BoxPlayer 的 ApiUserPic（src/aliapi/user.ts）只取 resp.body.data.driveId 并存入 token.pic_drive_id，供相册浏览功能使用。

4.2 相册合并迁移（adrive/v1/user/albums_migration）

原文档标注为"未知（相册合并？）"，接口用于检测/执行相册数据迁移状态。

POST: https://api.aliyundrive.com/adrive/v1/user/albums_migration

请求体：

{}

响应：

{ "code": "200", "message": "success", "data": { "hasMigrateData": false, "drive": { "driveId": "9600002", "driveName": "alibum" } }, "resultCode": "200" }

data.hasMigrateData 表示是否存在待迁移的相册数据，data.drive 为迁移后的目标相册 drive。从源码结构看（src/aliapi/user.ts 中未发现直接调用），该接口在 BoxPlayer 中暂未使用，适合需要处理老相册数据合并的工具类项目自行接入。

五、实名信息（adrive/v1/user_verify/get）

查询账号实名认证状态（手机号末尾脱敏、姓名打码）。

POST: https://api.aliyundrive.com/adrive/v1/user_verify/get

请求体：

{}

响应：

{ "name": "*名子", "rp_verify_status": "pass", "card_number": "1****************3" }

字段含义：

name：脱敏后的实名姓名（保留部分字符，其余以 * 打码）；
rp_verify_status：实名认证状态，pass 表示已通过；
card_number：脱敏后的证件号码。

该接口适合在需要实名校验的功能（如大文件上传、会员购买、特殊权益领取）前调用，以判断用户是否已完成实名认证。

六、云服务授权管理（apps/v1/users/list_app_permissions）

列出当前账号授权的第三方应用/云服务权限。

POST: https://api.aliyundrive.com/apps/v1/users/list_app_permissions

请求体：

响应：

{ "result": [] }

result 数组列出所有已授权的应用权限项；空数组表示当前没有授权任何第三方应用。自研应用可据此实现"账号已授权服务"列表页，或在撤销授权后刷新该列表。

七、登录设备管理

7.1 设备列表（users/v1/users/device_list）

列出当前账号所有已登录的设备。

POST: https://api.aliyundrive.com/users/v1/users/device_list

请求体：

响应：

{
  "result": [
    { "deviceId": "q2e900000000ASdqMZ/pXgt7", "deviceName": "Chrome浏览器", "modelName": "Windows网页版", "city": "北京市", "loginTime": "2022-03-20 08:52" },
    { "deviceId": "SyQo00000000AbfHgMQi2AXv", "deviceName": "Chrome浏览器", "modelName": "Windows网页版", "city": "北京市", "loginTime": "2022-03-01 08:28" }
  ]
}

字段含义：

deviceId：设备唯一 ID（下线设备时必须回传）；
deviceName：设备名称；
modelName：客户端型号（如"Windows网页版"）；
city：最近登录城市；
loginTime：最近登录时间（本地化字符串）。

7.2 下线设备（users/v1/users/device_offline）

强制下线指定设备。原文档特别注明：需要先通过短信验证获取 umidToken。

POST: https://api.aliyundrive.com/users/v1/users/device_offline

请求体：

{ "deviceId": "q2e900000000ASdqMZ/pXgt7", "token": "CN-SPLIT-AQiE_......zdaLa2BOqAzuwCl3TS5Vp68qw", "umidToken": "dhhL00000000BzV/qXrSsXhU3k6buc1a" }

响应：

{ "result": true }

参数说明：

deviceId：待下线设备的 ID（来自 device_list）；
token：当前会话 token；
umidToken：短信验证后获得的临时安全令牌（必填前置条件）。

result: true 表示下线成功。安全上，该接口用于"在其他设备登录时踢掉旧设备"，实现账号会话的远程管理。

7.3 上报登录设备（users/v1/users/device）

登录成功后向服务端上报当前设备信息（配合 device/create_session 形成完整会话注册链路）。

POST: https://api.aliyundrive.com/users/v1/users/device

请求体：

{
  "modelName": "iPad4,4",
  "refreshToken": "3b920000000043f19fbc6b65c8dea11c",
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9......",
  "deviceName": "iPad"
}

响应：

{ "result": true }

字段含义：

modelName：设备型号标识；
deviceName：设备展示名称；
token：access_token（JWT）；
refreshToken：refresh_token。

与 BoxPlayer 源码对应，ApiSessionRefreshAccount 在上报设备时使用 deviceName: 'Edge浏览器'、modelName: 'Windows网页版' 与本地生成的 pubKey，通过 users/v1/users/device/create_session 建立会话（见 src/aliapi/user.ts），说明设备信息上报是维持会话有效性的必要环节。

八、兑换福利码（member.aliyundrive.com/v1/users/rewards）

兑换阿里云盘福利码（容量码 / 会员码），注意该接口位于会员域 member.aliyundrive.com。

POST: https://member.aliyundrive.com/v1/users/rewards

请求体：

{ "code": "山山水水" }

无效码的响应示例：

{ "success": false, "code": "30002", "message": "请输入有效的福利码", "totalCount": null, "nextToken": null, "maxResults": null, "result": { "message": "请输入有效的福利码" }, "arguments": null }

响应结构解读：

success：是否成功；
code：业务错误码（30002 表示福利码无效）；
message：提示信息；
result.message：结果明细中的提示。

BoxPlayer 的 ApiUserRewardSpace（src/aliapi/user.ts）实现了完整的分支处理：

const url = 'https://member.aliyundrive.com/v1/users/rewards'
const postData = { code: gift_code }
const resp = await AliHttp.Post(url, postData, user_id, '')
if (AliHttp.IsSuccess(resp.code)) {
  if (!resp.body || !resp.body.result) {
    return { status: false, message: resp.body?.message }
  }
  if (!resp.body.success) {
    return { status: false, message: resp.body?.message }
  } else {
    return { status: true, message: resp.body.result?.message }
  }
}

即客户端先判断 HTTP/传输层成功，再判断业务层 success 字段，最终把 result.message 作为成功文案回显给用户。

九、福利社任务（member 域）

福利社是阿里云盘通过完成任务换取容量的运营体系，接口同样位于 member.aliyundrive.com。

9.1 任务列表（v1/users/task_list）

POST: https://member.aliyundrive.com/v1/users/task_list

请求体：

响应（节选，完整结构含两个任务对象）：

{
  "success": true,
  "code": null,
  "message": null,
  "totalCount": null,
  "nextToken": null,
  "maxResults": null,
  "result": [
    {
      "idempotent": "5dd6000000004283a4be19f4a5ab647a",
      "position": 10,
      "id": "51",
      "name": "邀请好友用云盘",
      "code": "referral",
      "actionType": "openLink",
      "action": "smartdrive://vipcenter/referral",
      "url": "https://pages.aliyundrive.com/mobile-page/web/invitefriends.html",
      "appName": null,
      "description": "+800G/人",
      "backgroundImage": "https://img.alicdn.com/imgextra/i4/O1CN016LFIjK1SRL72iovyX_!!6000000002243-2-tps-819-456.png",
      "backgroundColor": "#D9E8FF",
      "darkBackgroundColor": "#D9E8FF",
      "textColor": "#6FBEEB",
      "darkTextColor": "#6FBEEB",
      "status": "unfinished",
      "createdAt": 1644718396417,
      "finishedAt": null,
      "notice": "容量一年有效",
      "topRightCorner": "限时任务",
      "detailName": "",
      "detailDescription": "https://pages.aliyundrive.com/mobile-page/web/beinvited.html?code=",
      "detailBackgroundImage": "",
      "detailIntroduction": null,
      "rewards": [{ "icon": "https://img.alicdn.com/imgextra/i1/O1CN015KvMU11Yj65cGXGCp_!!6000000003094-2-tps-72-72.png", "name": "", "description": "有效期一年" }],
      "detailRewardNotice": "",
      "process": { "current": 0, "max": 0 },
      "statusNotice": "",
      "explain": null,
      "referral": null,
      "monthlyCard": null,
      "popUps": null,
      "shareFissions": null,
      "subTasks": null,
      "shareAction": null,
      "darenShareViewModel": null
    },
    {
      "idempotent": "80bf00000000442b90368c27a7ec3443",
      "position": 3,
      "id": "66",
      "name": "第四周·周任务",
      "code": "adrive",
      "actionType": "openNative",
      "action": "smartdrive://vipcenter/opentaskcarddetail?taskId=66",
      "url": "",
      "appName": null,
      "description": "阿里云盘VIP免费领",
      "backgroundImage": "https://img.alicdn.com/imgextra/i3/O1CN01HK76N21tBlGdfXcjm_!!6000000005864-2-tps-1029-612.png",
      "backgroundColor": null,
      "darkBackgroundColor": null,
      "textColor": "#FFD601",
      "darkTextColor": "#FFD601",
      "status": "finished",
      "createdAt": 1645953637620,
      "finishedAt": 1647857247562,
      "notice": "一个月 VIP",
      "topRightCorner": "周年庆",
      "detailName": "第四周·周任务",
      "detailDescription": "阿里云盘VIP免费领",
      "detailBackgroundImage": "https://img.alicdn.com/imgextra/i3/O1CN01HK76N21tBlGdfXcjm_!!6000000005864-2-tps-1029-612.png",
      "detailIntroduction": null,
      "rewards": [{ "icon": "https://gw.alicdn.com/imgextra/i3/O1CN01nl3rNq1PWQc5cpUWQ_!!6000000001848-2-tps-72-72.png", "name": "阿里云盘VIP", "description": "完成两个任务即可获得1个月阿里云盘VIP " }],
      "detailRewardNotice": "",
      "process": { "current": 2, "max": 0 },
      "statusNotice": "领取阿里云盘VIP",
      "explain": { "title": "活动说明：\r\n1.  活动期为2022年3月21日-3月27日。\r\n2. 任务福利将于4月30日开启兑换，所有会员福利最晚兑换时间为2022年6月30日，过期后不可兑换。", "description": "" },
      "referral": null,
      "monthlyCard": null,
      "popUps": null,
      "shareFissions": null,
      "subTasks": null,
      "shareAction": null,
      "darenShareViewModel": null
    }
  ],
  "arguments": null
}

关键字段说明：

id：任务 ID，后续任务详情接口的入参；
name / description：任务名称 / 奖励描述（如"+800G/人"）；
actionType / action：完成任务的动作类型（openLink 打开链接 / openNative 唤起原生页面）与跳转协议（smartdrive://）；
status：任务状态，unfinished 未完成 / finished 已完成；
rewards：奖励数组，含图标、名称与描述；
process.current / process.max：完成进度；
topRightCorner：任务角标（如"限时任务""周年庆"）；
explain.title：活动规则说明文本。

9.2 任务详情（v1/users/task_detail）

POST: https://member.aliyundrive.com/v1/users/task_detail

请求体：

{ "taskId": "51" }

响应（"邀请好友用云盘"任务详情，含邀请返利扩展数据 referral）：

{
  "idempotent": "5dd6000000004283a4be19f4a5ab647a",
  "position": 10,
  "id": "51",
  "name": "邀请好友用云盘",
  "code": "referral",
  "actionType": "openLink",
  "action": "smartdrive://vipcenter/referral",
  "url": "https://pages.aliyundrive.com/mobile-page/web/invitefriends.html",
  "appName": null,
  "description": "+800 GB/人 一年有效",
  "backgroundImage": "https://img.alicdn.com/imgextra/i4/O1CN016LFIjK1SRL72iovyX_!!6000000002243-2-tps-819-456.png",
  "backgroundColor": "#D9E8FF",
  "darkBackgroundColor": "#D9E8FF",
  "textColor": "#FFD601",
  "darkTextColor": "#FFD601",
  "status": "unfinished",
  "createdAt": 1644718396417,
  "finishedAt": null,
  "notice": "",
  "topRightCorner": "限时任务",
  "detailName": "",
  "detailDescription": "https://pages.aliyundrive.com/mobile-page/web/beinvited.html?code=",
  "detailBackgroundImage": "",
  "detailIntroduction": null,
  "rewards": [{ "icon": "https://img.alicdn.com/imgextra/i1/O1CN015KvMU11Yj65cGXGCp_!!6000000003094-2-tps-72-72.png", "name": "", "description": "有效期一年" }],
  "detailRewardNotice": "",
  "process": { "current": 0, "max": 0 },
  "statusNotice": "",
  "explain": null,
  "referral": {
    "reward": 300,
    "userSignupAmount": 10,
    "userAmount": 10,
    "newUserTask": 10,
    "availableReward": 0,
    "verificationReward": 8000,
    "limitReward": 8000,
    "shortURL": "https://pages.aliyundrive.com/mobile-page/web/beinvited.html?code=0000007"
  },
  "monthlyCard": null,
  "popUps": null,
  "shareFissions": null,
  "subTasks": null,
  "shareAction": null,
  "darenShareViewModel": null
}

邀请任务的 referral 对象是本接口的核心增量：

字段	含义
`reward`	单次邀请奖励
`userSignupAmount` / `userAmount` / `newUserTask`	被邀请用户注册/使用产生的额度
`availableReward`	当前可领奖励
`verificationReward` / `limitReward`	最高可核验奖励 / 奖励上限
`shortURL`	带邀请码的分享短链（含 `code=` 参数）

9.3 任务批量详情（v1/users/batch_task_detail）

一次请求多个任务的完整详情，用于列表页批量加载。

POST: https://member.aliyundrive.com/v1/users/batch_task_detail

请求体：

{ "taskIds": ["52", "55", "58", "66", "69"] }

响应为数组（此处节选任务 66，重点展示其 subTasks 子任务结构）：

[
  {
    "idempotent": "80bf00000000442b90368c27a7ec3443",
    "position": 3,
    "id": "66",
    "name": "第四周·周任务",
    "code": "adrive",
    "actionType": "openNative",
    "action": "smartdrive://vipcenter/opentaskcarddetail?taskId=66",
    "url": "",
    "appName": null,
    "description": "阿里云盘VIP免费领",
    "backgroundImage": "https://img.alicdn.com/imgextra/i3/O1CN01HK76N21tBlGdfXcjm_!!6000000005864-2-tps-1029-612.png",
    "backgroundColor": null,
    "darkBackgroundColor": null,
    "textColor": "#FFD601",
    "darkTextColor": "#FFD601",
    "status": "finished",
    "createdAt": 1645953637620,
    "finishedAt": 1647857247562,
    "notice": "一个月 VIP",
    "topRightCorner": "周年庆",
    "detailName": "第四周·周任务",
    "detailDescription": "阿里云盘VIP免费领",
    "detailBackgroundImage": "https://img.alicdn.com/imgextra/i3/O1CN01HK76N21tBlGdfXcjm_!!6000000005864-2-tps-1029-612.png",
    "detailIntroduction": null,
    "rewards": [{ "icon": "https://gw.alicdn.com/imgextra/i3/O1CN01nl3rNq1PWQc5cpUWQ_!!6000000001848-2-tps-72-72.png", "name": "阿里云盘VIP", "description": "完成两个任务即可获得1个月阿里云盘VIP " }],
    "detailRewardNotice": "",
    "process": { "current": 2, "max": 0 },
    "statusNotice": "领取阿里云盘VIP",
    "explain": { "title": "活动说明：\r\n1.  活动期为2022年3月21日-3月27日。\r\n2. 任务福利将于4月30日开启兑换，所有会员福利最晚兑换时间为2022年6月30日，过期后不可兑换。", "description": "" },
    "referral": null,
    "monthlyCard": null,
    "popUps": null,
    "shareFissions": null,
    "subTasks": [
      {
        "id": 67,
        "name": "订阅一个云盘订阅号",
        "actionType": "openNative",
        "action": "smartdrive://app/subscription",
        "url": "",
        "idempotent": "0c260000000042d493714b53fc6da210",
        "status": "finished",
        "statusNotice": "已完成",
        "position": 0
      },
      {
        "id": 68,
        "name": "转存一个订阅号分享的文件",
        "actionType": "openNative",
        "action": "smartdrive://userpage/openroot?userId=ec11691148db442aa7aa374ca707543c",
        "url": "",
        "idempotent": "369f000000004f188d85e7f682f9633f",
        "status": "finished",
        "statusNotice": "已完成",
        "position": 0
      }
    ],
    "shareAction": null,
    "darenShareViewModel": null
  }
]

与 task_detail 的差异在于：批量接口返回数组，且复合任务会携带 subTasks 子任务数组（每个子任务含 id、name、action、status、statusNotice）。idempotent 为幂等键，同一任务多次请求该值不变，客户端可据此做去重与状态缓存。

十、首页 widgets（apps/v1/users/apps/widgets）

首页信息流 widgets 接口，返回类似"最近转存""你订阅的分享者有更新了"等首页动态。

POST: https://api.aliyundrive.com/apps/v1/users/apps/widgets

请求体：

响应：

最近转存,你订阅的分享者有更新了...

原文档该响应仅为示意文本，从接口命名与"widgets"语义可以推断，其用于驱动官方客户端首页的信息流卡片（转存动态、订阅更新提醒等）。BoxPlayer 中暂未见直接调用该接口的实现，属于可选接入项。

十一、源码视角：接口的工程化落地模式

从 src/aliapi/user.ts 整体实现可以总结出 BoxPlayer 消费用户域接口的统一模式，供自研客户端参考：

统一 HTTP 封装：所有请求走 AliHttp.Post(url, postData, token.user_id, '')，第三参数绑定用户会话，由封装层自动附加鉴权头与错误码处理（AliHttp.IsSuccess / AliHttp.HttpCodeBreak）；
失败分级：传输层失败与 HTTP 断连（HttpCodeBreak）分开处理，业务错误通过 DebugLog.mSaveWarning 落日志，避免污染用户界面；
限频与互斥：token 刷新、会话刷新均配 LockMap（防止并发重复刷新）+ ReTimeMap（5 分钟内不重复请求）双重保护；
字段沉淀到本地模型：default_drive_id、pic_drive_id、used_size、total_size、spu_id、vipname 等解析结果写回 ITokenInfo（见 src/aliapi/models.ts 的 IAliUserDriveDetails / IAliUserDriveCapacity），供账户页、文件树、上传/下载逻辑直接消费；
展示层本地化：容量到期文案（"永久有效""每年激活""已过期"）与可读大小（humanSize）在数据层完成，UI 直接渲染字符串。

与用户域强相关的还包含福利社签到体系：ApiUserSign（src/aliapi/user.ts）调用 member.aliyundrive.com/v1/activity/sign_in_list 获取签到日历、v1/activity/sign_in_reward 领取奖励，构成"签到 + 福利社任务 + 容量明细"的完整容量增长闭环，可配合上文 capacityDetails 中 MEMBER_TASK 类型的容量验证权益到账。

十二、实战注意事项

域名区分：用户档案类接口在 api.aliyundrive.com（或 user.aliyundrive.com），会员/福利/签到类在 member.aliyundrive.com，兑换福利码与任务接口务必使用会员域，否则会 404；
响应包装差异：albums_info、albums_migration 等接口返回 code/message/data/resultCode 包装，而 get_personal_info、task_list 等直接返回业务字段，解析时需分情况处理；
设备下线前置条件：device_offline 必须先完成短信验证获取 umidToken，且需同时携带 deviceId 与会话 token，三者缺一不可；
福利码错误码：rewards 接口失败时业务码 30002 对应"无效福利码"，应优先展示 result.message 而非笼统报错；
容量明细的 expired 特殊值：permanent 与 permanent_condition 不是时间字符串，解析时不能直接 new Date()，必须按原文档与源码逻辑单独判断；
接口时效性：本系列接口文档整理于 2022 年 3 月，具体字段与配额随官方版本演进可能变化，接入时应以实际响应为准并做好字段容错。

结语

本文完整梳理了阿里云盘用户域的全部接口——从用户档案查询/修改、容量与 VIP 权益读取，到相册 drive、实名信息、设备管理、福利码兑换与福利社任务，并逐一对照 BoxPlayer 在 src/aliapi/user.ts 中的真实消费实现。开发者既可将本文作为纯接口手册直接调用，也可借鉴 BoxPlayer 的锁机制、限频与字段沉淀模式，在自研网盘客户端中构建稳健的账号体系。

登录后查看全文

桌面应用音视频AI Agent人工智能

boxplayer

BoxPlayer 中的阿里云盘用户 API 接口全解析：用户信息、容量、设备与福利社接口实战

BoxPlayer 中的阿里云盘用户 API 接口全解析：用户信息、容量、设备与福利社接口实战

导读

一、接口调用前的鉴权约定

二、用户信息：查询与修改

2.1 查询用户信息（v2/user/get）

2.2 修改用户信息（v2/user/update）

三、空间用量与容量明细

3.1 已用空间（adrive/v1/user/driveCapacityDetails）

3.2 容量明细（adrive/v1/user/capacityDetails）

3.3 用户信息（VIP + 空间权益，v2/databox/get_personal_info）

四、相册相关接口

4.1 获取相册 driveId（adrive/v1/user/albums_info）

4.2 相册合并迁移（adrive/v1/user/albums_migration）

五、实名信息（adrive/v1/user_verify/get）

六、云服务授权管理（apps/v1/users/list_app_permissions）

七、登录设备管理

7.1 设备列表（users/v1/users/device_list）

7.2 下线设备（users/v1/users/device_offline）

7.3 上报登录设备（users/v1/users/device）

八、兑换福利码（member.aliyundrive.com/v1/users/rewards）

九、福利社任务（member 域）

9.1 任务列表（v1/users/task_list）

9.2 任务详情（v1/users/task_detail）

9.3 任务批量详情（v1/users/batch_task_detail）

十、首页 widgets（apps/v1/users/apps/widgets）

十一、源码视角：接口的工程化落地模式

十二、实战注意事项

结语

相关推荐

热门文章