使用具有下列 Scope 的 API Key,应用用户范围必须为 subject_scope={"mode":"all"}。
使用具有下列 Scope 的 API Key,应用用户范围必须为 subject_scope={"mode":"all"}。企业由鉴权后的 API Key 决定,不接受调用方指定企业。响应 Cache-Control: no-store;拒绝未知、重复和空查询参数。两个查询接口共用一个安装包读取 Scope。查询不改变下载配置或升级任务。与安装包管理页复用相同的筛选、分页和数据。获取全部版本需逐页查询。包含版本更新说明、最低兼容版本、安装/升级包、完整/差分元数据、发布状态、下载标记和活动任务 ID;不包含升级任务详情,不改变 OTA 判定。托管文件使用 download_link 下载(签名有效期 30 分钟),download_url 为存储地址。无专属打包权益时返回 403。
适用《通过 API 配置 QwenWork 管理后台》的“认证与请求头”章节:
将 <BASE_URL> 替换为企业部署的千问办公 API 服务地址,并填写实际参数。示例中的占位值不能直接用于请求。
Content-Type: application/json
401:API Key 无效;403:Scope、企业身份、用户范围或权益不满足;400/422:查询参数不合法;503:依赖不可用。临时故障采用退避重试。
网关可能在请求到达业务服务前以 HTML 返回 401/403;客户端应先检查 HTTP 状态及 Content-Type,再解析 JSON。业务服务错误使用上述公共错误结构。
所需权限
| 所需权限 | 资源 | Scope | 资源服务 |
|---|---|---|---|
| 客户端安装包(读取) | client-downloads | admin.v1.client-downloads.read | qwenwork-biz-service |
公共请求头
适用《通过 API 配置 QwenWork 管理后台》的“认证与请求头”章节:Authorization 必填,X-Request-Id 可选;本查询无需 Idempotency-Key。
请求参数
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
| page | query | integer · int64 | 否 | 页码; format="int64"; minimum=1; maximum=1000000; default=1 | - |
| page_size | query | integer · int64 | 否 | 每页条数; format="int64"; minimum=1; maximum=100; default=20 | - |
| q | query | string | 否 | 搜索版本或标题; maxLength=200 | - |
| platform | query | string | 否 | 操作系统; enum=["windows", "macos", "linux", "harmony"] | - |
| arch | query | string | 否 | CPU 架构; enum=["x64", "arm64", "universal64"] | - |
| enabled | query | string | 否 | 是否启用; enum=["true", "false"] | - |
| id | query | string · uuid | 否 | 记录 ID; format="uuid" | - |
| typed_only | query | boolean | 否 | 仅返回已有平台归属的版本 | - |
| release_status | query | string | 否 | 升级发布状态:未发布、发布中、部分发布或全量发布。; enum=["unreleased", "publishing", "partial", "full_released"] | - |
请求示例
将 <BASE_URL> 替换为企业部署的千问办公 API 服务地址,并填写实际参数。示例中的占位值不能直接用于请求。
响应状态表
| HTTP 状态码 | 触发条件 | 响应结构引用 | 客户端处理建议 |
|---|---|---|---|
| 200 | 请求成功 | 见本文“响应结果” | 读取结果。 |
| default | 认证、授权、参数校验或依赖错误 | 见《通过 API 配置 QwenWork 管理后台》的“通用错误”结构 | 按 HTTP 状态和 code 处理。 |
响应结果
Content-Type: application/json
| 名称 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
| items | array<object> | null | 是 | 结果列表 | - |
| page | integer · int64 | 是 | 页码; format="int64" | - |
| page_size | integer · int64 | 是 | 每页条数; format="int64" | - |
| total | integer · int64 | 是 | 符合条件的总数; format="int64" | - |
items[]
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| active_task_id | string | 否 | 尚未结束的升级任务 ID(不包含任务详情) |
| arch | string | 是 | CPU 架构 |
| central_minimum_version | string | 否 | 中心提供的建议最低版本;存在时返回,不改变升级决策。 |
| created_at | string · date-time | 是 | 创建时间; format="date-time" |
| download_platforms | array<string> | null | 否 | 当前由该记录提供下载安装包的平台;未用于下载时省略,包含历史配置。 |
| download_version | boolean | 否 | 是否为下载页使用的版本 |
| enabled | boolean | 是 | 是否启用 |
| id | string | 是 | 记录 ID |
| is_central_minimum | boolean | 否 | 是否为中心最低版本 |
| minimum_compatible_version | string | 否 | 该版本兼容的最低客户端版本;存在时返回,仅供提示。 |
| packages | array<object> | null | 是 | 安装包和升级包 |
| platform | string | 是 | 操作系统 |
| platforms | array<string> | null | 是 | 支持的操作系统 |
| publish_blocked_reason | string | 否 | 不能发布升级的原因;可发布时省略。; enum=["full_released", "not_above_baseline", "no_upgrade_package", "disabled"] 取值:"disabled"、"full_released"、"no_upgrade_package"、"not_above_baseline" |
| release_note | string | 是 | 版本更新说明 |
| release_status | string | 否 | 升级发布状态:未发布、发布中、部分发布或全量发布。; enum=["unreleased", "publishing", "partial", "full_released"] 取值:"full_released"、"partial"、"publishing"、"unreleased" |
| title | string | 是 | 版本标题 |
| updated_at | string · date-time | 是 | 更新时间; format="date-time" |
| version | string | 是 | 版本号 |
items[].packages[]
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| arch | string | 是 | CPU 架构 |
| checksum_md5 | string | 是 | MD5 校验值;空值表示未提供 |
| delta_from_version | string | 是 | 差分包的基础版本 |
| download_link | string | 否 | 可直接下载的链接;托管文件为临时签名链接 |
| download_url | string | 是 | 文件地址;列表中托管文件原始地址可能不能直接访问,应使用 download_link |
| id | string | 是 | 记录 ID |
| managed_upload | boolean | 否 | 是否为托管上传文件 |
| package_kind | string | 是 | 完整包或差分包 |
| package_purpose | string | 否 | 包用途:安装或升级; enum=["installer", "upgrade"] 取值:"installer"、"upgrade" |
| platform | string | 是 | 操作系统 |
| size_bytes | integer · int64 | 是 | 文件大小(字节);0 表示未提供; format="int64" |