跳到主要内容

Jenkins API 使用

介绍

Jenkins 是一个广泛使用的持续集成和持续交付(CI/CD)工具,它提供了强大的 API 来帮助开发者自动化任务、集成外部工具以及扩展 Jenkins 的功能。Jenkins API 允许你通过 HTTP 请求与 Jenkins 服务器进行交互,从而执行各种操作,如触发构建、获取构建状态、管理作业等。

本文将逐步介绍如何使用 Jenkins API,并提供实际的代码示例和应用场景,帮助你快速上手。

Jenkins API 基础

Jenkins API 主要通过 RESTful 接口提供,支持 JSON 和 XML 格式的响应。你可以使用任何支持 HTTP 请求的编程语言或工具来与 Jenkins API 进行交互。

认证

在访问 Jenkins API 之前,通常需要进行认证。Jenkins 支持多种认证方式,包括基本认证(Basic Authentication)和 API 令牌(API Token)。

基本认证

基本认证是最简单的认证方式,你需要在 HTTP 请求头中添加 Authorization 字段,值为 Basic base64(username:password)

bash
curl -u username:password http://jenkins.example.com/api/json

API 令牌

API 令牌是一种更安全的认证方式。你可以在 Jenkins 的用户设置中生成 API 令牌,然后在请求中使用它。

bash
curl -u username:api_token http://jenkins.example.com/api/json

获取 Jenkins 信息

你可以通过访问 /api/json 端点来获取 Jenkins 的基本信息。

bash
curl -u username:api_token http://jenkins.example.com/api/json

响应将是一个 JSON 对象,包含 Jenkins 的版本、作业列表、视图等信息。

json
{
"assignedLabels": [],
"mode": "NORMAL",
"nodeDescription": "the master Jenkins node",
"nodeName": "",
"numExecutors": 2,
"description": null,
"jobs": [
{
"name": "example-job",
"url": "http://jenkins.example.com/job/example-job/",
"color": "blue"
}
],
"overallLoad": {},
"primaryView": {
"name": "All",
"url": "http://jenkins.example.com/"
},
"quietingDown": false,
"slaveAgentPort": 0,
"unlabeledLoad": {},
"useCrumbs": false,
"useSecurity": true,
"views": [
{
"name": "All",
"url": "http://jenkins.example.com/"
}
]
}

使用 Jenkins API 执行常见操作

触发构建

你可以通过向作业的 build 端点发送 POST 请求来触发构建。

bash
curl -X POST -u username:api_token http://jenkins.example.com/job/example-job/build

如果你想传递参数给构建,可以使用 buildWithParameters 端点。

bash
curl -X POST -u username:api_token http://jenkins.example.com/job/example-job/buildWithParameters \
--data-urlencode "param1=value1" \
--data-urlencode "param2=value2"

获取构建状态

你可以通过访问作业的 lastBuild 端点来获取最近一次构建的状态。

bash
curl -u username:api_token http://jenkins.example.com/job/example-job/lastBuild/api/json

响应将包含构建的状态、持续时间、结果等信息。

json
{
"building": false,
"description": null,
"displayName": "#1",
"duration": 12345,
"estimatedDuration": 12345,
"fullDisplayName": "example-job #1",
"id": "1",
"result": "SUCCESS",
"timestamp": 1633072800000,
"url": "http://jenkins.example.com/job/example-job/1/"
}

管理作业

你可以使用 API 来创建、更新或删除作业。例如,创建一个新的作业:

bash
curl -X POST -u username:api_token http://jenkins.example.com/createItem?name=new-job \
--data-binary @config.xml \
-H "Content-Type: application/xml"

其中 config.xml 是作业的配置文件。

实际案例

自动化部署

假设你有一个 Jenkins 作业用于部署应用程序。你可以编写一个脚本,使用 Jenkins API 在代码提交后自动触发部署。

bash
#!/bin/bash

# 触发部署作业
curl -X POST -u username:api_token http://jenkins.example.com/job/deploy-job/buildWithParameters \
--data-urlencode "branch=main" \
--data-urlencode "environment=production"

# 等待构建完成
while true; do
status=$(curl -s -u username:api_token http://jenkins.example.com/job/deploy-job/lastBuild/api/json | jq -r .result)
if [ "$status" != "null" ]; then
echo "Build finished with status: $status"
break
fi
sleep 10
done

集成外部监控工具

你可以使用 Jenkins API 将构建状态集成到外部监控工具中。例如,将构建状态发送到 Slack:

bash
#!/bin/bash

# 获取构建状态
status=$(curl -s -u username:api_token http://jenkins.example.com/job/example-job/lastBuild/api/json | jq -r .result)

# 发送到 Slack
curl -X POST -H 'Content-type: application/json' \
--data "{\"text\":\"Build status: $status\"}" \
https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX

总结

Jenkins API 是一个强大的工具,可以帮助你自动化任务、集成外部工具以及扩展 Jenkins 的功能。通过本文的介绍,你应该已经掌握了如何使用 Jenkins API 来触发构建、获取构建状态以及管理作业。

附加资源

练习

  1. 使用 Jenkins API 触发一个带参数的构建,并获取构建状态。
  2. 编写一个脚本,将 Jenkins 构建状态发送到你的电子邮件。
  3. 使用 Jenkins API 创建一个新的作业,并配置其构建步骤。

通过完成这些练习,你将更深入地理解 Jenkins API 的使用,并能够在实际项目中应用这些知识。