3. API格式
Jenkins API支持以下3种格式：
- XML
- JSON并支持JSONP跨域访问
- Python
4. API文档
Jenkins API 没有统一的入口，而是采用 “…/api/” 的 REST API 样式，其中 “…” 表示Jenkins资源的URL。
常见的Jenkins资源包括：站点（实例）、Job和Build。
上面的思维导图中只是列出了不同级别API的常用API，具体用法请参考Jenkins API在线文档：
4.1 API示例
4.1.1 站点API文档 (例子)
### JENKINS_URL/api/
http://192.168.1.100:8080/api/4.1.2 View API文档 （例子）
# JENKINS_URL/view/<view-name>/api/json
http://192.168.1.100:8080/view/test/api/json4.1.3 Job API文档 （例子）
下面的命令可以查看当前job的api：
# JENKINS_URL/job/<job-name>/api/ OR JENKINS_URL/job/<job-name>/api/xml
http://192.168.1.100:8080/job/email-test/api/创建项目(Job)
在创建项目之前首先需要创建一个模板配置文件 config.xml，config.xml配置文件就是pipeline项目配置文件，配置文件可通过如下方式获取：
- 手动在jenkins创建一个pipeline项目，例如我创建并配置了一个名为pipeline_demo的job。
- 访问192.168.30.8:8080/job/pipeline_demo/config.xml，这个就是pipeline_demo的配置文件，保存到本地，然后修改对应内容即可。
配置文件内容如下：
<?xml version='1.1' encoding='UTF-8'?>
<flow-definition plugin="workflow-job@1232.v5a_4c994312f1">
<actions>
<org.jenkinsci.plugins.pipeline.modeldefinition.actions.DeclarativeJobAction plugin="pipeline-model-definition@2.2114.v2654ca_721309"/>
<org.jenkinsci.plugins.pipeline.modeldefinition.actions.DeclarativeJobPropertyTrackerAction plugin="pipeline-model-definition@2.2114.v2654ca_721309">
<jobProperties/>
<triggers/>
<parameters/>
<options/>
</org.jenkinsci.plugins.pipeline.modeldefinition.actions.DeclarativeJobPropertyTrackerAction>
</actions>
<description>a pipeline demo</description>
<keepDependencies>false</keepDependencies>
<properties>
<hudson.plugins.jira.JiraProjectProperty plugin="jira@3.8"/>
<org.jenkinsci.plugins.workflow.job.properties.PipelineTriggersJobProperty>
<triggers>
<hudson.triggers.TimerTrigger>
<spec>30 22 * * *</spec>
</hudson.triggers.TimerTrigger>
</triggers>
</org.jenkinsci.plugins.workflow.job.properties.PipelineTriggersJobProperty>
</properties>
<definition class="org.jenkinsci.plugins.workflow.cps.CpsFlowDefinition" plugin="workflow-cps@2759.v87459c4eea_ca_">
<script>pipeline {
agent any
stages {
stage('begin') {
steps {
echo 'Hello pipeline'
}
}
}
post {
always {
echo 'say goodbay'
}
}
}</script>
<sandbox>true</sandbox>
</definition>
<triggers/>
<disabled>false</disabled>
</flow-definition>创建项目的命令格式如下：
curl -X POST --USER {username}:{api token} {jenkins URL}/createItem?name={jobName} --header "Content-Type:text/xml" --data-binary @config.xml- username：用户名
- api token：用户API TOKEN
- jenkins URL：jenkins地址
- jobName为项目名
使用 curl 方式执行：
$ curl -X POST --USER admin:11108c1d093a24fcebe11e945de3bcece4 http://192.168.30.8:8080/createItem?name=pipeline_demo2 --header "Content-Type:text/xml" --data-binary @pipeline_demo_config.xml
# 或者
$ curl -X POST http://admin:11108c1d093a24fcebe11e945de3bcece4@192.168.30.8:8080/createItem?name=pipeline_demo2 --header "Content-Type:text/xml" --data-binary @pipeline_demo_config.xml提示💡
这里的
@pipeline_demo_config.xml是需要再body中写入的配置文件，类型为Content-Type:text/xml。
更新项目（job）
$ curl -X POST --USER admin:11108c1d093a24fcebe11e945de3bcece4 http://192.168.30.8:8080/job/pipeline_demo2/config.xml --header "Content-Type:text/xml" --data-binary @pipeline_demo_config_new.xmlpipeline_demo_config_new.xml为更新之后的配置文件。
4.1.4 Build API文档 （例子）
# JENKINS_URL/job/<job-name>/<build-number>/api/
http://192.168.1.100:8080/job/email-test/lastSuccessfulBuild/api/4.2 API返回值
Jenkins API将Jenkins资源模型抽象为树形结构，可以通过tree来指定返回Jenkins资源的层次。
- 返回值：XML示例
<hudson _class='hudson.model.Hudson'>
<assignedLabel>
<name>master</name>
</assignedLabel>
<mode>NORMAL</mode>
<nodeDescription>Jenkins的master节点</nodeDescription>
<nodeName></nodeName>
<numExecutors>1</numExecutors>
<job _class='org.jenkinsci.plugins.workflow.job.WorkflowJob'>
<name>deploy-test2</name>
<url>http://127.0.0.1:8080/jenkins/job/deploy-test2/</url>
<color>red</color>
</job>
<job _class='org.jenkinsci.plugins.workflow.job.WorkflowJob'>
<name>test-job</name>
<url>http://127.0.0.1:8080/jenkins/job/test-job/</url>
<color>blue</color>
</job>
<quietingDown>false</quietingDown>
<slaveAgentPort>50000</slaveAgentPort>
<unlabeledLoad _class='jenkins.model.UnlabeledLoadStatistics'></unlabeledLoad>
<useCrumbs>false</useCrumbs>
<useSecurity>true</useSecurity>
<view _class='hudson.model.AllView'>
<name>all</name>
<url>http://127.0.0.1:8080/jenkins/</url>
</view>
</hudson>- 返回值：JSON示例
{
"_class": "hudson.model.Hudson",
"assignedLabels": [
{
"name": "master"
}
],
"mode": "NORMAL",
"nodeDescription": "Jenkins的master节点",
"nodeName": "",
"numExecutors": 1,
"description": null,
"jobs": [
{
"_class": "org.jenkinsci.plugins.workflow.job.WorkflowJob",
"name": "deploy-test2",
"url": "http://127.0.0.1:8080/jenkins/job/deploy-test2/",
"color": "red"
},
{
"_class": "org.jenkinsci.plugins.workflow.job.WorkflowJob",
"name": "test-job",
"url": "http://127.0.0.1:8080/jenkins/job/test-job/",
"color": "blue"
}
],
"overallLoad": {},
"primaryView": {
"_class": "hudson.model.AllView",
"name": "all",
"url": "http://127.0.0.1:8080/jenkins/"
},
"quietingDown": false,
"slaveAgentPort": 50000,
"unlabeledLoad": {
"_class": "jenkins.model.UnlabeledLoadStatistics"
},
"useCrumbs": false,
"useSecurity": true,
"views": [
{
"_class": "hudson.model.AllView",
"name": "all",
"url": "http://192.168.2.11:8080/jenkins/"
}
]
}具体用法请参考Jenkins API 在线文档。
4.3 API安全
在调用Jenkins API 时需要以HTTP Basic Auth验证方式提供用户名和密码。
另外，在Jenkins 2之后默认开启CSRF protection （跨域访问伪造保护），对有些Jenkins API的调用还需要提供Jenkins-Crumb(有时效的token)；否则会出现“403 No valid crumb was included in the request” 的错误。
获取Jenkins生成的crumb值:
-
返回结果类似：
<defaultCrumbIssuer _class="hudson.security.csrf.DefaultCrumbIssuer">
<crumb>068ab0b4e0622b374d8822b22cee8b18</crumb>
<crumbRequestField>Jenkins-Crumb</crumbRequestField>
</defaultCrumbIssuer>以通过Postman”执行一次新的build“为例:
- 选择HTTP POST方法
- 输入URL: http://192.168.1.100:8080/job/email-test/build
- 选择Authorization Type为Basic Auth，并输入Username和Password （Jenkins用户名和密码）
- 在Headers中填入一个新的header:
- Key为
Jenkins-Crumb - Value为上面一步获取到的Jenkins生成的crumb值:
068ab0b4e0622b374d8822b22cee8b18
- Key为
Tips: 测试过Jenkins API官方文档中的wget方法获取到的Jenkins的crumb值，和浏览器直接访问获取到的值不同，并且用wget方法获取到的crumb值在Postman测试失败。