跳到主要内容

Jenkins 远程API

Jenkins是一个广泛使用的持续集成和持续交付（CI/CD）工具。除了通过Web界面管理任务外，Jenkins还提供了强大的远程API，允许开发者通过编程方式与Jenkins进行交互。本文将详细介绍Jenkins远程API的使用方法，帮助初学者掌握这一高级特性。

什么是Jenkins远程API？​

Jenkins远程API是一组基于HTTP的接口，允许开发者通过HTTP请求与Jenkins服务器进行通信。通过远程API，您可以执行诸如创建任务、触发构建、获取构建状态等操作。这使得Jenkins可以轻松集成到自动化脚本、CI/CD流水线或其他系统中。

Jenkins远程API支持多种数据格式，包括XML、JSON和Python。本文将以JSON格式为例进行讲解。

如何访问Jenkins远程API​

要访问Jenkins远程API，您需要确保Jenkins服务器已启用远程API访问权限。默认情况下，Jenkins远程API是启用的，但您可以通过以下步骤确认：

  1. 登录Jenkins Web界面。
  2. 导航到“系统管理” > “全局安全配置”。
  3. 确保“匿名用户”或“已登录用户”具有“读取”权限。

认证​

Jenkins远程API支持多种认证方式，包括基本认证（Basic Authentication）和API令牌。建议使用API令牌进行认证，以提高安全性。

要生成API令牌：

  1. 登录Jenkins Web界面。
  2. 点击右上角的用户名，选择“配置”。
  3. 在“API令牌”部分，点击“添加新令牌”。

生成令牌后，您可以在HTTP请求中使用它进行认证。

使用Jenkins远程API​

获取Jenkins信息​

首先，让我们通过远程API获取Jenkins的基本信息。以下是一个简单的HTTP GET请求示例：

bash
curl -u username:api_token http://your-jenkins-server/api/json

输入：

  • username: 您的Jenkins用户名。
  • api_token: 您生成的API令牌。
  • http://your-jenkins-server/api/json: Jenkins服务器的API端点。

输出：

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

触发构建​

接下来，我们将通过远程API触发一个Jenkins任务的构建。假设我们有一个名为example-job的任务。

bash
curl -X POST -u username:api_token http://your-jenkins-server/job/example-job/build

输入：

  • -X POST: 使用POST方法触发构建。
  • http://your-jenkins-server/job/example-job/build: 任务的构建端点。

输出： 如果请求成功，Jenkins将返回HTTP状态码201 Created，表示构建已成功触发。

获取构建状态​

要获取某个构建的状态，可以使用以下请求：

bash
curl -u username:api_token http://your-jenkins-server/job/example-job/lastBuild/api/json

输出：

json
{
  "building": false,
  "result": "SUCCESS",
  "timestamp": 1633072800000,
  "duration": 12000,
  "url": "http://your-jenkins-server/job/example-job/1/"
}

实际应用场景​

自动化构建​

假设您有一个持续集成流水线，需要在代码提交后自动触发Jenkins构建。您可以使用Jenkins远程API在Git钩子中触发构建。

bash
curl -X POST -u username:api_token http://your-jenkins-server/job/example-job/build

监控构建状态​

在自动化测试中，您可能需要监控Jenkins构建的状态，以确保所有测试通过。您可以通过定期查询构建状态来实现这一点。

bash
curl -u username:api_token http://your-jenkins-server/job/example-job/lastBuild/api/json

总结​

Jenkins远程API为开发者提供了强大的工具，可以自动化构建、监控和管理Jenkins任务。通过本文的介绍，您应该已经掌握了如何使用Jenkins远程API进行基本操作。接下来，您可以尝试将这些API集成到您的CI/CD流水线中，以提高开发效率。

附加资源​

练习​

  1. 使用Jenkins远程API创建一个新的任务。
  2. 编写一个脚本，定期检查某个任务的构建状态，并在构建失败时发送通知。
提示

在编写脚本时，建议使用Python的requests库来简化HTTP请求的处理。