Jenkins - Remote Access 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說明。

一般情況下,都會支持如下三種訪問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