Jenkins API 中文文档

桃扇骨 2022-05-21 01:48 711阅读 0赞

*  Jenkins API 文档与学习路线图
    
     *  官方文档
     *  学习路线图
     *  API格式
     *  API在线文档
     *  过滤返回数据
     *  安全
     *  API调试工具
     *  API封装
     *  参考文档

# Jenkins API 文档与学习路线图 #

## 官方文档 ##

*  [https://wiki.jenkins.io/display/JENKINS/Remote+access+API][https_wiki.jenkins.io_display_JENKINS_Remote_access_API]

## 学习路线图 ##

整理了Jenkins API 学习路线图如下：

![Jenkins API 学习路线图][Jenkins API]

下面来说明Jenkins API学习路线图的各个部分。

## API格式 ##

Jenkins API支持以下3种格式：

*  XML
 *  JSON并支持JSONP跨域访问
 *  Python

## API在线文档 ##

Jenkins API没有统一的入口，而是采用“…/api/” 的REST API样式，其中”…” 表示Jenkins资源的URL。

常见的Jenkins资源包括：站点（实例）、Job和Build。

上面的学习路线图中只是列出了不同级别API的常用API，具体用法请参考Jenkins API在线文档：

**站点API文档 (例子)**

# JENKINS_URL/api/
    http://192.168.37.100:8080/api/

**Job API文档 （例子）**

# JENKINS_URL/job/JOB_NAME/api/
    http://192.168.37.100:8080/job/email-test/api/

**Build API文档 （例子）**

# JENKINS_URL/job/JOB_NAME/lastSucessfulBuild/api/
    http://192.168.37.100:8080/job/email-test/lastSuccessfulBuild/api/

## 过滤返回数据 ##

Jenkins API将Jenkins资源模型抽象为树形结构，可以通过tree来指定返回Jenkins资源的层次。

具体用法请参考Jenkins API 在线文档。

## 安全 ##

在调用Jenkins API 时需要以HTTP Basic Auth验证方式提供用户名和密码。

另外，在Jenkins 2之后默认开启CSRF protection （跨域访问伪造保护），对有些Jenkins API的调用还需要提供Jenkins-Crumb；否则会出现”403 No valid crumb was included in the request“ 的错误。

**获取Jenkins生成的crumb值**:

1.  通过浏览器直接打开：[http://192.168.37.100:8080/crumbIssuer/api/xml][http_192.168.37.100_8080_crumbIssuer_api_xml]
2.  返回结果类似：
    
        <defaultCrumbIssuer _class="hudson.security.csrf.DefaultCrumbIssuer">
        <crumb>068ab0b4e0622b374d8822b22cee8b18</crumb>
        <crumbRequestField>Jenkins-Crumb</crumbRequestField>
        </defaultCrumbIssuer>

**以通过Postman”执行一次新的build“为例:**

1.  选择HTTP POST方法
2.  输入URL: [http://192.168.37.100:8080/job/email-test/build][http_192.168.37.100_8080_job_email-test_build]
3.  选择Authorization Type为Basic Auth，并输入Username和Password （Jenkins用户名和密码）
4.  在Headers中填入一个新的header:
    
     *  Key为Jenkins-Crumb
     *  Value为上面一步获取到的Jenkins生成的crumb值

> Tips: 测试过Jenkins API官方文档中的wget方法获取到的Jenkins的crumb值，和浏览器直接访问获取到的值不同，并且用wget方法获取到的crumb值在Postman测试失败。

Jenkins CSRF protection参考文档：

*  [https://issues.jenkins-ci.org/browse/JENKINS-42200][https_issues.jenkins-ci.org_browse_JENKINS-42200]
 *  [https://support.cloudbees.com/hc/en-us/articles/219257077-CSRF-Protection-Explained][https_support.cloudbees.com_hc_en-us_articles_219257077-CSRF-Protection-Explained]

## API调试工具 ##

推荐使用 [Postman][] 来调试Jenkins API, 当然你可以使用命令行工具wget或curl。

## API封装 ##

Jenkins API 官网上推荐了几个对Jenkins API封装的框架：

**Python API 封装**

*  [JenkinsAPI][]
 *  [Python-Jenkins][]

**Ruby API 封装：**

*  [Jenkins API Client][]

**Java API 封装：**

*  [jenkins-rest][]
 *  [jclouds-toolkit][]

## 参考文档 ##

*  [https://www.cnblogs.com/zjsupermanblog/archive/2017/07/26/7238422.html][https_www.cnblogs.com_zjsupermanblog_archive_2017_07_26_7238422.html]

[https_wiki.jenkins.io_display_JENKINS_Remote_access_API]: https://wiki.jenkins.io/display/JENKINS/Remote+access+API
[Jenkins API]: /images/20220521/1b6b4a90b6834b4b82922422799113cd.png
[http_192.168.37.100_8080_crumbIssuer_api_xml]: http://192.168.37.100:8080/crumbIssuer/api/xml
[http_192.168.37.100_8080_job_email-test_build]: http://192.168.37.100:8080/job/email-test/build
[https_issues.jenkins-ci.org_browse_JENKINS-42200]: https://issues.jenkins-ci.org/browse/JENKINS-42200
[https_support.cloudbees.com_hc_en-us_articles_219257077-CSRF-Protection-Explained]: https://support.cloudbees.com/hc/en-us/articles/219257077-CSRF-Protection-Explained
[Postman]: https://www.getpostman.com/
[JenkinsAPI]: http://pypi.python.org/pypi/jenkinsapi
[Python-Jenkins]: https://pypi.python.org/pypi/python-jenkins/
[Jenkins API Client]: https://rubygems.org/gems/jenkins_api_client
[jenkins-rest]: https://github.com/cdancy/jenkins-rest
[jclouds-toolkit]: https://jclouds.apache.org/
[https_www.cnblogs.com_zjsupermanblog_archive_2017_07_26_7238422.html]: https://www.cnblogs.com/zjsupermanblog/archive/2017/07/26/7238422.html