---

前言

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

---

我觉着需要有一个前提条件，需要对页面访问下的jenkins要有个大致了解，需要知道通过页面大致如何去使用jenkins来完成自动化步骤，了解它个各个业务功能模块，尤其是项目那块，这样在使用jenkins api，才能知道调用的各个api分别对应页面上的哪个操作功能以及接口需要的参数的含义。

一、Jenkins Rest API简单介绍

在githup上，jenkins-rest项目地址：[链接地址](https://codechina.csdn.net/mirrors/cdancy/jenkins-rest?utm_source=csdn_github_accelerator)，接口定义和接口测试代码都可以详细看到。 但在使用过程中遇到了问题让我纠结了很久。 看下使用REST API前置条件：

1. 需要运行着的jenkins环境
2. 需要一个管理员权限的账号
3. CSRF功能需要关闭掉，不然会影响POST接口的请求（我在这个上面纠结了很久，我使用的版本是Jenkins2.263.4，高于2.0版本的jenkins页面上已经不提供直接关闭CSRF的勾选按钮功能，网上搜索到的很多都是通过勾选按钮关闭CSRF功能，而新版本的JENKINS已经不支持这种方式—起初，我是不想关闭CSRF，但是解决不了API POST请求接口返回403forbiden问题，然后网上看到了一种，将获取到的crumb设置到header中，通过通过httpclient方式URL请求Jenkins API，这种方式我没能成功，最终放弃了，代码编写起来也很麻烦，跟API调用方法传入参数的方式比较起来的话） 4、插件的要求我感觉我没用到。

二、使用步骤

1.关闭CSRF保护

编辑jenkins配置文件

vim /etc/sysconfig/jenkins

在默认配置文件JENKINS_JAVA_OPTIONS里面加入取消相关保护的参数配置，即可关闭CSRF,配置内容如下：

-Dhudson.security.csrf.GlobalCrumbIssuerConfiguration.DISABLE_CSRF_PROTECTION=true

修改后如下：

重启jenkins即可生效

systemctl  restart jenkins.service

登录jenkins，Dashboard->Configure Global Security,跨站请求伪造保护会有提示，即可只修改已经生效了

2.引入jenkins-rest.jar包

我新建了个maven项目用来测试API，pom.xml引入了jenkins-rest包，由githup可知，最新的版本0.0.28，使用20-28版本会出现一个问题，启动api测试代码会报一个类方法未定义的错误，这个是因为com.google.guava包在jenkins-rest包里默认的版本不对，或者使用低版本的jenkins-rest包，但我对比了下看低版本提供的API方法还是少好几个的

log4j:WARN No such property [datePattern] in org.apache.log4j.RollingFileAppender.
Exception in thread "main" java.lang.NoSuchMethodError: com.google.common.base.Preconditions.checkArgument(ZLjava/lang/String;Ljava/lang/Object;Ljava/lang/Object;)V

pom.xml配置如下：

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

3.创建客户端

githup上有示例代码，按照自己jenkins访问地址和账户密码修改下即可。

JenkinsClient client = JenkinsClient.builder()
.endPoint("http://127.0.0.1:8080") // Optional. Defaults to http://127.0.0.1:8080
.credentials("admin:password") // Optional.
.build();

SystemInfo systemInfo = client.api().systemApi().systemInfo();
assertTrue(systemInfo.jenkinsVersion().equals("1.642.4"));

由代码可以看出一共提供了6个API类，分别是

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

4.jobsApi-任务API

 JobsApi  jobApi=client.api().jobsApi();

4.1 jobList-任务一览

		 /**
         * 任务一览
         * param  文件夹路径“”，取的是最外层的任务，若要查看任务文件夹中的任务，入参则为文件名名称
         */
        JobList jobList=jobApi.jobList("");
        for(int i=0;i<jobList.jobs().size();i++){
            log.info(jobList.jobs().get(i));
        }

4.2 jobInfo-具体任务详细信息

		/**
         * 根据任务名称获取任务信息
         * param  文件夹路径null，最外层任务   任务名称“test”
         */
		JobInfo jobInfo=jobApi.jobInfo(null,"test");
        log.info("test任务详细信息"+jobInfo);

4.3 buildInfo-任务构建的详细信息

		/**
         * 根据任务名称和任务构建id，获取构建信息
         * param  文件夹路径null   任务名称“test”  构建ID 3
         */
        jobApi.buildInfo(null,"test",3);
        log.info("test任务第三次构建详细信息:"+jobApi);

4.4 create-新建任务

		File file=new File("C:\\Users\\dwzq\\Desktop\\config.xml");
        StringBuilder xmlStr=new StringBuilder();
        BufferedReader read=null;
        read=new BufferedReader(new FileReader(file));
        String tempStr;
        while((tempStr=read.readLine())!=null){
            xmlStr.append(tempStr);
        }
        read.close();
        /**
         * 创建job任务
         * param   文件夹路径null   新建任务名称“test2”   任务详细配置文件内容:xmlStr
         */
        RequestStatus status=jobApi.create(null,"test2",xmlStr.toString());
        log.info(status);

4.5 config-查看任务配置文件内容（两个入参）

	/**
     * 获取任务配置文件内容
     * param  文件夹路径null   任务名称“test2”
     */
    String testConfig=jobApi.config(null,"test2");
    log.info("testConfig:"+testConfig);

4.6 config-更新任务配置文件内容（三个入参）

	  /**
       * 更新任务的配置文件
       * param  文件夹路径null  任务名称“test2”   新的任务配置文件内容xmlStr.toString
       */
      boolean updateConfig=jobApi.config(null,"test2",xmlStr.toString());
      log.info("updateConfig result:"+updateConfig);

4.7 description-获取任务描述内容（两个入参）

      /**
      *获取任务描述
      * param 文件夹路径null  任务名称“test2”
      */
     String description= jobApi.description(null,"test2");
     log.info("description:"+description);

4.8 description-获取任务描述内容（三个入参）

		/**
         * 更新任务的描述
         * param  文件夹路径null   任务名称“tes2”  新的任务描述
         */
        Boolean updateDescription=jobApi.description(null,"test2","this is update test job description");
        log.info("updateDescription result:"+updateConfig);

4.9 delete-删除任务

     /**
      * 删除任务
      * param  文件夹路径null  任务名称
      */
     RequestStatus deleteResult=jobApi.delete(null,"test2");
     log.info("deleteResult:"+deleteResult);

4.10 enable-启用任务

     /**
     * 启用任务
     * param  文件夹路径null  任务名称“tes2” 
     */
    boolean enableResult=jobApi.enable(null,"test2");
    log.info("enableResult:"+enableResult);

4.11 disable-禁用任务

     /**
     * 禁用任务
     * param  文件夹路径null  任务名称“tes2”
     */
    boolean disableResult=jobApi.disable(null,"test2");
    log.info("disableResult:"+disableResult);

4.12 build-构建任务

	  /**
      * 任务构建
      * param 文件夹路径null , 任务名“test”
      */
    IntegerResponse buildJob=jobApi.build(null,"test");
    log.info("buildJob"+buildJob);

4.13 buildWithParameters-带参数构建任务

    /**
     * 带参数构建任务
     * param 文件夹路径null , 任务名“test”  参数
     */
    Map<String, List<String>> param=new HashMap<>();
    List<String> list=new ArrayList<>();
    list.add("staging");
    param.put("DEPLOY_ENV",list);
    param.put("myparam",list);
    IntegerResponse buldParam=jobApi.buildWithParameters(null,"test",param);
    log.info("buildParam:"+buldParam);

4.14 lastBuildNumber-上次任务的构建序号

     /**
      *上次构建的序号
      * param 文件夹路径null , 任务名“pipeline-hello-word”  参数
      */
     Integer  lastBuildNumber=jobApi.lastBuildNumber(null,"pipeline-hello-word");
     log.info("lastBuildNumber:"+lastBuildNumber);

4.15 lastBuildTimestamp-上次任务的构建时间戳

      /**
      * 上次任务构建时间
      * param 文件夹路径null , 任务名“test” 
      */
     String lastBuildTimetamp=jobApi.lastBuildTimestamp(null,"test");
     log.info("lastBuildTimestamp:"+lastBuildTimetamp);

4.16 progressiveText-任务构建对应的控制台输出内容（3个入参）

     /**
     * 获取任务构建对应的控制台输出
      * param 文件夹路径null  任务名称“test"   0:控制台输出文本开始的位置
      */
     ProgressiveText progressiveText=jobApi.progressiveText(null,"test",0);
     log.info("progressText:"+progressiveText);

4.17 progressiveText-任务构建对应的控制台输出内容（3个入参）

     /**
      * 获取任务某个构建次数控制台对应的输出
      * param 文件夹路径null  任务名称“test"   构建index:16   0:控制台输出文本开始的位置
      */
     ProgressiveText progressiveText1=jobApi.progressiveText(null,"test",16,0);
     log.info("progressText num=16:"+progressiveText1);

4.18 rename-任务重命名

      /**
       * 任务名称重命名
       * param 文件夹路径null   任务名称“test"  任务新名词“test2New”
       */
      boolean renameResult=jobApi.rename(null,"test2","test2New");
      log.info("renameResult:"+renameResult);

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

    /**
     * 获取任务构建index对应的构建步骤内容
     * param 文件夹路径null  任务名称"pipeline-hello-word"    构建index:17
     */
    Workflow workFlow=jobApi.workflow(null,"pipeline-hello-word",17);
    log.info("workFlow:"+workFlow);

4.20 pipelineNode-获取pipelineNode信息

这个没和页面具体功能联系起来，不知道具体获取的什么信息

     /**
      * 获取pipelineNode信息
      * param 文件夹路径null  任务名称"pipeline-hello-word"    构建index:17  nodeId:1
      */
     PipelineNode pipelineNode=jobApi.pipelineNode(null,"pipeline-hello-word",17,1);
     log.info("pipeLineNodeInfo:"+pipelineNode);

任务涉及到的接口是这20个，接口涉及到的数据结构的定义可以在githup domain查看

5.systemApi-系统环境API

SystemApi systemApi=client.api().systemApi();

5.1 systemInfo-查看jenkins系统环境信息

    /**
     * 查看jenkins系统环境信息
     */
    SystemInfo systemInfo=systemApi.systemInfo();
    log.info("systemInfo:"+systemInfo);

5.2 quietDown-准备关闭jenkins,对应Prepare for Shutdown功能

	  /**
      * 准备关闭jenkins,对应Prepare for Shutdown功能
      */
     RequestStatus quietDown=systemApi.quietDown();
     log.info("quietDown:"+quietDown);

5.3 cancelQuietDown-取消准备关闭jenkins

    /**
    * 取消准备关闭jenkins
     */
    RequestStatus cancleQuietDown= systemApi.cancelQuietDown();
    log.info("cancelQuietDown:"+cancleQuietDown);

6.pluginManagerApi-插件API

    PluginManagerApi pluginManagerApi=client.api().pluginManagerApi();

6.1 plugins-查看所有插件信息

    /**
    *查看插件所有信息
     *param   不是很理解这两个参数的具体含义，第一个参数调整返回的插件信息不一样
     */
   Plugins plugins=pluginManagerApi.plugins(3,null);
   for(int i=0;i<plugins.plugins().size();i++) {
       log.info(plugins.plugins().get(i).longName()+":" + plugins.plugins().get(i));
   }

6.2 installNecessaryPlugins-插件安装

     /**
     * 安装插件
     * param 插件ID@版本号
     */
    RequestStatus requestStatus=pluginManagerApi.installNecessaryPlugins("artifactory@3.10.6");
    log.info("artifactory:"+requestStatus);

7.statisticsApi-统计信息API

        /**
         * 我的系统返回值为空，所以不清楚具体统计的什么
         */
       StatisticsApi statisticsApi= client.api().statisticsApi();
       OverallLoad overallLoad=statisticsApi.overallLoad();
       log.info("overallLoad:"+overallLoad);

8.queueApi-任务队列API

		 /**
         * 三个接口，因为没数据，所以对应页面功能不是很理解
         */
         QueueApi queueApi=client.api().queueApi();
         List<QueueItem> queueList=queueApi.queue();
         RequestStatus cancelStatus=queueApi.cancel(1);
         QueueItem queueItem=queueApi.queueItem(1);

9.crumbIssuerApi-用于CSRF

        CrumbIssuerApi crumbIssuerApi= client.api().crumbIssuerApi();
        Crumb crum=crumbIssuerApi.crumb();

总结

涉及到的restAPI接口整理了一遍，便于理解和记录，部分接口还未跟页面功能对应上，对jenkins功能理解还不全面，后续有了更深认识再补充。