Jenkins REST API 保姆级使用教程：从入门到实战（附常见问题解决）
前言
Jenkins 作为最流行的开源持续集成与持续交付（CI/CD）工具之一，不仅提供了强大的 Web UI，还支持通过 REST API 实现自动化操作。无论是触发构建、获取构建状态，还是管理插件和用户权限，REST API 都能让你将 Jenkins 深度集成到自己的系统中。
本文将手把手带你掌握 Jenkins REST API 的核心用法，并提供实用示例和常见问题解决方案，助你轻松实现 Jenkins 自动化！
一、什么是 Jenkins REST API？
Jenkins 提供了一套基于 HTTP 协议的 RESTful 接口，允许外部程序以编程方式与其交互。通过这些接口，你可以：
- 触发或取消构建任务
- 获取 Job 和 Build 的详细信息
- 创建、更新或删除 Job
- 管理节点（Agent）
- 查询系统信息（如插件、版本等）
所有操作均通过标准 HTTP 方法（GET、POST、PUT、DELETE）完成，返回格式通常为 JSON 或 XML（默认为 XML，但可指定 Accept 头切换为 JSON）。
二、启用 Jenkins REST API
1. 确保 Jenkins 已启用远程访问
Jenkins 默认开启 REST API，但需注意以下几点：
- 安全设置：若启用了“全局安全配置”中的“登录认证”，则必须提供有效凭证。
- CSRF 保护：Jenkins 默认启用防止跨站请求伪造（CSRF），调用修改类 API（如 POST/DELETE）时需携带 Crumb。
2. 获取 API Token（推荐方式）
为避免使用明文密码，建议为用户生成 API Token：
- 登录 Jenkins → 点击右上角用户名 →Configure
- 滚动到API Token区域 → 点击Add new Token
- 输入描述（如
my-script-token）→ 点击Generate - 复制并保存 Token（仅显示一次！）
注意：Token 具有与密码相同的权限，请妥善保管。
三、基础 API 使用方法
1. 查看 API 文档
Jenkins 自带 API 文档。在任意页面 URL 后加上/api/即可查看，例如：
http://your-jenkins/job/my-job/api/添加?pretty=true可美化输出：
http://your-jenkins/api/json?pretty=true2. 常用 API 端点速查
| 功能 | URL 示例 | 方法 |
|---|---|---|
| 获取所有 Job 列表 | /api/json | GET |
| 获取某个 Job 信息 | /job/MyJob/api/json | GET |
| 触发构建 | /job/MyJob/build | POST |
| 触发带参数构建 | /job/MyJob/buildWithParameters | POST |
| 获取某次构建详情 | /job/MyJob/123/api/json | GET |
| 删除 Job | /job/MyJob/doDelete | POST |
| 获取系统信息 | /systemInfo/api/json | GET |
所有路径均相对于 Jenkins 根路径（如
http://localhost:8080）
四、实战示例（含代码）
示例 1：使用 curl 触发无参构建
# 替换 YOUR_JENKINS_URL、USERNAME、API_TOKEN、JOB_NAMEcurl-X POST\http://YOUR_JENKINS_URL/job/JOB_NAME/build\--user USERNAME:API_TOKEN示例 2：触发带参数的构建
curl-X POST\"http://YOUR_JENKINS_URL/job/JOB_NAME/buildWithParams?BRANCH=main&ENV=prod"\--user USERNAME:API_TOKEN参数通过 URL Query String 传递（适用于简单参数）。复杂参数建议使用 POST 表单。
示例 3：使用 Python 调用 API（推荐 requests 库）
importrequestsimportjson JENKINS_URL="http://your-jenkins"USERNAME="admin"API_TOKEN="your-api-token"JOB_NAME="my-app-build"# 获取 Crumb（用于 CSRF 防护）auth=(USERNAME,API_TOKEN)crumb_url=f"{JENKINS_URL}/crumbIssuer/api/json"crumb_resp=requests.get(crumb_url,auth=auth)crumb=crumb_resp.json()['crumb']# 触发带参数构建build_url=f"{JENKINS_URL}/job/{JOB_NAME}/buildWithParameters"params={"BRANCH":"develop","DEPLOY_ENV":"staging"}headers={"Jenkins-Crumb":crumb}response=requests.post(build_url,params=params,auth=auth,headers=headers)ifresponse.status_code==201:print("构建已成功触发！")else:print(f"失败：{response.status_code}-{response.text}")示例 4：获取最近一次构建状态
resp=requests.get(f"{JENKINS_URL}/job/{JOB_NAME}/lastBuild/api/json",auth=auth)build_info=resp.json()print(f"构建 #{build_info['number']}状态:{build_info['result']}")五、常见问题及解决办法（重点章节）
在实际使用 Jenkins REST API 时，开发者常遇到以下问题。本节提供针对性解决方案。
问题 1：403 Forbidden 错误
现象：调用 API 返回403 No valid crumb was included in the request。
原因：Jenkins 启用了 CSRF 保护，但请求未携带有效的 Crumb。
解决：
- 先调用
/crumbIssuer/api/json获取 Crumb； - 在后续 POST/DELETE 请求头中添加
Jenkins-Crumb: <crumb值>。
示例见上文 Python 代码。
问题 2：401 Unauthorized
现象：返回401 Invalid password/token for user。
排查步骤：
- 确认用户名拼写正确；
- 确认使用的是API Token而非登录密码（尤其在启用了“API Token only”策略时）；
- 检查 Jenkins 用户是否具有对应 Job 的权限（如“Build”权限）。
建议：在 Jenkins 中为自动化脚本创建专用账号，并分配最小必要权限。
问题 3：返回 XML 而非 JSON
现象：即使请求了/api/json，仍返回 XML。
原因：某些旧版本 Jenkins 或特定插件可能忽略 Accept 头。
解决：
- 显式添加请求头：
Accept: application/json - 或在 URL 后加
?tree=...来定制返回字段（推荐）
curl-H"Accept: application/json"\http://jenkins/job/myjob/api/json?pretty=true\--user user:token问题 4：带参数构建不生效
现象：调用buildWithParameters后，参数未传入 Job。
原因：
- Job 未配置为“参数化构建”；
- 参数名大小写不匹配；
- 使用了错误的 Content-Type（如 multipart/form-data 但未正确构造表单）。
解决：
- 确保 Job 设置中勾选了This project is parameterized；
- 优先使用URL Query String 方式传参（简单可靠）；
- 若必须用 POST body，设置
Content-Type: application/x-www-form-urlencoded并用data=传递参数。
问题 5：无法删除 Job（405 Method Not Allowed）
现象：尝试 DELETE/job/name返回 405。
原因：Jenkins 不支持标准 DELETE 方法删除 Job。
正确做法：
使用 POST 请求访问/job/NAME/doDelete：
curl-X POST\http://jenkins/job/myjob/doDelete\--user user:token\-H"Jenkins-Crumb:$(crumb)"六、最佳实践建议
- 使用 API Token 而非密码：更安全，可单独吊销。
- 缓存 Crumb：Crumb 通常在会话有效期内可复用，无需每次请求都获取。
- 限制权限：为自动化脚本创建专用 Jenkins 用户，仅授予必要权限。
- 处理重试与超时：网络波动可能导致请求失败，建议加入重试机制。
- 日志记录：记录 API 调用结果，便于排查问题。
七、结语
掌握 Jenkins REST API，意味着你拥有了将 CI/CD 流程深度自动化的钥匙。无论是与 GitLab/GitHub 集成、自研运维平台对接，还是实现智能监控告警，REST API 都是不可或缺的桥梁。
参考资料：
- Jenkins 官方 API 文档
- Jenkins Crumb Issuer 说明