Argos REST API 完全参考快速掌握 Build 两段式上传协议、签名 S3 URL 与并行分片上传【免费下载链接】argosArgos detects unintended visual changes in your UI, helping teams maintain high product quality as they ship faster.项目地址: https://gitcode.com/gh_mirrors/arg/argosArgos 是一个开源的 UI 视觉回归测试工具帮助团队在快速交付的同时及时发现界面中不预期的视觉变化。它的 REST API 采用经典的「两段式上传协议」处理截图第一次请求创建 Build 并换回签名 S3 URL第二次请求上传截图并确认完成API 还支持并行分片上传把数千张截图拆分到多个 CI 工作节点。本文用最少代码讲透 Argos REST API 的完整调用链路。 什么是 Argos REST APIArgos REST API 是 CI 脚本、SDK 和自定义上传器与 Argos 服务交互的入口。所有接口都基于 OpenAPI 规范定义并直接在服务上以 YAML 形式暴露GET /openapi.yaml可以直接粘到任何 API 调试工具里查看完整字段说明。API 提供三种身份认证方式都通过Authorization: Bearer token请求头传递定义见 security.ts令牌类型适用场景典型端点Project Token项目令牌CI 中创建 Build、上传截图POST /builds、PUT /builds/{id}Personal Access Token个人令牌以用户身份执行审查、评论等操作评论、Review 相关端点OAuth 2.1 访问令牌CLI 与 AI AgentMCP 客户端带projects:read、media:write等 scope 的端点 Build 两段式上传协议如何工作整个 Build 上传流程分为三步这也是 Argos API 设计文档 apps/backend/src/api/README.md 中描述的核心流程第一步POST /builds 创建 Build 并获取签名上传地址客户端把截图文件的 SHA-256 摘要key和当前 commit、分支信息发给POST /builds服务端创建 Build并只为 Argos 尚未持有的文件签发上传目标。响应形如{ build: { id: ..., number: 42, status: in-progress }, screenshots: [ { key: sha256, postUrl: https://...s3..., fields: { key: ..., policy: ... } } ] }请求体支持的关键字段完整 Zod 校验见 createBuild.tscommit、branch必填构建所在的提交与分支screenshots新式上传每项包含keySHA-256与contentTypescreenshotKeys旧式兼容字段仅传 key 数组parallelparallelNonce开启并行分片上传的开关下文详述referenceCommit/referenceBranch指定作为基线的参考提交或分支。服务端用 Redis 锁 externalId查重保证同一parallelNonce的重复创建请求是幂等的若 Build 已定稿则返回409 Conflict。第二步把截图直接上传到签名 S3 URL拿到上传目标后客户端绕过 Argos 服务、直传对象存储网络流量不经过 API 服务新式把fields中的每个键值对作为表单字段先于file字段以multipart/form-dataPOST 到postUrl旧式直接 PUT 二进制到putUrl已标记 deprecated仅兼容老客户端。第三步PUT /builds/{buildId} 推送截图清单并定稿上传完成后客户端调用PUT /builds/{buildId}提交截图清单每项含key与name测试名。服务端校验文件确实存在于存储中然后标记 Build 完成并触发像素比对。该接口对重试是幂等的重复请求若所有截图都已入库会直接返回 Build 而不是报错见 updateBuild.ts。手动定稿并行分片POST /builds/finalize当某个分片因超时等原因无法正常收尾时可显式调用POST /builds/finalize并传入parallelNonce服务端会把该 nonce 下所有并行分片一次性标记为完成随后开始聚合比对实现见 finalizeBuilds.ts。 签名 S3 URL 详解postUrl 与 fields 的优势新式上传使用 AWS 预签名 POST 策略createPresignedPost每个策略里嵌入了两条由 S3 在上传时强制执行的 Condition源码见 createBuild.tscontent-length-range请求体大小必须在[1, 50MB]之间——单文件 50MB 上限由存储层直接兜底eq $Content-Type上传时必须携带与创建 Build 时声明完全一致的 Content-Type杜绝登记为图片、实际传别的东西的注入风险。签名有效期为30 分钟过期后需重新调用POST /builds。相比旧式putUrl预签名 POST 把大小与类型约束写进了签名本身即使 URL 泄露也无法被用来上传超大文件或篡改内容类型。⚡ 并行分片上传parallelNonce、parallelTotal 与 parallelIndex单个非并行 Build 最多注册5000 张截图。更大的测试套件请开启并行模式并行模式的使用规则createBuild.ts 与 updateBuild.ts每个 worker 调用POST /builds时必须传parallel: true和唯一的parallelNonce同一 CI 流水线各 worker 共享该 nonce每个 worker 上传完自己那批截图后调用PUT /builds/{buildId}并携带parallelTotal分片总数各分片必须一致否则400parallelIndex当前分片序号final该分片是否还有后续请求默认true服务端每收到一个完整分片就把batchCount 1当batchCount parallelTotal时自动定稿整个 Build 并触发比对若个别分片丢失或超时用POST /builds/finalize兜底强制收尾。单个分片内部若截图过多装不进一个请求也可以把final设为false连续多次PUT只在最后一批传final: true。 Argos REST API 端点速查表端点方法作用认证/buildsPOST创建 Build返回签名上传目标Project Token/builds/{buildId}PUT推送截图清单、更新元数据、定稿Project Token/builds/finalizePOST按parallelNonce手动定稿并行分片Project Token/projects/{owner}/{project}/builds/{buildNumber}GET按构建号查询 Build 状态见 getBuild.ts三种令牌均可/mediaPOST注册独立图片/视频返回上传目标Project Token / PAT / OAuth/media/{mediaId}/finalizePOST确认媒体字节已落盘见 media.tsProject Token / PAT / OAuth/openapi.yamlGET完整 OpenAPI 规范公开无需认证⚠️ 常见限制与错误码速览限制 / 场景数值 / 行为单个上传文件大小≤ 50MBS3 策略强制单个非并行 Build 的截图数≤ 5000超出请改用并行模式签名 URL 有效期30 分钟400参数缺失或冲突如parallel: true却未传parallelNonce401/403令牌类型不对或权限不足如项目令牌访问了用户端点404资源不存在越权查询也刻意返回 404 以防枚举409Build 已定稿后再次推送 / 分片冲突️ 去哪里看完整规范与源码运行时 OpenAPI 文档GET /openapi.yaml路由注册见 index.tsAPI 整体设计说明apps/backend/src/api/README.mdBuild 创建与签名 URL 签发createBuild.ts分片定稿与幂等重试逻辑updateBuild.ts、finalizeBuilds.ts认证方案定义security.ts独立媒体图片/视频上传协议media.ts。掌握「创建 Build → 签名上传 → 定稿比对」这条两段式主链路再加上parallelNonce/parallelTotal/parallelIndex三个并行参数你就拥有了对接 Argos REST API 所需的全部知识——无论是写 CI 脚本还是自研上传器都能快速跑通 【免费下载链接】argosArgos detects unintended visual changes in your UI, helping teams maintain high product quality as they ship faster.项目地址: https://gitcode.com/gh_mirrors/arg/argos创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考