持续集成Jenkins Jenkins API的使用（更新中）

Posted 2023-03-06 鮀城小帅

 前言

目前，我们将要上线DevOps系统，面对未来可能需要对系统的二次开发和处于对系统的深入理解，我需要对Jenkins API有个比较熟悉的了解。在DevOps中，jenkins总是作为其中的一环集成到里面，它提供了几种语言的API,可以很方便的进行调用集成。

一.Jenkins Rest API简单介绍

在githup上，jenkins-rest项目地址：jenkins-rest ,接口定义和接口测试代码都可以详细看到。以下是使用REST API的前置条件：

1. 需要运行着的jenkins环境

2. 需要一个管理员权限的账号

3. CSRF功能需要关闭掉，不然会影响接口的请求（在API使用JenkinsClient连接后，基于Jenkins API进行请求是没有问题的，也可以不关闭。我是因为需要通过访问post接口创建凭据，所以需要关闭CSRF功能，不然会403。低版本的jenkins可以在  Configure Global Security功能）

4. 重点：config.xml的创建，通过REST API创建job，则需要动态传入和修改Job对应的config.xml，目前主流未提供完整的config.xml生成工具。根据查询到的资料，大部分人都是用固定的xml字符串去修改后再拼接到一起，来构成所需要的config.xml，这并不规范，而且在多种Job类型的场景下，无法根据任务类型生成所需的config.xml。

这里提供一个博主自己在做的开源项目 xml-jenkins，博主会持续维护Jenkins常用的 config.xml。

二.关闭CSRF保护

高版本jenkins，页面因为无关闭CSRF选项了,需要在Manage Jenkins —>Script Console中手动禁用CSRF.

禁用CSRF，命令如下：

 hudson.security.csrf.GlobalCrumbIssuerConfiguration.DISABLE_CSRF_PROTECTION = true

启用CSRF，命令如下：

  hudson.security.csrf.GlobalCrumbIssuerConfiguration.DISABLE_CSRF_PROTECTION = false

三.Jenkins Rest API使用

1.引入 jenkins-rest.jar 包

引入以下依赖：

 <dependency>
            <groupId>com.cdancy</groupId>
            <artifactId>jenkins-rest</artifactId>
            <version>0.0.28</version>
        </dependency>

        <dependency>
            <groupId>com.google.guava</groupId>
            <artifactId>guava</artifactId>
            <version>28.1-jre</version>
  </dependency>

2.创建客户端

2.1JenkinsClient

@Configuration
public class JenkinsClient 

    @Autowired
    private JenkinsProperties jenkinsProperties;

    @Bean(name = "jenkinsClient")
    @Scope(scopeName = ConfigurableBeanFactory.SCOPE_SINGLETON)
    public JenkinsClient getJenkinsClient() 
        return JenkinsClient.builder()
                .endPoint(jenkinsProperties.getServerUri())
                .credentials(jenkinsProperties.getUsername() + ":" + jenkinsProperties.getPassword())
                .build();
    

2.2JenkinsProperties

@Data 
@Component
@ConfigurationProperties("jenkins")
public class JenkinsProperties 
    private String serverUri;
    private String username;
    private String password;

2.3application.yaml

jenkins:
  # jenkins的访问url
  server-uri: http://127.0.0.1:8080
  username: jenkins
  password: jenkins

3.API介绍   

底层代码：

//
// Source code recreated from a .class file by IntelliJ IDEA
// (powered by FernFlower decompiler)
//

package com.cdancy.jenkins.rest;

import com.cdancy.jenkins.rest.features.ConfigurationAsCodeApi;
import com.cdancy.jenkins.rest.features.CrumbIssuerApi;
import com.cdancy.jenkins.rest.features.JobsApi;
import com.cdancy.jenkins.rest.features.PluginManagerApi;
import com.cdancy.jenkins.rest.features.QueueApi;
import com.cdancy.jenkins.rest.features.StatisticsApi;
import com.cdancy.jenkins.rest.features.SystemApi;
import com.cdancy.jenkins.rest.features.UserApi;
import java.io.Closeable;
import org.jclouds.rest.annotations.Delegate;

public interface JenkinsApi extends Closeable 
    @Delegate
    CrumbIssuerApi crumbIssuerApi();

    @Delegate
    JobsApi jobsApi();

    @Delegate
    PluginManagerApi pluginManagerApi();

    @Delegate
    QueueApi queueApi();

    @Delegate
    StatisticsApi statisticsApi();

    @Delegate
    SystemApi systemApi();

    @Delegate
    ConfigurationAsCodeApi configurationAsCodeApi();

    @Delegate
    UserApi userApi();

由代码可以看出一共提供了6个API类，如下表所示：

API类	说明
pluginManagerApi	插件API：提供插件操作接口，一共就俩方法，查看和安装插件
crumbIssuerApi	系统哈希值信息（用于防御CSRF攻击）
jobsAPi	任务（项目管理），提供任务的创建、修改、查询、删除等操作，主要使用接口
queueApi	任务队列相关
statisticsApi	jenkins统计相关
systemApi	jenkins系统信息，如版本

API 二次封装：

@Component
public class JenkinsTemplate 
    
    @Autowired
    private JenkinsClient jenkinsClient;
    
    /**
     * 任务管理（任务信息、创建、修改）API
     */
    private JobsApi jobsApi;

    /**
     * 插件管理（插件信息、安装插件）API
     */
    private PluginManagerApi pluginManagerApi;
    
    /**
     * 任务队列相关（队列状态）API
     */
    private QueueApi queueApi;
    
    /**
     * Jenkins统计信息 API
     */
    private StatisticsApi statisticsApi;
    
    /**
     * 系统哈希值信息（用于防御CSRF攻击）API
     */
    private CrumbIssuerApi crumbIssuerApi;
    
    /**
     * Jenkins系统状态（版本、路径）API
     */
    private SystemApi systemApi;

    /**
     * jenkins用户信息API
     */
    private UserApi userApi;

    public JenkinsTemplate() 

    

    /**
     * 后置处理，JenkinsTemplate比JenkinsProperties先初始化，所以不能在构造器里获取api
     */
    @PostConstruct
    public void initApi()
        this.jobsApi = jenkinsClient.api().jobsApi();
        this.pluginManagerApi = jenkinsClient.api().pluginManagerApi();
        this.queueApi = jenkinsClient.api().queueApi();
        this.statisticsApi = jenkinsClient.api().statisticsApi();
        this.crumbIssuerApi = jenkinsClient.api().crumbIssuerApi();
        this.systemApi = jenkinsClient.api().systemApi();
    

4.JobsApi-任务API

4.1任务列表查询

    /**
     * @Title: fetchJobInfo   
     * @Description:  任务列表查询   
     * @param: optionalFolderPath  文件夹名称（对应的是 folder 类型的item）
     * @return: JobInfo      
     * @throws
     */
    public JobList getJobInfo(String optionalFolderPath) 
        return jobsApi.jobList(optionalFolderPath);
    

4.2获取任务信息

   /**
     * @Title: fetchJobInfo   
     * @Description:  获取任务信息   
     * @param: optionalFolderPath  文件夹名称（对应的是 folder 类型的item）
     * @param: jobName  任务名
     * @return: JobInfo      
     * @throws
     */
    public JobInfo getJobInfo(String optionalFolderPath, String jobName) 
        
        return jobsApi.jobInfo(optionalFolderPath, jobName);
    

4.3 使用 XML 文件创建任务

    /**
     * @Title: create   
     * @Description: 使用 XML 文件创建任务  
     * @param: @param optionalFolderPath 文件夹名称（对应的是 folder 类型的item）
     * @param: @param jobName 任务名
     * @param: @param configXML  任务配置
     * @param: @return      
     * @return: RequestStatus      
     * @throws
     */
    public RequestStatus createJob(String optionalFolderPath, String jobName, String configXML) 
        return jobsApi.create(optionalFolderPath, jobName, configXML);
    
    

4.4删除任务

   /**
     * @Title: deleteJob   
     * @Description: 删除任务
     * @param: @param optionalFolderPath 文件夹名称（对应的是 folder 类型的item）
     * @param: @param jobName 任务名
     * @param: @param configXML 任务配置
     * @param: @return      
     * @return: RequestStatus      
     * @throws
     */
    public RequestStatus deleteJob(String optionalFolderPath, String jobName, String configXML) 
        return jobsApi.delete(optionalFolderPath, jobName);
    

4.5启用任务

    /**
     * @Title: deleteJob   
     * @Description: 启用任务
     * @param: @param optionalFolderPath 文件夹名称（对应的是 folder 类型的item）
     * @param: @param jobName 任务名
     * @param: @param configXML 任务配置
     * @param: @return      
     * @return: RequestStatus      
     * @throws
     */
    public boolean enableJob(String optionalFolderPath, String jobName, String configXML) 
        return jobsApi.enable(optionalFolderPath, jobName);
    

4.6禁用任务

    /**
     * @Title: disableJob   
     * @Description: 禁用任务 
     * @param: @param optionalFolderPath 文件夹名称（对应的是 folder 类型的item）
     * @param: @param jobName 任务名
     * @param: @param configXML 任务配置
     * @param: @return      
     * @return: boolean      
     * @throws
     */
    public boolean disableJob(String optionalFolderPath, String jobName, String configXML) 
        return jobsApi.disable(optionalFolderPath, jobName);
    

4.7获取任务配置文件内容

    /**
     * @Title: getConfig   
     * @Description: 获取任务配置文件内容
     * @param: @param optionalFolderPath 文件夹名称（对应的是 folder 类型的item）
     * @param: @param jobName 任务名
     * @param: @return      
     * @return: String      
     * @throws
     */
    public String getJobConfig(String optionalFolderPath, String jobName) 
        return jobsApi.config(optionalFolderPath, jobName);
    

4.8更新任务配置文件内容

    /**
     * @Title: updateConfig   
     * @Description: 更新任务配置文件     
     * @param: @param optionalFolderPath 文件夹名称（对应的是 folder 类型的item）
     * @param: @param jobName 任务名
     * @param: @param configXML 任务配置
     * @param: @return      
     * @return: boolean      
     * @throws
     */
    public boolean updateJobConfig(String optionalFolderPath, String jobName, String configXML) 
        return jobsApi.config(optionalFolderPath, jobName, configXML);
    

4.9获取任务描述内容

    /**
     * @Title: getJobDescription   
     * @Description: 获取任务描述内容  
     * @param: @param optionalFolderPath 文件夹名称（对应的是 folder 类型的item）
     * @param: @param jobName 任务名
     * @param: @return      
     * @return: String      
     * @throws
     */
    public String getJobDescription(String optionalFolderPath, String jobName) 
        return jobsApi.description(optionalFolderPath, jobName);
    

4.10设置任务描述内容

    /**
     * @Title: setJobDescription   
     * @Description: 设置任务描述   
     * @param: @param optionalFolderPath 文件夹名称（对应的是 folder 类型的item）
     * @param: @param jobName 任务名 
     * @param: @param configXML 任务配置
     * @param: @return      
     * @return: boolean      
     * @throws
     */
    public boolean setJobDescription(String optionalFolderPath, String jobName, String configXML) 
        return jobsApi.description(optionalFolderPath, jobName, configXML);
    

4.11构建任务

    /**
     * @Title: buildJob   
     * @Description: 构建任务   
     * @param: @param optionalFolderPath 文件夹名称（对应的是 folder 类型的item）
     * @param: @param jobName 任务名
     * @param: @return      
     * @return: IntegerResponse      
     * @throws
     */
    public IntegerResponse buildJob(String optionalFolderPath, String jobName) 
        return jobsApi.build(optionalFolderPath, jobName);
    

4.12构建带参数任务

    /**
     * @Title: buildJobwithParams   
     * @Description: 构建带参数任务   
     * @param: @param optionalFolderPath 文件夹名称（对应的是 folder 类型的item）
     * @param: @param jobName 任务名
     * @param: @param configXML 任务配置
     * @param: @param properties
     * @param: @return      
     * @return: IntegerResponse      
     * @throws
     */
    public IntegerResponse buildJobwithParams(String optionalFolderPath, String jobName, Map<String,List<String>> properties) 
        return jobsApi.buildWithParameters(optionalFolderPath, jobName, properties);
    

4.13获取Job上次构建序号

    /**
     * @Title: lastBuildNumber   
     * @Description: 获取Job上次构建序号  
     * @param: @param optionalFolderPath 文件夹名称（对应的是 folder 类型的item）
     * @param: @param jobName 任务名
     * @param: @return      
     * @return: Integer      
     * @throws
     */
    public Integer getLastBuildNumber(String optionalFolderPath, String jobName) 
        return jobsApi.lastBuildNumber(optionalFolderPath, jobName);
    

4.14 获取Job上次构建时间戳

    /**
     * @Title: getLastBuildTimestamp   
     * @Description: 获取Job上次构建时间戳  
     * @param: @param optionalFolderPath 文件夹名称（对应的是 folder 类型的item）
     * @param: @param jobName 任务名
     * @param: @return      
     * @return: String      
     * @throws
     */
    public String getLastBuildTimestamp(String optionalFolderPath, String jobName) 
        return jobsApi.lastBuildTimestamp(optionalFolderPath, jobName);
    

4.15获取构建信息

    /**
     * @Title: fetchJobInfo   
     * @Description:  获取构建信息   
     * @param: optionalFolderPath 文件夹名称（对应的是 folder 类型的item）
     * @param: jobName 任务名
     * @param: buildNumber 构建序号
     * @return: JobInfo      
     * @throws
     */
    public BuildInfo getBuildInfo(String optionalFolderPath, String jobName, int buildNumber) 
        return jobsApi.buildInfo(optionalFolderPath, jobName, buildNumber);
    

4.16任务构建对应的控制台输出内容

    /**
     * @Title: getLogText   
     * @Description: 任务构建对应的控制台输出内容
     * @param: @param optionalFolderPath 文件夹名称（对应的是 folder 类型的item）
     * @param: @param jobName 任务名
     * @param: @param start
     * @param: @return      
     * @return: ProgressiveText      
     * @throws
     */
    public ProgressiveText getLogText(String optionalFolderPath, String jobName, int start) 
        return jobsApi.progressiveText(optionalFolderPath, jobName, start);
    

4.17 获取指定构建控制台输出

 /**
     * @Title: getLogTextofBuildNumber   
     * @Description: 获取指定构建控制台输出    
     * @param: @param optionalFolderPath 文件夹名称（对应的是 folder 类型的item）
     * @param: @param jobName 任务名
     * @param: @param buildNumber 构建序号
     * @param: @param start
     * @param: @return      
     * @return: ProgressiveText      
     * @throws
     */
    public ProgressiveText getLogTextofBuildNumber(String optionalFolderPath, String jobName, int buildNumber, int start) 
        return jobsApi.progressiveText(optionalFolderPath, jobName, buildNumber, start);
    

4.18 任务重命名

    /**
     * @Title: renameJob   
     * @Description: 任务重命名
     * @param: @param optionalFolderPath 文件夹名称（对应的是 folder 类型的item）
     * @param: @param currentJobName 任务当前名称）
     * @param: @param newJobName 任务新名称
     * @param: @return      
     * @return: boolean      
     * @throws
     */
    public boolean renameJob(String optionalFolderPath,String currentJobName, String newJobName) 
        return jobsApi.rename(optionalFolderPath, currentJobName, newJobName);
    

4.19任务某次构建的步骤信息

    /**
     * @Title: workflow   
     * @Description: 任务某次构建的步骤信息
     * @param: @param optionalFolderPath 文件夹名称（对应的是 folder 类型的item）
     * @param: @param jobName (任务名）
     * @param: @param buildNumber (任务新名称)
     * @param: @return      
     * @return: Workflow       
     * @throws
     */
    public Workflow workflow(String optionalFolderPath,String JobName, int buildNumber) 
        return jobsApi.workflow(optionalFolderPath, JobName, buildNumber);
    

4.20 获取pipelineNode信息

   /**
     * @Title: getPipelineNode   
     * @Description: 获取pipelineNode信息
     * @param: @param optionalFolderPath 文件夹名称（对应的是 folder 类型的item）
     * @param: @param jobName (任务名）
     * @param: @param buildNumber (任务新名称)
     * @param: @return      
     * @return: ProgressiveText      
     * @throws
     */
    public PipelineNode  getPipelineNode(String optionalFolderPath,String JobName, int buildNumber) 
        return jobsApi.pipelineNode(optionalFolderPath, JobName, buildNumber);
    

5.systemApi-系统环境API

未完待续……

6.pluginManagerApi-插件API

7.statisticsApi-统计信息API

8.queueApi-任务队列API

9.crumbIssuerApi-用于CSRF