Jenkins - API详解

1 - Jenkins API

• https://www.jenkins.io/doc/book/using/remote-access-api/
• https://wiki.jenkins.io/display/JENKINS/Remote+access+API

Jenkins本身支持丰富的API接口，通过调用接口，基本可以实现所有需要的功能，包括获取、触发、删除Job等。
Jenkins的Remote API以REST-like的形式进行提供，通过对特定的API执行相关请求即可。
可以通过curl、wget和postman等工具模拟请求和调试。

2 - 查看API文档

Jenkins API没有统一的入口，而是采用…/api/的REST API样式，其中”…” 表示Jenkins资源的URL。
常见的Jenkins资源包括：站点（实例）、Job和Build。
也就是说，可以通过不同级别的URL地址查看到当前的API信息，例如http://<IP:Port or URL>/api查看当前站点所有相关的API说明。
例如：

• 插件管理: http://<Jenkins-Server-Address>/pluginManager/api/
• 节点管理: http://<Jenkins-Server-Address>/computer/api/
• 认证管理: http://<Jenkins-Server-Address>/credentials/api/

一般情况下,都会支持如下三种访问Jenkins API的方式

• JSON API
• XML API
• Python API

Many objects of Jenkins provide the remote access API. They are available at /blueocean/.../api/ where "..." portion is the object for which you'd like to access.

XML API
Access data exposed in HTML as XML for machine consumption. Schema is also available.
You can also specify optional XPath to control the fragment you'd like to obtain (but see below). For example, ../api/xml?xpath=/*/*[0].

For XPath that matches multiple nodes, you need to also specify the "wrapper" query parameter to specify the name of the root XML element to be create so that the resulting XML becomes well-formed.

Similarly exclude query parameter can be used to exclude nodes that match the given XPath from the result. This is useful for trimming down the amount of data you fetch (but again see below). This query parameter can be specified multiple times.

XPath filtering is powerful, and you can have it only return a very small data, but note that the server still has to build a full DOM of the raw data, which could cause a large memory spike. To avoid overloading the server, consider using the tree parameter, or use the xpath parameter in conjunction with the tree parameter. When used together, the result of the tree parameter filtering is built into DOM, then the XPath is applied to compute the final return value. In this way, you can often substantially reduce the size of DOM built in memory.

JSON API
Access the same data as JSON for JavaScript-based access. tree may be used.
Python API
Access the same data as Python for Python clients. This can be parsed into Python object as eval(urllib.urlopen("...").read()) and the resulting object tree is identical to that of JSON. However, when you do this, beware of the security implication. If you are connecting to a non-trusted Jenkins, the server can send you malicious Python programs.

In Python 2.6 or later you can safely parse this output using ast.literal_eval(urllib.urlopen("...").read())

For more information about remote API in Jenkins, see the documentation.

3 - 一些使用方法

3.1 站点API

- 站点支持的API： http://<Jenkins-Server-Address>/api
- 查询到站点中所有的job信息（JSON格式）： http://<Jenkins-Server-Address>/api/json?pretty=true
- 查询到站点中所有的job信息（XML格式）： http://<Jenkins-Server-Address>/api/xml
- 通过tree进行过滤： http://<Jenkins-Server-Address>/api/json?pretty=true&tree=jobs[name[*]]
- 重启站点： http://<Jenkins-Server-Address>/restart
- 安全重启站点： http://<Jenkins-Server-Address>/safeRestart

3.2 获取Job相关信息

- 当前的api说明： http://<Jenkins-Server-Address>/job/<Job-Name>/api/
- JSON格式： http://<Jenkins-Server-Address>/job/<Job-Name>/api/json?pretty=true
- XML格式： http://<Jenkins-Server-Address>/job/<Job-Name>/api/xml

3.3 获取Job的指定信息（JSON格式）

- 获取Job的builds节点信息： http://<Jenkins-Server-Address>/job/<Job-Name>/api/json?pretty=true&tree=builds[*]
- 获取Job的builds节点下displayName节点信息： http://<Jenkins-Server-Address>/job/<Job-Name>/api/json?pretty=true&tree=builds[displayName]
- 获取Job的builds节点下指定displayName节点信息： http://<Jenkins-Server-Address>/job/<Job-Name>/api/json?pretty=true&tree=builds[displayName]{x,y}
- 获取两个相关的节点信息，例如： http://<Jenkins-Server-Address>/job/<Job-Name>/api/json?pretty=true&tree=builds[displayName]{3,5},url[*]

3.4 获取指定Build相关信息

- JSON格式： http://<Jenkins-Server-Address>/job/<Job-Name>/<Build-Number>/api/json?pretty=true
- XML格式： http://<Jenkins-Server-Address>/job/<Job-Name>/<Build-Number>/api/xml
- 获取指定信息： http://<Jenkins-Server-Address>/job/<Job-Name>/<Build-Number>/api/json?pretty=true&&tree=<filter>

3.5 通过curl工具

- 获取最近的buildNumber： `curl --silent http://<Jenkins-Server-Address>/job/<Job-Name>/lastBuild/buildNumber`
- 获取最近稳定的buildNumber：`curl --silent http://<Jenkins-Server-Address>/job/<Job-Name>/lastStableBuild/buildNumber`
- 获取最近成功的buildNumber：`curl --silent http://<Jenkins-Server-Address>/job/<Job-Name>/lastSuccessfulBuild/buildNumber`
- 获取最近失败的buildNumber：`curl --silent http://<Jenkins-Server-Address>/job/<Job-Name>/lastFailedBuild/buildNumber`

3.6 对Job的一些操作

- 获取（get方法）和更新（post方法）Job的description信息： http://<Jenkins-Server-Address>/job/<Job-Name>/description
- 获取（get方法）和更新（post方法）Job的详细配置信息： http://<Jenkins-Server-Address>/job/<Job-Name>/config.xml
- 不带参数直接执行（post方法）： http://<Jenkins-Server-Address>/job/<Job-Name>/build
- 带参数执行（post方法），例如： http://<Jenkins-Server-Address>/job/<Job-Name>/buildWithParameters?token=testuser\&AAA='test123'\&BBB='test789'
- 禁用（post方法）指定的job： http://<Jenkins-Server-Address>/job/<Job-Name>/disable
- 启用（post方法）指定的job： http://<Jenkins-Server-Address>/job/<Job-Name>/enable
- 删除（post方法）指定的job： http://<Jenkins-Server-Address>/job/<Job-Name>/doDelete

4 - Python API wrappers

4.1 jenkinsapi

• Pypi：https://pypi.org/project/jenkinsapi/
• Github：https://github.com/salimfadhley/jenkinsapi
• Docs：https://jenkinsapi.readthedocs.io/en/latest/

4.2 python-jenkins

• Pypi：https://pypi.org/project/python-jenkins/
• HomePage：https://opendev.org/jjb/python-jenkins
• Docs：https://python-jenkins.readthedocs.io/en/latest/

5 - Sample

通过API远程触发job

5.1 创建API token

在user的configure页面，创建API token，然后记录下token name对应的密文，保存设置并退出。

5.2 配置job的触发条件

5.3 配置权限

Job和所在project对匿名用户开放build权限

5.4 配置测试参数

5.5 远程触发job

这里是通过curl命令

# 方式-1：cookie
crumb=$(curl -c cookies.txt -s 'https://<JENKINS_USER_ID>:1110e7943aeaa4316950dc423f5b15b114@<JENKINS_SERVER_URL>/crumbIssuer/api/xml?xpath=concat(//crumbRequestField,":",//crumb)')
curl --cookie cookies.txt --user "<JENKINS_USER_ID>:1110e7943aeaa4316950dc423f5b15b114" -H $crumb -X POST -s https://<JENKINS_JOB_URL>/buildWithParameters?token=testuser

# 方式-2：https dns
crumb=$(curl -k -u "<JENKINS_USER_ID>:1110e7943aeaa4316950dc423f5b15b114" 'https://<JENKINS_SERVER_URL>/crumbIssuer/api/xml?xpath=concat(//crumbRequestField,":",//crumb)')
curl  -u "<JENKINS_USER_ID>:1110e7943aeaa4316950dc423f5b15b114" -H $crumb -X POST -s https://<JENKINS_JOB_URL>/buildWithParameters?token=testuser

# 方式-3：https dns Parameters
crumb=$(curl -k -u "<JENKINS_USER_ID>:1110e7943aeaa4316950dc423f5b15b114" 'https://<JENKINS_SERVER_URL>/crumbIssuer/api/xml?xpath=concat(//crumbRequestField,":",//crumb)')
curl  -u "<JENKINS_USER_ID>:1110e7943aeaa4316950dc423f5b15b114" -H $crumb -X POST -s https://<JENKINS_JOB_URL>/buildWithParameters?token=testuser\&TEST_ONE='test123'\&TEST_TWO='test789'

# 方式-4：http ip:port
crumb=$(curl -k -u "<JENKINS_USER_ID>:1110e7943aeaa4316950dc423f5b15b114" 'http://<IP:PORT>/crumbIssuer/api/xml?xpath=concat(//crumbRequestField,":",//crumb)')
curl  -u "<JENKINS_USER_ID>:1110e7943aeaa4316950dc423f5b15b114" -H $crumb -X POST -s http://<IP:PORT>/<JOB_PATH>/buildWithParameters?token=testuser

5.6 查看结果

直接触发

带参数触发

6 - References

• https://blog.csdn.net/nklinsirui/article/details/80832005
• https://segmentfault.com/a/1190000018939447
• https://blog.csdn.net/liumiaocn/category_8598907.html