60 lines
2.0 KiB
Markdown
60 lines
2.0 KiB
Markdown
# Raw API 批处理
|
||
|
||
当某个 GitLink OpenAPI 尚未封装为 shortcut，但需要重复执行多步请求时，可以使用 `api --batch-file` 读取 JSON 计划文件。批处理会复用 gitlink-cli 的认证、base_url、输出格式和错误处理，并返回结构化汇总。
|
||
|
||
## 示例
|
||
|
||
```json
|
||
{
|
||
"vars": {
|
||
"owner": "Gitlink",
|
||
"repo": "gitlink-cli",
|
||
"issue": "123"
|
||
},
|
||
"requests": [
|
||
{
|
||
"name": "list-open-issues",
|
||
"method": "GET",
|
||
"path": "/v1/{{owner}}/{{repo}}/issues",
|
||
"query": {
|
||
"state": "open",
|
||
"limit": 20
|
||
}
|
||
},
|
||
{
|
||
"name": "comment-issue",
|
||
"method": "POST",
|
||
"path": "/v1/{{owner}}/{{repo}}/issues/{{issue}}/journals",
|
||
"body": {
|
||
"notes": "批处理自动评论"
|
||
}
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
```bash
|
||
gitlink-cli api --batch-file plan.json --dry-run
|
||
gitlink-cli api --batch-file plan.json --var issue=456
|
||
gitlink-cli api --batch-file plan.json --continue-on-error --format json
|
||
```
|
||
|
||
## 字段
|
||
|
||
| 字段 | 必填 | 说明 |
|
||
|------|------|------|
|
||
| `vars` | 否 | 模板变量，支持在 name/path/query/body 字符串中使用 `{{name}}` |
|
||
| `requests` | 是 | 请求数组，至少包含一个请求 |
|
||
| `requests[].name` | 否 | 步骤名称，会出现在结果汇总中 |
|
||
| `requests[].method` | 是 | HTTP 方法，如 GET、POST、PUT、PATCH、DELETE |
|
||
| `requests[].path` | 是 | API 路径，可省略开头的 `/` |
|
||
| `requests[].query` | 否 | 查询参数对象，值可为字符串、数字、布尔值或数组 |
|
||
| `requests[].body` | 否 | JSON 请求体，字符串字段会做模板替换 |
|
||
|
||
## 注意事项
|
||
|
||
- 默认遇到失败会停止；需要继续执行后续步骤时传 `--continue-on-error`。
|
||
- 写入类操作先用 `--dry-run` 检查渲染后的路径、query 和 body。
|
||
- `--var key=value` 可重复传入，并覆盖计划文件里的同名变量，适合在不同仓库或 Issue 上复用同一计划。
|
||
- 批处理模式不能和单次请求的 `--body`、`--body-file`、`--body-stdin`、`--query`、`--header` 混用。
|