【Jenkins】远程API接口介绍

Jenkins 为其功能提供了远程访问 API。目前它支持：

• REST API 风格，包含xml和json格式
• Python 包装接口
• Java 包装接口
• Ruby 包装接口

远程访问 API 以 REST 样式提供。也就是说，没有所有功能的单一入口点，而是在".../api/" URL 下提供，其中"..."部分是它作用的数据。

例如，如果您的 Jenkins 安装在 https://ci.jenkins.io，访问 https://ci.jenkins.io/api/ 只会显示可用的顶级 API 功能

一、CSRF 跨域保护解决

直接调用Jenkins接口会报错误HTTP ERROR 403 No valid crumb was included in the request，这个是因为默认接口不允许跨域允许，需要增加启动参数后重启Jenkins

这里以容器化Jenkins配置为例

# 以root用户进入容器
docker exec -u root -it jenkins /bin/bash

# 容器是ubuntu ,所以用 apt-get，先安装vim
# 先升级版本
apt-get update
# 在安装 vim
apt-get install vim 

修改配置jenkins.sh

vim /usr/local/bin/jenkins.sh 

找到exec java那行，添加配置 -Dhudson.security.csrf.GlobalCrumbIssuerConfiguration.DISABLE_CSRF_PROTECTION=true，保存退出

添加完成后，最终效果是

exec java -Duser.home="$JENKINS_HOME" -Dhudson.security.csrf.GlobalCrumbIssuerConfiguration.DISABLE_CSRF_PROTECTION=true "${java_opts_array[@]}" -jar ${JENKINS_WAR} "${jenkins_opts_array[@]}" "$@"

重启Jenkins容器

docker restart jenkins

打开Jenkins-系统管理-全局安全配置，可以看见配置变成下面这样

二、常用接口介绍

您只需在 JENKINS_URL/job/JOBNAME/build 上执行 HTTP POST。

这也适用于多分支管道和组织文件夹。这将触发扫描。

注意，以下示例假设 JENKINS_URL = http://192.168.56.114:8080

1、触发任务执行

您只需在 JENKINS_URL/job/JOBNAME/build 上执行 HTTP POST。

1）执行无参任务parallelsAlwaysFailFast

curl -X POST 'http://192.168.56.114:8080/job/parallelsAlwaysFailFast/build' --user admin:admin123

2）执行带参数任务pipeline_variables

执行带参数任务需调用接口buildWithParameters

curl -X POST 'http://192.168.56.114:8080/job/pipeline_variables/buildWithParameters' --user admin:admin123   --data ENV=prod

2、创建任务

1）复制任务

要复制任务，请使用三个查询参数 name=NEWJOBNAME&mode=copy&from=FROMJOBNAME 向此 JENKINS_URL/createItem发送 POST 请求。

curl -X POST 'http://192.168.56.114:8080/createItem?name=test01&mode=copy&from=test' \
--user admin:admin123  

2）创建任务

要创建一个新任务，需要将 config.xml 发布到此 URL 并带上查询参数 name=JOBNAME。您需要发送 Content-Type: application/xml 头。

如果创建成功，您将收到 200 状态代码，如果失败，则会收到 4xx/5xx 代码。
config.xml 是 Jenkins 用于在文件系统中存储项目的格式，因此您可以在 Jenkins 主目录中看到它们的示例，或者通过从 /job/JOBNAME/config.xml 检索现有作业的 XML 配置来查看它们的示例。

创建新任务api_job_test

设置请求头 Content-Type: application/xml ，并发送data参数的config.xml内容

curl -L 'http://192.168.56.114:8080/createItem?name=api_job_test' \
-H 'Content-Type: application/xml' \
--user admin:admin123  \
--data '<?xml version='\''1.1'\'' encoding='\''UTF-8'\''?>
<flow-definition plugin="workflow-job@1385.vb_58b_86ea_fff1">
  <actions>
    <org.jenkinsci.plugins.pipeline.modeldefinition.actions.DeclarativeJobAction plugin="pipeline-model-definition@2.2151.ve32c9d209a_3f"/>
    <org.jenkinsci.plugins.pipeline.modeldefinition.actions.DeclarativeJobPropertyTrackerAction plugin="pipeline-model-definition@2.2151.ve32c9d209a_3f">
      <jobProperties/>
      <triggers/>
      <parameters/>
      <options/>
    </org.jenkinsci.plugins.pipeline.modeldefinition.actions.DeclarativeJobPropertyTrackerAction>
  </actions>
  <description></description>
  <keepDependencies>false</keepDependencies>
  <properties/>
  <definition class="org.jenkinsci.plugins.workflow.cps.CpsFlowDefinition" plugin="workflow-cps@3826.v3b_5707fe44da_">
    <script>pipeline {
    agent any
    environment {
        CC = 'clang'
    }
    stages {
        stage('Example') {
            environment {
                DEBUG_FLAGS = '-g'
            }
            steps {
                sh 'printenv'
            }
        }
    }
}</script>
    <sandbox>true</sandbox>
  </definition>
  <triggers/>
  <disabled>false</disabled>
</flow-definition>'

config.xml代码示例

<?xml version='1.1' encoding='UTF-8'?>
<flow-definition plugin="workflow-job@1385.vb_58b_86ea_fff1">
  <actions>
    <org.jenkinsci.plugins.pipeline.modeldefinition.actions.DeclarativeJobAction plugin="pipeline-model-definition@2.2151.ve32c9d209a_3f"/>
    <org.jenkinsci.plugins.pipeline.modeldefinition.actions.DeclarativeJobPropertyTrackerAction plugin="pipeline-model-definition@2.2151.ve32c9d209a_3f">
      <jobProperties/>
      <triggers/>
      <parameters/>
      <options/>
    </org.jenkinsci.plugins.pipeline.modeldefinition.actions.DeclarativeJobPropertyTrackerAction>
  </actions>
  <description></description>
  <keepDependencies>false</keepDependencies>
  <properties/>
  <definition class="org.jenkinsci.plugins.workflow.cps.CpsFlowDefinition" plugin="workflow-cps@3826.v3b_5707fe44da_">
    <script>pipeline {
    agent any
    environment {
        CC = &apos;clang&apos;
    }
    stages {
        stage(&apos;Example&apos;) {
            environment {
                DEBUG_FLAGS = &apos;-g&apos;
            }
            steps {
                sh &apos;printenv&apos;
            }
        }
    }
}</script>
    <sandbox>true</sandbox>
  </definition>
  <triggers/>
  <disabled>false</disabled>
</flow-definition>

3、创建视图

1）复制视图

要复制一个视图，请使用三个查询参数 name=NEWVIEWNAME&mode=copy&from=FROMVIEWNAME 向 JENKINS_URL/createView 发送 POST 请求。

示例，从视图View01复制创建新视图View03

curl -X POST 'http://192.168.56.114:8080/createView?name=View05&mode=copy&from=View01' \
--user admin:admin123  

2）创建视图

要创建一个新视图，请将 config.xml 发送到 JENKINS_URL/createView并带上查询参数 name=VIEWNAME。您需要发送 Content-Type: application/xml 头。

如果创建成功，您将收到 200 状态代码，如果失败，则会收到 4xx/5xx 代码。
config.xml 是 Jenkins 用于在文件系统中存储视图的格式，因此您可以在 Jenkins 主目录中看到它们的示例，或者通过从 /view/VIEWNAME/config.xml 检索现有视图的 XML 配置来查看它们的示例。

视图config.xml示例

<?xml version="1.1" encoding="UTF-8"?>
<hudson.model.ListView>
  <name>testView</name>
  <filterExecutors>false</filterExecutors>
  <filterQueue>false</filterQueue>
  <properties class="hudson.model.View$PropertyList"/>
  <jobNames>
    <comparator class="java.lang.String$CaseInsensitiveComparator"/>
    <string>api01</string>
    <string>api02</string>
    <string>api03</string>
    <string>api04</string>
  </jobNames>
  <jobFilters/>
  <columns>
    <hudson.views.StatusColumn/>
    <hudson.views.WeatherColumn/>
    <hudson.views.JobColumn/>
    <hudson.views.LastSuccessColumn/>
    <hudson.views.LastFailureColumn/>
    <hudson.views.LastDurationColumn/>
    <hudson.views.BuildButtonColumn/>
    <hudson.plugins.favorite.column.FavoriteColumn plugin="favorite@2.208.v91d65b_7792a_c"/>
  </columns>
  <recurse>false</recurse>
</hudson.model.ListView>

4、重启Jenkins

curl -X POST 'http://192.168.56.114:8080/restart' \
--user admin:admin123  

三、Jenkins API 接口支持的sdk

1、Python API 包装器

JenkinsAPI、Python-Jenkins、api4jenkins、aiojenkins 是 Python REST API 的面向对象的 Python 包装器，旨在提供一种更传统的 Python 方式来控制 Jenkins 服务器。它提供了一个更高级的 API，其中包含许多便利函数。目前提供的服务包括：

• 查询已完成构建的测试结果
• 获取表示作业最新构建的对象
• 根据简单的条件搜索工件
• 阻塞直到作业完成
• 将工件安装到自定义指定的目录结构中
• 对 Jenkins 实例进行身份验证
• 能够通过 subversion 修订版本搜索构建
• 能够添加/删除/查询 Jenkins 代理

2、Java API 包装器

jenkins-rest 库是一个面向对象的 Java 项目，它通过编程方式提供对 Jenkins REST API 的访问，以访问 Jenkins 提供的一些远程 API。它使用 jclouds 工具包构建，可以轻松扩展以支持更多 REST 端点。其功能集不断发展，用户可以通过拉取请求贡献新的端点。在当前状态下，使用此库可以提交作业、跟踪其通过队列的进度并监控其执行直到完成，并获取构建状态。目前提供的服务包括：

• 端点定义（属性或环境变量）
• 身份验证（通过属性或环境变量进行基本和 API 令牌）
• Crumbs Issuer 支持（自动检测 crumbs）
• 文件夹支持
• 作业 API（构建、构建信息、带参数构建、配置、创建、删除、描述、禁用、启用、作业信息、最后构建编号、最后构建时间戳和渐进文本）
• 插件管理器 API（安装必要的插件、列出当前插件）
• 队列 API（取消、列出队列项、查询队列项）
• 统计 API（总体负载）
• 系统 API（系统信息）

该项目快速发展，功能还在持续增加中。

3、Ruby API 包装器

Jenkins API 客户端是一个面向对象的 Ruby 包装器项目，它使用 Jenkins 的 JSON API，旨在提供对 Jenkins 提供的所有远程 API 的访问。它作为 Rubygem 提供，可以与 Job、Node、View、BuildQueue 和 System 相关功能进行交互。目前提供的服务包括：

• 通过发送 xml 文件或通过指定参数作为选项（包括源控制、通知等）来创建作业，并提供更多自定义选项。
• 构建作业（带参数）、停止构建、查询最近构建的详细信息、获取构建参数等。
• 使用作业名称过滤器、作业状态过滤器列出 Jenkins 中可用的作业。
• 添加/删除下游项目。
• 链接作业，即给定一个项目列表，每个项目都作为下游项目添加到前一个项目。
• 获取渐进式控制台输出。
• 基于用户名/密码的身份验证。
• 库中提供了很多选项的命令行界面。
• 创建、列出视图。
• 将作业添加到视图并从视图中删除作业。
• 添加/删除 Jenkins 代理，查询代理的详细信息。
• 获取构建队列中的任务及其年龄、原因、原因、ETA、ID、参数等。
• 静音，取消静音，安全重启，强制重启，并等待 Jenkins 在重启后可用。
• 能够列出已安装/可用的插件、获取有关插件的详细信息、安装/卸载插件以及更多插件。
  项目源代码在此处

参考

• https://www.jenkins.io/doc/book/using/remote-access-api/