Jenkins API使用

Jenkins API使用

介绍

Jenkins API 是一个强大的接口，允许开发者通过编程方式与 Jenkins 服务器交互，实现自动化任务、获取构建信息、管理作业和插件等。无论是初学者还是高级用户，都可以利用 Jenkins API 扩展 Jenkins 的功能或集成到其他系统中。

Jenkins 提供多种 API 访问方式，包括：

• **REST API**：通过 HTTP 请求与 Jenkins 交互。
• **Java API**：用于插件开发或直接操作 Jenkins 核心功能。
• **Groovy 脚本**：通过 Jenkins 脚本控制台执行。

本文将重点介绍 REST API 和 Java API 的使用方法，并提供实际案例。

REST API 基础

Jenkins 的 REST API 使用 HTTP 协议，支持 JSON 或 XML 格式的响应。API 的根路径通常是： http://your-jenkins-server/api

常用端点示例

以下是一些常用的 REST API 端点：

• 获取 Jenkins 基本信息：

 GET /api/json  

• 获取所有作业列表：

 GET /api/json?tree=jobs[name]  

• 触发一个作业构建：

 POST /job/{job-name}/build  

代码示例：使用 cURL 调用 REST API

以下示例展示如何通过 cURL 获取 Jenkins 作业列表：

  
# 获取 Jenkins 作业列表（需替换 JENKINS_URL 和 CRUMB）  
curl -X GET "http://JENKINS_URL/api/json?tree=jobs[name]" \  
     --user username:api_token \  
     -H "Jenkins-Crumb: YOUR_CRUMB"

• • 输出示例：**

  
{  
  "jobs": [  
    {"name": "test-job-1"},  
    {"name": "test-job-2"}  
  ]  
}

认证与安全

Jenkins API 通常需要认证，支持以下方式：

• **Basic Auth**：通过用户名和 API Token 认证。
• **Crumb**：防止 CSRF 攻击的令牌，需先获取。

获取 Crumb 的示例：

  
curl -X GET "http://JENKINS_URL/crumbIssuer/api/json" \  
     --user username:api_token

Java API 开发

Jenkins 的 Java API 主要用于插件开发或直接操作 Jenkins 内部对象。核心类包括：

• Jenkins：访问 Jenkins 实例。
• Job：表示一个 Jenkins 作业。
• Build：表示作业的构建记录。

示例：获取所有作业名称

  
import hudson.model.Job;  
import jenkins.model.Jenkins;  

public class JenkinsApiExample {  
    public static void main(String[] args) {  
        Jenkins jenkins = Jenkins.get();  
        for (Job<?, ?> job : jenkins.getAllItems(Job.class)) {  
            System.out.println("Job Name: " + job.getName());  
        }  
    }  
}

• • 输出示例：**

Job Name: test-job-1 Job Name: test-job-2

触发构建示例

  
import hudson.model.*;  

public class TriggerBuildExample {  
    public static void main(String[] args) throws Exception {  
        Jenkins jenkins = Jenkins.get();  
        Job<?, ?> job = jenkins.getItemByFullName("test-job-1", Job.class);  
        if (job != null) {  
            job.scheduleBuild2(0);  
            System.out.println("Build triggered for " + job.getName());  
        }  
    }  
}

实际案例

案例 1：自动化部署监控

• • 场景**：通过 API 监控所有部署作业的状态，并在失败时发送通知。

• • 步骤**：

1. 使用 REST API 获取所有作业的最近构建状态。 2. 解析返回的 JSON，检查 result 字段。 3. 如果状态为 "FAILURE"，调用通知服务（如 Slack 或邮件）。

案例 2：动态生成作业

• • 场景**：根据 Git 仓库的分支动态创建 Jenkins 作业。

• • 实现**：

1. 使用 Java API 的 Jenkins 和 FreeStyleProject 类。 2. 读取 Git 分支列表，为每个分支创建一个新作业。 3. 配置 SCM 和构建步骤。

高级主题

使用 Jenkins API 分页

对于大型实例，API 响应可能很大。Jenkins 支持分页查询：

  
curl "http://JENKINS_URL/api/json?tree=jobs[name]{0,10}"

（返回前 10 个作业）

使用 Mermaid 绘制 API 流程

以下是一个简单的 API 调用流程：

sequenceDiagram participant Client participant Jenkins Client->>Jenkins: GET /api/json?tree=jobs[name] Jenkins-->>Client: 返回作业列表 Client->>Jenkins: POST /job/test-job/build Jenkins-->>Client: 触发构建

常见问题

1. 如何获取 API Token？

在 Jenkins 用户设置中生成： 1. 点击用户右上角 > 配置。 2. 在 "API Token" 部分生成新 Token。

2. 如何调试 API 请求？

使用工具如 **Postman** 或 **curl -v** 查看详细请求/响应。

总结

Jenkins API 提供了灵活的方式与 Jenkins 交互，适合自动化、集成和扩展开发。本文介绍了 REST API 和 Java API 的基础用法，并提供了实际案例。

下一步建议：

• 阅读 [Jenkins 官方 API 文档](https://www.jenkins.io/doc/book/using/remote-access-api/)。
• 尝试编写一个简单的 Jenkins 插件。