Jenkins基础：API：7：使用API对Job进行操作

在前面的文章中，已经陆续介绍过如何使用API进行Job的创建、拷贝、启用、禁用等操作，这篇文章将进一步介绍如何使用API进行Job构建、取消、删除等操作。

Jenkins环境

本文示例的Jenkins的API Token是基于LTS 2.164.3版本进行演示。详细的环境构建可参看：

• https://liumiaocn.blog.csdn.net/article/details/90679244

• Job准备
  事前可参看前面的文章创建相关的Job，也可手动直接在Jenkins上进行操作生成。
  

• 前文中已经使用过的示例

操作	HTTP动作	URI	使用示例
创建Job	POST	/createItem	/createItem?name=Job名称
拷贝Job	POST	/createItem	/createItem?name=Job名称&mode=copy&from=源Job名称
起用Job	POST	/job/job名称/enable	/job/job名称/enable
禁用Job	POST	/job/job名称/disable	/job/job名称/disable

取得Crumb信息

liumiaocn:jenkins liumiao$ curl -u root:liumiaocn 'http://localhost:32002/crumbIssuer/api/xml?xpath=concat(//crumbRequestField,":",//crumb)'
Jenkins-Crumb:5955de6dcdcdb990b7341ead1045eb64liumiaocn:jenkins liumiao$

Job Description获取与更新

操作	HTTP动作	URI	使用示例
获取Job描述信息	GET	/job/job名称/description	/job/job名称/description
更新Job描述信息	POST	/job/job名称/description	/job/job名称/description

• 获取描述信息

liumiaocn:jenkins liumiao$ curl http://localhost:32002/job/free_style_job/description
Free Style Jobliumiaocn:jenkins liumiao$ 
liumiaocn:jenkins liumiao$ 
liumiaocn:jenkins liumiao$ curl http://localhost:32002/job/pipeline_job_noparam/description
Pipeline Job Sampleliumiaocn:jenkins liumiao$

• 更新描述信息
  获取Job的描述信息的时候可以不需要认证信息，而更新操作则必须进行认证方可进行。这里将描述信息从“Free Style Job”修改为“Free Style Job Description”

liumiaocn:jenkins liumiao$ curl -X POST -u root:liumiaocn -H Jenkins-Crumb:5955de6dcdcdb990b7341ead1045eb64 http://localhost:32002/job/free_style_job/description --data "description=Free Style Job Description"
liumiaocn:jenkins liumiao$

更新之后，重新查询可以确认到描述信息已经被修改。

liumiaocn:jenkins liumiao$ curl http://localhost:32002/job/free_style_job/description
Free Style Job Descriptionliumiaocn:jenkins liumiao$

获取Job API信息

操作	HTTP动作	URI	使用示例
获取Job的API信息	GET	/job/job名称/api	/job/job名称/api

liumiaocn:jenkins liumiao$ curl http://localhost:32002/job/free_style_job/api/xml 2>/dev/null|xmllint --format -

<freeStyleProject _class="hudson.model.FreeStyleProject">
  <action/>
  <action/>
  <action/>
  <action/>
  <action/>
  <action _class="com.cloudbees.plugins.credentials.ViewCredentialsAction"/>
  <description>Free Style Job Descriptiondescription>
  <displayName>free_style_jobdisplayName>
  <fullDisplayName>free_style_jobfullDisplayName>
  <fullName>free_style_jobfullName>
  <name>free_style_jobname>
  <url>http://localhost:32002/job/free_style_job/url>
  <buildable>truebuildable>
  <color>notbuiltcolor>
  <inQueue>falseinQueue>
  <keepDependencies>falsekeepDependencies>
  <nextBuildNumber>1nextBuildNumber>
  <property _class="com.dabsquared.gitlabjenkins.connection.GitLabConnectionProperty"/>
  <concurrentBuild>falseconcurrentBuild>
  <scm _class="hudson.scm.NullSCM"/>
freeStyleProject>
liumiaocn:jenkins liumiao$ 

删除Job

操作	HTTP动作	URI	使用示例
删除Job	POST	/job/job名称/doDelete	/job/job名称/doDelete

此处以free_style_job_copy为例，进行Job删除操作，操作日志示例如下所示

liumiaocn:jenkins liumiao$ curl -X POST -u root:liumiaocn -H Jenkins-Crumb:5955de6dcdcdb990b7341ead1045eb64 http://localhost:32002/job/free_style_job_copy/doDelete
liumiaocn:jenkins liumiao$

删除之后，从Jenkins上也可以清楚地看到，此Job已经不再存在

构建Job

操作	HTTP动作	URI	使用示例
执行Job	POST	/job/job名称/build	/job/job名称/build

对前文生成的pipeline类型的Job进行构建触发，示例如下所示

liumiaocn:jenkins liumiao$ curl -X POST -u root:liumiaocn -H Jenkins-Crumb:5955de6dcdcdb990b7341ead1045eb64 http://localhost:32002/job/pipeline_job_noparam/build
liumiaocn:jenkins liumiao$ 

从Jenkins上可以看到执行结果信息如下所示

查询构建日志

操作	HTTP动作	URI	使用示例
查询构建日志(HTML格式)	GET	/job/Job名称/构建序号/console	/job/Job名称/构建序号/console
查询构建日志(文本格式)	GET	/job/Job名称/构建序号/consoleText	/job/Job名称/构建序号/consoleText

这里以文本格式的构建日志查询为例，查询一下上述构建之后的日志信息，执行日志信息如下所示

liumiaocn:jenkins liumiao$ curl http://localhost:32002/job/pipeline_job_noparam/1/consoleText
Started by user root
Running in Durability level: MAX_SURVIVABILITY
[Pipeline] Start of Pipeline
[Pipeline] node
Running on Jenkins in /data/jenkins/workspace/pipeline_job_noparam
[Pipeline] {
[Pipeline] stage
[Pipeline] { (Build)
[Pipeline] sh
+ echo Build stage ...
Build stage ...
[Pipeline] }
[Pipeline] // stage
[Pipeline] stage
[Pipeline] { (Test)
[Pipeline] sh
+ echo Test stage ...
Test stage ...
[Pipeline] }
[Pipeline] // stage
[Pipeline] stage
[Pipeline] { (Deploy)
[Pipeline] sh
+ echo Deploy stage ...
Deploy stage ...
[Pipeline] }
[Pipeline] // stage
[Pipeline] }
[Pipeline] // node
[Pipeline] End of Pipeline
Finished: SUCCESS
liumiaocn:jenkins liumiao$ 

更新Job(Pipeline方式)

操作	HTTP动作	URI	使用示例
更新Job的config.xml文件	POST	job/Job名称/config.xml	job/pipeline_job_noparam/config.xml

更新Pipeline方式的Job，只需要更新config.xml文件即可，而当前版本（LTS 2.164.3）Jenkins中使用API方式进行操作的方式也异常简单，只需要将本地的config.xml以POST的方式到远端Job即可。这里将Pipeline格式的Job的第二个Stage中添加一个sleep 操作以便与后续进行Job停止操作。

• 事前准备
  按照如下方式修改Jenkinsfile信息，添加sleep信息。

liumiaocn:sample1 liumiao$ cp -p config.xml config.xml.org
liumiaocn:sample1 liumiao$ vi config.xml
liumiaocn:sample1 liumiao$ diff config.xml config.xml.org
27,29d26
<                 sh 'echo Test stage sleep begin ...'
<                 sh 'sleep 300'
<                 sh 'echo Test stage sleep end ...'
liumiaocn:sample1 liumiao$

• 更新config.xml文件

liumiaocn:jenkins liumiao$ curl -X POST -u root:liumiaocn -H Jenkins-Crumb:5955de6dcdcdb990b7341ead1045eb64 -H "Content-Type:application/xml"  --data-binary  "@demo/pipeline/sample1/config.xml" http://localhost:32002/job/pipeline_job_noparam/config.xml
liumiaocn:jenkins liumiao$

• 结果确认
  从如下Jenkins的结果确认截图上可以看到，需要添加的sleep信息已经加入到第2个stage （Test）中了
  

停止Job

Job的停止在Jenkins中被分为了两类，一种是尚未执行的Job，这种情况下是对对了中等待的Job执行取消动作cancelItem；另外一种则是已经开始执行的Job，通过对停止对象的构建序号进行stop动作即可。

操作	HTTP动作	URI	使用示例
停止执行中的Job	POST	/job/Job名称/构建序号/stop	/job/Job名称/构建序号/stop
停止尚未执行的Job	POST	/queue/cancelItem?id=队列等待序号	/queue/cancelItem?id=队列等待序号

• 事前准备
  在前面对pipeline_job_noparam添加sleep操作后，连续两次通过API触发build操作，此操作由于会等待300秒，然后在此时间之内将两个执行中的Job停止下来。执行操作的示例日志如下所示：

liumiaocn:jenkins liumiao$ curl -X POST -u root:liumiaocn -H Jenkins-Crumb:5955de6dcdcdb990b7341ead1045eb64 http://localhost:32002/job/pipeline_job_noparam/build
liumiaocn:jenkins liumiao$ curl -X POST -u root:liumiaocn -H Jenkins-Crumb:5955de6dcdcdb990b7341ead1045eb64 http://localhost:32002/job/pipeline_job_noparam/build
liumiaocn:jenkins liumiao$

可以看到如下构建序号为3和4的两个Job都运行到了Test的Stage

顺次停掉构建序号为3和4的执行中的Job

liumiaocn:jenkins liumiao$ curl -X POST -u root:liumiaocn -H Jenkins-Crumb:5955de6dcdcdb990b7341ead1045eb64 http://localhost:32002/job/pipeline_job_noparam/3/stop
liumiaocn:jenkins liumiao$ curl -X POST -u root:liumiaocn -H Jenkins-Crumb:5955de6dcdcdb990b7341ead1045eb64 http://localhost:32002/job/pipeline_job_noparam/4/stop
liumiaocn:jenkins liumiao$

然后，在构建页面可以看到构建序号为3和4的构建状态已经变成aborted而停止了