GET/api/v1/admin/versions
管理员Cookie/HTTPS/JWE,ADMIN_VERSIONS_READJSON 响应接入指南 ↗

查询App版本列表

请求参数

OWNER与VIEWER可读。所有请求发送八项公共头,固定admin/web/admin_web;身份使用独立Secure HttpOnly Cookie,不接受App Bearer。必须HTTPS与真实JWE,GET使用X-Budyoo-JWE携带信封。请求由后台安全协议封装,不通过地址栏直接读取。

无业务请求体。查询参数均可省略:channel(九渠道代码)、platform(android/ios)、region(domestic/overseas/global)、status(PUBLISHED/WITHDRAWN)及versionName默认空串表示全部;page为1–100000整数默认1,pageSize为1–100整数默认20。DRAFT已不再支持,传入返回400 INVALID_APP_VERSION。组合无匹配返回空列表;按createdAt、id倒序,不接收自定义SQL或排序字段。

versionName使用完整三段数字精确匹配,例如1.0.0;每段1–4位,不带前导零、v前缀、预发布或构建后缀。未传或空串保持原查询;其他格式返回400/INVALID_APP_VERSION。该条件与平台、地区、渠道、状态按AND组合,在分页前执行,items与total使用同一筛选。可通过版本号候选取得可选版本,不从当前列表页推断候选。

请求示例

以下使用后台已有统一request封装(自动带语言、八项元数据、Cookie、CSRF及JWE)。UUID、下载地址和版本均为合成示例,不能直接作为实际发布内容。

await request("versions", "GET", undefined, {versionName:"1.0.0", platform:"android", page:1, pageSize:20});

成功响应

HTTP200,Cache-Control:no-store;JWE认证解密后的正文示例:

{
  "code": "SUCCESS",
  "message": "操作成功。",
  "data": {
    "items": [
      {
        "id": "11111111-1111-4111-8111-111111111111",
        "channel": "xiaomi",
        "versionName": "1.0.0",
        "buildNumber": 140,
        "minimumVersion": "1.0.0",
        "forceUpdate": false,
        "packageSizeBytes": 25165824,
        "downloadUrl": "https://downloads.example.test/budyoo-1.0.0.apk",
        "releaseNotes": {
          "zh-CN": "修复已知问题",
          "en": "Fix known issues",
          "ja": "既知の問題を修正",
          "ko": "알려진 문제 수정"
        },
        "platform": "android",
        "region": "domestic",
        "status": "PUBLISHED",
        "version": 0,
        "createdAt": "2026-11-03T12:00:00Z",
        "updatedAt": "2026-11-03T12:00:00Z",
        "publishedAt": "2026-11-03T12:00:00Z"
      }
    ],
    "total": 1,
    "page": 1,
    "pageSize": 20
  },
  "errors": []
}

data.items为版本对象数组,字段与版本详情一致;total为匹配总数(integer int64),page/pageSize为当前分页整数。列表和总数共用同一读取快照,空结果items=[]、total=0。

失败响应

HTTP code 原因
400 INVALID_CLIENT_HEADERS 公共头缺失、重复或格式非法
400 INVALID_APP_VERSION/BAD_REQUEST 渠道、筛选值或分页格式/范围非法
401 UNAUTHORIZED 缺少或失效的管理员Cookie,或使用App Bearer
403 FORBIDDEN/ADMIN_CSRF_INVALID 角色无权限、客户端类型或来源/CSRF非法
426 HTTPS_REQUIRED 未使用HTTPS
503 SERVICE_UNAVAILABLE 数据库、Redis或审计存储暂不可用

加密失败沿用公共加密错误码,提示支持四语,code不翻译。示例:

{"code":"INVALID_APP_VERSION","message":"版本字段、发行渠道或下载地址不合法。","data":null,"errors":[]}

接入说明

苹果渠道app_store的region现为global(全球),国内Android仍domestic,Google Play仍overseas;后台类型、分组、筛选需支持global。苹果不拆成两条发布渠道,原UUID/构建及发布状态保持,展示分类从同一渠道清单派生,无数据库迁移。

版本号精确匹配及组合筛选、同快照分页保持;选择、清空或重置条件回第一页,版本候选仍使用names接口。

创建版本成功即发布,原子替换同渠道旧目标;校验、创建、旧目标停用和管理员审计同事务,任一步失败全部回滚。曾发布构建号必须严格递增,展示版本不能倒退。所有记录只读;停用后不自动恢复旧版本,也不提供编辑、删除或再次发布入口。

状态只有PUBLISHED(当前发布)和WITHDRAWN(停用、被替换或迁移保留的未生效历史)。V18将旧DRAFT原内容及UUID保留为WITHDRAWN,publishedAt仍为null,绝不自动发布占位地址;这些从未发布的历史不占用真实发布构建号。新建成功的publishedAt必有值,version初始为0。

App继续使用升级检查的原请求和返回字段,无需改代码。下载链接的可用性、包签名和商店状态仍须管理员确认;本接口不上传安装包、不代替商店提交或安装。

2026-11-04最终381项服务器Java回归全部通过(0失败/0跳过),包含24项版本管理、筛选、App升级与迁移用例;服务器TypeScript/Vite及7项环境/归档检查通过。验证覆盖创建即发布、旧页面缺少publish=true拒绝、历史保留、并发创建、旧快照停用、发布/替换审计回滚、升级兼容及V17→V18迁移。116份MD链接和141段JSON示例检查通过。API、V18与新版网页已配套部署。候选产物的12项真实浏览器加密夹具检查覆盖立即发布/替换/停用、确认取消、重复提交保护、只读角色、409及响应丢失后完整内容核对,实际渠道写请求0;另13项四语桌面/手机、渠道预览、强更、筛选和重置检查通过。发布前备份在独立数据库恢复验证,运行库迁移后原九条记录UUID与业务内容保持,全部为WITHDRAWN/publishedAt=null且当前发布为0。超时先点击“核对发布结果”查询渠道/构建号及完整内容,核对失败保留输入,不自动重试创建。