跳到主要内容

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)。

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

API 令牌​

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

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

获取 Jenkins 信息​

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

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

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

{
  "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 请求来触发构建。

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

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

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

获取构建状态​

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

curl -u username:api_token http://jenkins.example.com/job/example-job/lastBuild/api/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 来创建、更新或删除作业。例如，创建一个新的作业：

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 在代码提交后自动触发部署。

#!/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：

#!/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 的使用，并能够在实际项目中应用这些知识。