UAT REST API 和发布关卡

开始之前

您需要准备

工作区中的 Connections 模块：Team、Business、Partner 和 Enterprise 套餐已包含，Project 套餐可通过附加组件 Integrations for one UAT 获得。
UAT Studio 项目中的管理员权限。
能发送 HTTPS 请求的工具：脚本、您的 CI 流水线、Postman 或集成平台。

使用 Zapier 或 Make？那您无需自己调用 API：请参阅 Zapier 和 Make。

设置 · 每个项目一次

连接您的工具

创建 API 密钥

登录 app.uat.studio，打开项目并前往 Setup。
在 API keys 卡片中输入名称，例如 Release pipeline，然后点击 Create API key。
点击 Copy。UAT Studio 只显示一次密钥。请将其作为机密保存在您的工具中，例如 UAT_STUDIO_KEY。

发起调用

每个请求都要附带密钥，格式为 Authorization: Bearer、一个空格，再加上密钥。例如，获取最新的问题：

curl -H "Authorization: Bearer $UAT_STUDIO_KEY" "https://app.uat.studio/api/v1/issues?order=created&limit=10"

新建问题，请求正文为 JSON：

curl -X POST "https://app.uat.studio/api/v1/issues" \
  -H "Authorization: Bearer $UAT_STUDIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Save fails on a new quote", "severity": "High", "test_number": 12}'

响应为 JSON。每个问题都附带编号（ISS-012）、标题、描述、严重程度、优先级、状态、负责人、测试和发现该问题的测试人员、Jira 或 Azure DevOps 中的工单，以及指向 UAT Studio 的链接。

可用内容 · https://app.uat.studio/api/v1

API 地址

类型	请求	作用
读取	`GET /me`	密钥所属的项目。
读取	`GET /issues?order=created`	最新的问题。`order=updated`：最近修改的问题。还支持 `since`（日期和时间）、`status` 和 `limit`（最多 100）。
读取	`GET /issues/ISS-012`	单个问题，包括其相关步骤和历史记录。
创建	`POST /issues`	新问题：`title`，可选 `description`、`severity`、`priority`、`test_number`、`step_number`、`assignee`、`record_url`。没有 `test_number` 时（可用 `group` 指定负责测试的分组），问题在被设为“待复测”时会获得自己的测试用例。
修改	`PATCH /issues/ISS-012`	`status`、`severity`、`assignee` 或 `record_url`，可选附带 `comment`。将没有测试用例的问题的 `status` 设为 `Ready for retest` 时，会创建其测试用例；此时响应中包含 `"test_case": "created"`。
修改	`POST /issues/ISS-012/comments`	历史记录中的一条 `comment`。
读取	`GET /cases`	测试用例及其步骤，以及 Pass、Fail 等各类结果的数量。还支持 `epic`、`since` 和 `limit`（最多 1,000）。
创建	`POST /cases`	测试用例：`title`、`steps`（由 `action`、`expected` 和可选的 `data` 组成的列表），以及可选的 `external_id`、`epic`、`group`、`links`、`priority`（Must、Should 或 Could）和 `risk`（High、Medium 或 Low）。再次发送相同的 `external_id` 即可更新；位置不变的步骤会保留其结果。
创建	`POST /testers`	测试人员：`name`，可选 `email` 和 `group`。邀请从 Setup 发送。
读取	`GET /signoffs`	签核记录，最新的在前。
读取	`GET /groups`	项目的分组。
读取	`GET /status`	某个版本的 go 或 no-go：见下文。

用于您的流水线

发布关卡：业务方签核后再部署

GET /status 返回一个 decision：当前轮次已签核且没有未解决的 Critical 问题时为 go；签核被拒绝或存在未解决的 Critical 问题时为 no-go；尚未决定时为 open。使用 ?gate=1 时，除 go 外的所有结果都返回 HTTP 409，使流水线中的该步骤失败。

- name: UAT signed off?
  run: curl --fail-with-body -sS -H "Authorization: Bearer ${{ secrets.UAT_STUDIO_KEY }}" "https://app.uat.studio/api/v1/status?gate=1"

为流水线使用单独的密钥，以便单独撤销。

出现问题时

响应及处理方法

响应	处理方法
401：API 密钥无效	密钥已被撤销或输入有误。请在 Setup › API keys 下创建新密钥。
403：套餐不包含此功能，或为只读	该工作区没有 Connections 模块，或其套餐已到期。只读状态下仍可读取。
404：不存在问题 ISS-…	该密钥属于另一个项目，或者问题已被合并。
400：某个字段不正确	提示信息会指出是哪个字段，例如不存在的严重程度。
使用 `?gate=1` 时返回 409	该版本暂不能发布：响应中包含原因。

安全

密钥如何保持安全

一个密钥只能访问一个项目，无法访问工作区中的其他任何内容。
UAT Studio 只存储密钥的指纹，从不存储密钥本身。Setup 中会显示最后四个字符和最近使用时间。
在 Setup 中点击 Revoke 可立即停用密钥。
通过密钥创建或修改的每个问题或测试人员都会显示在问题历史记录和审计日志中，并注明密钥名称。
切勿将密钥放入邮件、聊天或代码中；请将其作为机密保存在您的工具中。

UAT Studio REST API