Skip to main content

查询客户端安装包版本列表

使用具有下列 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。

所需权限

所需权限资源Scope资源服务
客户端安装包(读取)client-downloadsadmin.v1.client-downloads.readqwenwork-biz-service
GET /api/openapi/v1/client-app-versions

公共请求头

适用《通过 API 配置 QwenWork 管理后台》的“认证与请求头”章节:Authorization 必填,X-Request-Id 可选;本查询无需 Idempotency-Key。

请求参数

名称位置类型必填说明示例
pagequeryinteger · int64否页码; format="int64"; minimum=1; maximum=1000000; default=1-
page_sizequeryinteger · int64否每页条数; format="int64"; minimum=1; maximum=100; default=20-
qquerystring否搜索版本或标题; maxLength=200-
platformquerystring否操作系统; enum=["windows", "macos", "linux", "harmony"]-
archquerystring否CPU 架构; enum=["x64", "arm64", "universal64"]-
enabledquerystring否是否启用; enum=["true", "false"]-
idquerystring · uuid否记录 ID; format="uuid"-
typed_onlyqueryboolean否仅返回已有平台归属的版本-
release_statusquerystring否升级发布状态:未发布、发布中、部分发布或全量发布。; enum=["unreleased", "publishing", "partial", "full_released"]-

请求示例

将 <BASE_URL> 替换为企业部署的千问办公 API 服务地址,并填写实际参数。示例中的占位值不能直接用于请求。
curl --request GET \
  --url '<BASE_URL>/api/openapi/v1/client-app-versions' \
  --header 'Authorization: Bearer <API_KEY>'

响应状态表

HTTP 状态码触发条件响应结构引用客户端处理建议
200请求成功见本文“响应结果”读取结果。
default认证、授权、参数校验或依赖错误见《通过 API 配置 QwenWork 管理后台》的“通用错误”结构按 HTTP 状态和 code 处理。

响应结果

Content-Type: application/json
名称类型必填说明示例
itemsarray<object> | null是结果列表-
pageinteger · int64是页码; format="int64"-
page_sizeinteger · int64是每页条数; format="int64"-
totalinteger · int64是符合条件的总数; format="int64"-

items[]

字段类型必填说明
active_task_idstring否尚未结束的升级任务 ID(不包含任务详情)
archstring是CPU 架构
central_minimum_versionstring否中心提供的建议最低版本;存在时返回,不改变升级决策。
created_atstring · date-time是创建时间; format="date-time"
download_platformsarray<string> | null否当前由该记录提供下载安装包的平台;未用于下载时省略,包含历史配置。
download_versionboolean否是否为下载页使用的版本
enabledboolean是是否启用
idstring是记录 ID
is_central_minimumboolean否是否为中心最低版本
minimum_compatible_versionstring否该版本兼容的最低客户端版本;存在时返回,仅供提示。
packagesarray<object> | null是安装包和升级包
platformstring是操作系统
platformsarray<string> | null是支持的操作系统
publish_blocked_reasonstring否不能发布升级的原因;可发布时省略。; enum=["full_released", "not_above_baseline", "no_upgrade_package", "disabled"] 取值:"disabled"、"full_released"、"no_upgrade_package"、"not_above_baseline"
release_notestring是版本更新说明
release_statusstring否升级发布状态:未发布、发布中、部分发布或全量发布。; enum=["unreleased", "publishing", "partial", "full_released"] 取值:"full_released"、"partial"、"publishing"、"unreleased"
titlestring是版本标题
updated_atstring · date-time是更新时间; format="date-time"
versionstring是版本号

items[].packages[]

字段类型必填说明
archstring是CPU 架构
checksum_md5string是MD5 校验值;空值表示未提供
delta_from_versionstring是差分包的基础版本
download_linkstring否可直接下载的链接;托管文件为临时签名链接
download_urlstring是文件地址;列表中托管文件原始地址可能不能直接访问,应使用 download_link
idstring是记录 ID
managed_uploadboolean否是否为托管上传文件
package_kindstring是完整包或差分包
package_purposestring否包用途:安装或升级; enum=["installer", "upgrade"] 取值:"installer"、"upgrade"
platformstring是操作系统
size_bytesinteger · int64是文件大小(字节);0 表示未提供; format="int64"

响应示例

{
  "items": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "platforms": [
        "macos"
      ],
      "platform": "macos",
      "arch": "arm64",
      "version": "1.2.3",
      "title": "Desktop 1.2.3",
      "release_note": "Bug fixes",
      "enabled": true,
      "created_at": "2026-10-26T10:00:00Z",
      "updated_at": "2026-10-26T10:00:00Z",
      "release_status": "unreleased",
      "download_version": true,
      "download_platforms": [
        "macos"
      ],
      "packages": [
        {
          "id": "22222222-2222-4222-8222-222222222222",
          "platform": "macos",
          "arch": "arm64",
          "package_kind": "full",
          "package_purpose": "installer",
          "managed_upload": false,
          "download_url": "https://downloads.example.com/client-1.2.3-arm64.dmg",
          "checksum_md5": "0123456789abcdef0123456789abcdef",
          "size_bytes": 331070458,
          "delta_from_version": ""
        }
      ]
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 20
}

错误处理

401:API Key 无效;403:Scope、企业身份、用户范围或权益不满足;400/422:查询参数不合法;503:依赖不可用。临时故障采用退避重试。 网关可能在请求到达业务服务前以 HTML 返回 401/403;客户端应先检查 HTTP 状态及 Content-Type,再解析 JSON。业务服务错误使用上述公共错误结构。