术语定义
名词 | 说明 |
---|---|
job | 任务 |
payload | 在POST请求中提交的数据 |
{optionalFolderPath} | 可选参数:任务所在目录的路径 |
{job_name} | 必须参数:任务名称 |
- 在 GET/POST 时需要附加 HTTP 认证才能访问 API
- 本文使用的数据结构可以在 jenkins-rest/domain 中查看详细定义
API类型
API类型 | 说明 |
---|---|
JobsAP | 任务管理(任务信息、创建、修改) |
OBPluginManagerAPI | 插件管理(插件信息、安装插件) |
QueueAPI | 任务队列相关(队列状态) |
StatisticsAPI | Jenkins统计信息 |
CrumbIssuerAPI | 系统哈希值信息(用于防御CSRF攻击) |
SystemAPI | Jenkins系统状态(版本、路径) |
API汇总
名称 | API |
---|---|
创建 Job | POST http://localhost:8080/createItem/api/json |
更新 Job | POST http://localhost:8080/job/{job_name}/config.xml/api/json |
获取 Job | GET http://localhost:8080/job/{job_name}/api/json |
获取 JobXml | GET http://localhost:8080/job/{job_name}/config.xml/api/json |
删除 Job | POST http://127.0.0.1:8080/{optionalFolderPath}job/{job_name}/doDelete |
enable Job | POST http://127.0.0.1:8080/{optionalFolderPath}job/{job_name}/enable |
disable Job | POST http://127.0.0.1:8080/{optionalFolderPath}job/{job_name}/disable |
获取任务描述 | GET http://127.0.0.1:8080/{optionalFolderPath}job/{job_name}/description |
设置任务描述 | POST http://127.0.0.1:8080/{optionalFolderPath}job/{job_name}/description |
创建 Build | POST http://localhost:8080/job/{job_name}/build/api/json |
获取 QueueItem | GET http://localhost:8080/queue/item/17/api/json |
取消任务队列 | POST http://127.0.0.1:8080/cancelItem?id={id} |
所有任务队列信息 | GET http://127.0.0.1:8080/queue/api/json |
获取 Build信息 | GET http://localhost:8080/job/test/6/api/json |
获取上次构建序号 | GET http://127.0.0.1:8080/{optionalFolderPath}job/{job_name}/lastBuild/buildNumber |
获取上次构建时间戳 | GET http://127.0.0.1:8080/{optionalFolderPath}job/{job_name}/lastBuild/buildTimestamp |
获取TXT日志 | GET http://localhost:8080/job/test/{build_number}/logText/progressiveText/api/json |
获取 Html 日志 | GET http://localhost:8080/job/test/{build_number}/logText/progressiveHtml/api/json |
系统哈希值信息 | GET http://127.0.0.1:8080/crumbIssuer/api/xml?{key}={value} |
load统计信息 | GET http://127.0.0.1:8080/overallLoad/api/json |
插件管理 | GET http://127.0.0.1:8080/pluginManager/api/json |
安装插件 | POST http://127.0.0.1:8080/pluginManager/installNecessaryPlugins |
API详述
创建 Job
jenkins 的配置都是靠 xml 的格式落地的,所以配置其实都是 xml 的形式.
POST http://127.0.0.1:8080/createItem
参数
key | value |
---|---|
name 任务名称 | |
payload XML配置文件 |
返回类型:RequestStatus
字段 | 类型 | 说明 |
---|---|---|
value | Boolean | |
errors | List |
如何知道 config.xml应该如何编写呢?
- 可以在 jenkins 收工创建一个需要的项目,然后编辑完成后,到 jenkins 工作目录下 找到 jobs/{job_name}/config.xml 用他作为模板来书写你需要的模板.
- 通过获取 xml 的 api 来获取
GET http://localhost:8080/job/{job_name}/config.xml/api/json
Java Client
jenkinsServer.createJob("auto_test_job", replacedText, true);
String xml = jenkinsServer.getJobXml("auto_test_job");
更新Job
POST http://localhost:8080/job/{job_name}/config.xml/api/json
参数
字段 | 说明 |
---|---|
payload | XML配置文件 |
config.xml的内容传入到 body 中,contentType 设置为text/xml
返回类型:Boolean
Java Client
jenkinsServer.updateJob("auto_test_job", replacedText, true);
job-info 获取任务信息
GET http://127.0.0.1:8080/{optionalFolderPath}job/{job_name}/api/json
返回类型:JobInfo
字段 | 类型 | 说明 |
---|---|---|
description | String | 描述 |
name | String | 项目名称 |
url | boolean | 路径 |
buildable | String | 是否可构建 |
builds | List | 构建记录 |
lastBuild | BuildInfo | 上次构建记录 |
…… |
delete 删除任务
POST http://127.0.0.1:8080/{optionalFolderPath}job/{project_name}/doDelete
返回类型:RequestStatus
补充:
也可以使用
DELETE https://<Jenkins_url>/job/<job_name>/
注意最后有个 /
,不加 /
不能正常删除
enable允许任务
POST http://127.0.0.1:8080/{optionalFolderPath}job/{project_name}/enable
返回类型:Boolean
disable 禁止任务
POST http://127.0.0.1:8080/{optionalFolderPath}job/{project_name}/disable
返回类型:Boolean
get-description 获取任务描述
GET http://127.0.0.1:8080/{optionalFolderPath}job/{project_name}/description
返回类型:String
set-description 设置任务描述
POST http://127.0.0.1:8080/{optionalFolderPath}job/{project_name}/description
参数
key | value |
---|---|
description | 描述 |
返回类型:Boolean
创建 Build
POST http://127.0.0.1:8080/{optionalFolderPath}job/{job_name}/build
POST http://localhost:8080/job/{job_name}/build/api/json
返回类型: IntegerResponse
字段 | 类型 | 说明 |
---|---|---|
value | Integer | |
errors | List |
build-with-params 使用参数创建任务
POST http://127.0.0.1:8080/{optionalFolderPath}job/{job_name}/buildWithParameters
参数
key | value |
---|---|
payload | Map<String, List> properties |
返回类型: IntegerResponse
新的构建请求提交到服务器成功后返回一个类似于队列ID的东西,因为是异步构建,那么要获取构建的状态,就需要,用这个队列 id去进一步的获取. 例如:
$ curl -v -XPOST http://localhost:8080/job/test/build/api/json
* Trying ::1...
* TCP_NODELAY set
* Connected to localhost (::1) port 8080 (#0)
> POST /job/test/build/api/json HTTP/1.1
> Host: localhost:8080
> User-Agent: curl/7.54.0
> Accept: */*
>
< HTTP/1.1 201 Created
< Date: Sat, 05 Jan 2019 08:33:45 GMT
< X-Content-Type-Options: nosniff
< Location: http://localhost:8080/queue/item/17/
< Content-Length: 0
< Server: Jetty(9.4.z-SNAPSHOT)
<
* Connection #0 to host localhost left intact
上面的Location: http://localhost:8080/queue/item/17/
就是返回的队列信息,下面的 queueItem 获取就是依赖这个.
根据 QueueId 获取 QueueItem
GET http://localhost:8080/queue/item/17/api/json
参数
字段 | 说明 |
---|---|
{queueId} | 任务队列ID |
返回类型:QueueItem
$ curl http://localhost:8080/queue/item/17/api/json\?pretty\=true
{
"_class" : "hudson.model.Queue$LeftItem",
"actions" : [
{
"_class" : "hudson.model.CauseAction",
"causes" : [
{
"_class" : "hudson.model.Cause$UserIdCause",
"shortDescription" : "由用户 anonymous 启动",
"userId" : null,
"userName" : "anonymous"
}
]
}
],
"blocked" : false,
"buildable" : false,
"id" : 17,
"inQueueSince" : 1546677225670,
"params" : "",
"stuck" : false,
"task" : {
"_class" : "hudson.maven.MavenModuleSet",
"name" : "test",
"url" : "http://localhost:8080/job/test/",
"color" : "blue"
},
"url" : "queue/item/17/",
"why" : null,
"cancelled" : false,
"executable" : {
"_class" : "hudson.maven.MavenModuleSetBuild",
"number" : 6,
"url" : "http://localhost:8080/job/test/6/"
}
}
cancel 取消任务队列
POST http://127.0.0.1:8080/cancelItem?id={id}
参数
字段 | 说明 |
---|---|
{id} | 任务队列ID |
返回类型:RequestStatus
queue 所有任务队列信息
GET http://127.0.0.1:8080/queue/api/json
返回类型:List
字段 | 类型 | 说明 |
---|---|---|
blocked | Boolean | 是否阻塞 |
buildable | Boolean | 是否可构建 |
id | Integer | |
inQueueSince | Long | |
params | Map<String, String> | 任务参数 |
task | Task | Task中包含任务名称和URL |
…… |
获取 Build 详情
GET http://127.0.0.1:8080/{optionalFolderPath}job/{job_name}/{number}/api/json
返回类型:BuildInfo
字段 | 类型 | 说明 |
---|---|---|
artifacts | List | artifacts |
actions | Lis | actions |
building | boolean 路径 | |
description | String | 描述 |
…… |
curl http://localhost:8080/job/test/6/api/json\?pretty\=true
{
...
"building" : false,
"description" : null,
"displayName" : "#6",
"duration" : 13631,
"estimatedDuration" : 17999,
"executor" : null,
"fullDisplayName" : "test #6",
"id" : "6",
"keepLog" : false,
"number" : 6,
"queueId" : 17,
"result" : "SUCCESS",
"timestamp" : 1546677234794,
"url" : "http://localhost:8080/job/test/6/",
"builtOn" : "",
...
}
从返回结果可以看到 是否还在 build:"building" : false
,如果 build 结束状态就在:"result" : "SUCCESS"
获取上次Build详情
curl http://172.12.12.234:8080/job/pytest_7.0/lastBuild/api/xml --user jenkins:1
last-build-number 获取上次构建序号
GET http://127.0.0.1:8080/{optionalFolderPath}job/{job_name}/lastBuild/buildNumber
返回类型:Integer
last-build-timestamp 获取上次构建时间戳
GET http://127.0.0.1:8080/{optionalFolderPath}job/{job_name}/lastBuild/buildTimestamp
返回类型:String
progressive-text 获取构建控制台输出
获取上次构建的日志
GET http://127.0.0.1:8080/{optionalFolderPath}job/{job_name}/lastBuild/logText/progressiveText
返回类型:ProgressiveText
字段 | 类型 | 说明 |
---|---|---|
text | String | 控制台输出 |
size | Integer | 字数 |
hasMoreData | Boolean | 是否有更多数据 |
获取某次构建的日志
// text
GET http://localhost:8080/job/test/{build_number}/logText/progressiveText/api/json
// html
GET http://localhost:8080/job/test/{build_number}/logText/progressiveHtml/api/json
JobWithDetails job = jenkinsServer.getJob(jenkinsJob);
...
QueueReference reference = job.build( true);
...
QueueItem queueItem = jenkinsServer.getQueueItem(new QueueReference(queuePart));
...
Build build = jenkinsServer.getBuild(queueItem);
...
BuildWithDetails details = build.details();
BuildResult result = details.getResult();
...
String logs = details.getConsoleOutputText();
CrumbIssuer 系统哈希值信息(用于防御CSRF攻击)
- CrumbIssuerApi
- path: /crumbIssuer/api/xml
crumb
GET http://127.0.0.1:8080/crumbIssuer/api/xml?{key}={value}
参数
key | value |
---|---|
xpath | concat(//crumbRequestField,”:”,//crumb) |
返回类型:Crumb
字段 | 类型 |
---|---|
value | String |
errors | List |
Statistics 统计信息
- StatisticsApi
- path: /
overall-load
GET http://127.0.0.1:8080/overallLoad/api/json
返回类型:OverallLoad
字段 | 类型 | 说明 |
---|---|---|
availableExecutors | Map<String, String> | |
busyExecutors | Map<String, String> | |
connectingExecutors | Map<String, String> | |
definedExecutors | Map<String, String> | |
idleExecutors | Map<String, String> | |
onlineExecutors | Map<String, String> | |
queueLength | Map<String, String> | |
totalExecutors | Map<String, String> | |
totalQueueLength | Map<String, String> |
System 系统信息
- path: /
返回类型:SystemInfo
字段 | 类型 | 说明 |
---|---|---|
hudsonVersion | String | |
jenkinsVersion | String | |
jenkinsSession | String | |
instanceIdentity | String | |
sshEndpoint | String | |
server | String |
PluginManager 插件管理(插件信息、安装插件)
- PluginManagerApi
- path: /pluginManager
plugins 插件列表
GET http://127.0.0.1:8080/pluginManager/api/json
返回类型:List
字段 | 类型 | 说明 |
---|---|---|
active | Boolean | |
backupVersion String | ||
bundled | Boolean | |
deleted | Boolean | |
downgradable | Boolean | |
enabled | Boolean | |
longName | String | |
…… |
installNecessaryPlugins 安装插件
POST http://127.0.0.1:8080/pluginManager/installNecessaryPlugins
参数
payload: <jenkins><install plugin="{pluginID}"/></jenkins>
字段 | 说明 |
---|---|
{pluginID} | 要安装的插件ID |
返回类型:RequestStatus
代码示例
配置
导入依赖
<!--jenkins-java-client-->
<dependency>
<groupId>com.offbytwo.jenkins</groupId>
<artifactId>jenkins-client</artifactId>
<version>0.3.8</version>
</dependency>
创建连接配置,配置对应的信息
import com.offbytwo.jenkins.JenkinsServer;
import com.offbytwo.jenkins.client.JenkinsHttpClient;
import java.net.URI;
import java.net.URISyntaxException;
public class JenkinsConnect {
private JenkinsConnect(){}
// 连接 Jenkins 需要设置的信息
static final String JENKINS_URL = "http://jenkins:8080/";
static final String JENKINS_USERNAME = "jenkins";
static final String JENKINS_PASSWORD = "jenkins";
/**
* Http 客户端工具
*
* 如果有些 API 该Jar工具包未提供,可以用此Http客户端操作远程接口,执行命令
* @return
*/
public static JenkinsHttpClient getClient(){
JenkinsHttpClient jenkinsHttpClient = null;
try {
jenkinsHttpClient = new JenkinsHttpClient(new URI(JENKINS_URL), JENKINS_USERNAME, JENKINS_PASSWORD);
} catch (URISyntaxException e) {
e.printStackTrace();
}
return jenkinsHttpClient;
}
/**
* 连接 Jenkins
*/
public static JenkinsServer connection() {
JenkinsServer jenkinsServer = null;
try {
jenkinsServer = new JenkinsServer(new URI(JENKINS_URL), JENKINS_USERNAME, JENKINS_PASSWORD);
} catch (URISyntaxException e) {
e.printStackTrace();
}
return jenkinsServer;
}
}
JENKINS_URL是Jenkins的反向代理地址, Configure System -> Jenkins location url
, 一般和Jenkins首页访问地址一致
JENKINS_USERNAME Jenkins登录账号
JENKINS_PASSWORD Jenkins账号密码
使用示例
import com.offbytwo.jenkins.JenkinsServer;
import com.offbytwo.jenkins.client.JenkinsHttpClient;
import com.offbytwo.jenkins.model.Build;
import com.offbytwo.jenkins.model.Job;
import com.offbytwo.jenkins.model.JobWithDetails;
import com.offbytwo.jenkins.model.MavenJobWithDetails;
import java.io.IOException;
import java.util.HashMap;
import java.util.Map;
public class JobApi {
// Jenkins 对象
private JenkinsServer jenkinsServer;
// http 客户端对象
private JenkinsHttpClient jenkinsHttpClient;
/**
* 构造方法中调用连接 Jenkins 方法
*/
JobApi() {
// 连接 Jenkins
jenkinsServer = JenkinsConnect.connection();
// 设置客户端连接 Jenkins
jenkinsHttpClient = JenkinsConnect.getClient();
}
/**
* 创建 Job
*/
public void ceateJob(){
try {
/**创建一个流水线任务,且设置一个简单的脚本**/
// 创建 Pipeline 脚本
String script = "node(){ \n" +
"echo 'hello world!' \n" +
"}";
// xml配置文件,且将脚本加入到配置中
String xml = "<flow-definition plugin=\"workflow-job@2.32\">\n" +
"<description>测试项目</description>\n" +
"<definition class=\"org.jenkinsci.plugins.workflow.cps.CpsFlowDefinition\" plugin=\"workflow-cps@2.66\">\n" +
"<script>" + script + "</script>\n" +
"<sandbox>true</sandbox>\n" +
"</definition>\n" +
"</flow-definition>";
// 创建 Job
jenkinsServer.createJob("test-job",xml, true);
} catch (IOException e) {
e.printStackTrace();
}
}
/**
* 更新 Job
*
* 更改之前创建的无参数Job,更改其为参数Job
*/
public void updateJob(){
try {
/**
* 更改一个流水线任务,让一个无参数的任务变成带参数任务
*/
// 创建 Pipeline 脚本,用一个key变量
String script = "node(){ \n" +
"echo \"${key}\" \n" +
"}";
// xml配置文件,且将脚本加入到配置中
String xml = "<flow-definition plugin=\"workflow-job@2.32\">\n" +
"<actions/>\n" +
"<description>测试项目</description>\n" +
"<keepDependencies>false</keepDependencies>\n" +
"<properties>\n" +
"<hudson.model.ParametersDefinitionProperty>\n" +
"<parameterDefinitions>\n" +
"<hudson.model.StringParameterDefinition>\n" +
"<name>key</name>\n" +
"<description>用于测试的字符变量</description>\n" +
"<defaultValue>hello</defaultValue>\n" +
"<trim>false</trim>\n" +
"</hudson.model.StringParameterDefinition>\n" +
"</parameterDefinitions>\n" +
"</hudson.model.ParametersDefinitionProperty>\n" +
"</properties>\n" +
"<definition class=\"org.jenkinsci.plugins.workflow.cps.CpsFlowDefinition\" plugin=\"workflow-cps@2.66\">\n" +
"<script>" + script + "</script>\n" +
"<sandbox>true</sandbox>\n" +
"</definition>\n" +
"<disabled>false</disabled>\n" +
"</flow-definition>";
// 创建 Job
jenkinsServer.updateJob("test-job",xml, true);
} catch (IOException e) {
e.printStackTrace();
}
}
/**
* 获取 Job 基本信息
*/
public void getJob(){
try {
// 获取 Job 信息
JobWithDetails job = jenkinsServer.getJob("das-app-android-pkg");
// 获取 Job 名称
System.out.println(job.getName());
// 获取 Job URL
System.out.println(job.getUrl());
// 获取 Job 下一个 build 编号
System.out.println(job.getNextBuildNumber());
// 获取 Job 显示的名称
System.out.println(job.getDisplayName());
// 输出 Job 描述信息
System.out.println(job.getDescription());
// 获取 Job 下游任务列表
System.out.println(job.getDownstreamProjects());
// 获取 Job 上游任务列表
System.out.println(job.getUpstreamProjects());
} catch (IOException e) {
e.printStackTrace();
}
}
/**
* 获取 Maven Job 信息
*/
public void getMavenJob(){
try {
// 获取 Job 信息
MavenJobWithDetails job = jenkinsServer.getMavenJob("test-job");
} catch (IOException e) {
e.printStackTrace();
}
}
/**
* 获取 Job 列表
*/
public void getJobList(){
try {
// 获取 Job 列表
Map<String, Job> jobs = jenkinsServer.getJobs();
for (Job job:jobs.values()){
System.out.println(job.getName());
}
} catch (IOException e) {
e.printStackTrace();
}
}
/**
* 获取 View 名称获取 Job 列表
*/
public void getJobListByView(){
try {
// 获取 Job 列表
Map<String,Job> jobs = jenkinsServer.getJobs("all");
for (Job job:jobs.values()){
System.out.println(job.getName());
}
} catch (IOException e) {
e.printStackTrace();
}
}
/**
* 查看 Job XML 信息
*/
public void getJobConfig(){
try {
String xml = jenkinsServer.getJobXml("test-job");
System.out.println(xml);
} catch (IOException e) {
e.printStackTrace();
}
}
/**
* 执行无参数 Job build
*/
public void buildJob(){
try {
jenkinsServer.getJob("test-job").build(true);
} catch (IOException e) {
e.printStackTrace();
}
}
/**
* 执行带参数 Job build
*/
public void buildParamJob(){
try {
/**
* 例如,现有一个job,拥有一个字符参数"key"
* 现在对这个值进行设置,然后执行一个输出这个值的脚本
*/
// 设置参数值
Map<String,String> param = new HashMap<>();
param.put("way","gm-R-b");
// 执行 build 任务
jenkinsServer.getJob("das-app-android-pkg").build(param, true);
} catch (IOException e) {
e.printStackTrace();
}
}
/**
* 停止最后构建的 Job Build
*/
public void stopLastJobBuild(){
try {
// 获取最后的 build 信息
Build build = jenkinsServer.getJob("test-job").getLastBuild();
// 停止最后的 build
build.Stop();
} catch (IOException e) {
e.printStackTrace();
}
}
/**
* 删除 Job
*/
public void deleteJob(){
try {
jenkinsServer.deleteJob("test-job", true);
} catch (IOException e) {
e.printStackTrace();
}
}
/**
* 禁用 Job
*/
public void disableJob(){
try {
jenkinsServer.disableJob("test-job", true);
} catch (IOException e) {
e.printStackTrace();
}
}
/**
* 启用 Job
*/
public void enableJob(){
try {
jenkinsServer.enableJob("test-job", true);
} catch (IOException e) {
e.printStackTrace();
}
}
public static void main(String[] args) {
JobApi jobApi = new JobApi();
// jobApi.getJob();
// jobApi.getJobList();
jobApi.buildParamJob();
// // 创建 Job
// jobApi.ceateJob();
// // 构建无参数的 Job
// jobApi.buildJob();
// // 构建带参数的 Job
// jobApi.buildParamJob();
// // 停止最后构建的 Job Build
// jobApi.stopLastJobBuild();
// // 更新 Job
// jobApi.updateJob();
// // 获取 Job 信息
// jobApi.getJob();
// // 获取 Maven 项目 Job
// jobApi.getMavenJob();
// // 获取 Job 配置xml
// jobApi.getJobConfig();
// 获取全部 Job 列表
// jobApi.getJobList();
// 根据 view 名称获取 Job 列表
// jobApi.getJobListByView();
// // 禁用 Job
// jobApi.disableJob();
// // 启用 Job
// jobApi.enableJob();
// // 删除 Job
// jobApi.deleteJob();
}
}