REST API 访问权限

teamcity api 命令可让你直接在命令行对 TeamCity REST API 发起认证 HTTP 请求。这对于访问尚未由专用 CLI 命令覆盖的 API 端点、编写自定义脚本和调试很有用。

基本用法

端点实参是 URL 的路径部分，以 /app/rest/ 开头：

teamcity api '/app/rest/server'

CLI 会根据当前的认证上下文自动添加基础 URL 和认证页眉。

HTTP 方法

默认情况下，请求使用 GET 方法。如需使用其他方法，请用 -X 指定：

# GET (default)
teamcity api '/app/rest/projects'

# POST
teamcity api '/app/rest/buildQueue' -X POST -f 'buildType=id:MyBuild'

# PUT
teamcity api '/app/rest/builds/12345/comment' -X PUT --input comment.txt

# DELETE
teamcity api '/app/rest/builds/12345/tags/obsolete' -X DELETE

  

发送数据

JSON 字段

使用 -f 通过键值对构建 JSON 请求体：

teamcity api '/app/rest/buildQueue' -X POST -f 'buildType=id:MyBuild'
teamcity api '/app/rest/buildQueue' -X POST -f 'buildType=id:MyBuild' -f 'branchName=main'

从文件读取请求体

使用 --input 从文件读取请求体：

teamcity api '/app/rest/projects' -X POST --input project.json

使用 --input - 从 stdin 读取：

echo '{"name": "New Project"}' | teamcity api '/app/rest/projects' -X POST --input -

   

自定义页眉

使用 -H 添加自定义页眉：

teamcity api '/app/rest/builds' -H "Accept: application/xml"

响应处理

包含响应页眉

teamcity api '/app/rest/server' -i

原始输出

输出未进行格式设置的响应：

teamcity api '/app/rest/server' --raw

静默模式

在成功时抑制输出（在只关心退出码的脚本中很有用）：

teamcity api '/app/rest/builds/12345/tags/release' -X POST --silent

TeamCity REST API 对大型集合返回分页结果。使用 --paginate 自动获取所有页面：

teamcity api '/app/rest/builds' --paginate

使用 --slurp 将分页结果合并为单个 JSON 数组：

teamcity api '/app/rest/builds' --paginate --slurp

示例

# Get current user info
teamcity api '/app/rest/users/current'

# List all VCS roots
teamcity api '/app/rest/vcs-roots'

# Get build statistics
teamcity api '/app/rest/builds/12345/statistics'

# Trigger a build with parameters
teamcity api '/app/rest/buildQueue' -X POST \
  --input <(echo '{"buildType":{"id":"MyBuild"},"properties":{"property":[{"name":"version","value":"1.0"}]}}')

# Download a specific artifact
teamcity api '/app/rest/builds/12345/artifacts/content/report.html' --raw > report.html

  

api flags

标志	描述
`-X`， `--method`	HTTP 方法（GET、POST、PUT、DELETE、PATCH）。默认值：GET。
`-f`， `--field`	添加一个正文字段，格式为 `key=value`。构建一个 JSON 对象。可以重复。
`-H`， `--header`	添加自定义页眉。可以重复。
`--input`	从文件读取请求体。对于 stdin，请使用 `-`。
`-i`， `--include`	在输出中包含响应页眉
`--raw`	输出未进行格式设置的原始响应
`--silent`	成功时抑制输出
`--paginate`	自动获取所有页面
`--slurp`	将分页结果合并为 JSON 数组（需要 `--paginate`）

2026年 8月 6日