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：

1. 登录 Jenkins → 点击右上角用户名 →Configure
2. 滚动到API Token区域 → 点击Add new Token
3. 输入描述（如my-script-token）→ 点击Generate
4. 复制并保存 Token（仅显示一次！）

注意：Token 具有与密码相同的权限，请妥善保管。

三、基础 API 使用方法

1. 查看 API 文档

Jenkins 自带 API 文档。在任意页面 URL 后加上/api/即可查看，例如：

http://your-jenkins/job/my-job/api/

添加?pretty=true可美化输出：

http://your-jenkins/api/json?pretty=true

2. 常用 API 端点速查

所有路径均相对于 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。

解决：

1. 先调用/crumbIssuer/api/json获取 Crumb；
2. 在后续 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 但未正确构造表单）。

解决：

1. 确保 Job 设置中勾选了This project is parameterized；
2. 优先使用URL Query String 方式传参（简单可靠）；
3. 若必须用 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)"

六、最佳实践建议

1. 使用 API Token 而非密码：更安全，可单独吊销。
2. 缓存 Crumb：Crumb 通常在会话有效期内可复用，无需每次请求都获取。
3. 限制权限：为自动化脚本创建专用 Jenkins 用户，仅授予必要权限。
4. 处理重试与超时：网络波动可能导致请求失败，建议加入重试机制。
5. 日志记录：记录 API 调用结果，便于排查问题。

七、结语

掌握 Jenkins REST API，意味着你拥有了将 CI/CD 流程深度自动化的钥匙。无论是与 GitLab/GitHub 集成、自研运维平台对接，还是实现智能监控告警，REST API 都是不可或缺的桥梁。

参考资料：

• Jenkins 官方 API 文档
• Jenkins Crumb Issuer 说明