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. 返回結果類似：

   <defaultCrumbIssuer _class="hudson.security.csrf.DefaultCrumbIssuer"
    
   >
   <crumb>068ab0b4e0622b374d8822b22cee8b18</crumb>
   <crumbRequestField>Jenkins-Crumb</crumbRequestField>
   </defaultCrumbIssuer>

以通過Postman”執行一次新的build“為例:

1. 選擇HTTP POST方法

2. 選擇Authorization Type為Basic Auth，並輸入Username和Password （Jenkins使用者名稱和密碼）

3. 在Headers中填入一個新的header:

   • Key為Jenkins-Crumb
   • Value為上面一步獲取到的Jenkins生成的crumb值

Tips: 測試過Jenkins API官方文件中的wget方法獲取到的Jenkins的crumb值，和瀏覽器直接訪問獲取到的值不同，並且用wget方法獲取到的crumb值在Postman測試失敗。

Jenkins CSRF protection參考文件：

API除錯工具

推薦使用 Postman 來除錯Jenkins API, 當然你可以使用命令列工具wget或curl。

API封裝

Jenkins API 官網上推薦了幾個對Jenkins API封裝的框架：

Python API 封裝

Ruby API 封裝：

Java API 封裝：

參考文件