Jenkins 常用 REST API介紹(Java 客戶端)

candyleer發表於2019-02-23
JenkinsRESTAPIJava客戶端

jenkinsLogo

背景

Jenkins 作為專案構建,持續部署必不可少的工具,如何使用程式或者指令碼來控制構建流程成為本文研究的內容.

預設情況下,安裝好Jenkins後,/api路徑下面有一些基本 api 的介紹,可供參考,但是不是很直觀,沒有羅列出 api 介面.

本文使用的 jenkins-java 客戶端是:

<dependency>
	<groupId>com.offbytwo.jenkins</groupId>
	<artifactId>jenkins-client</artifactId>
	<version>0.3.7</version>
</dependency>
複製程式碼

假設 jenkins 部署地址為: http://localhost:8080

本文用到的 api:

名稱 API
建立 Job POST http://localhost:8080/createItem/api/json?name=xxx
更新 Job POST http://localhost:8080/job/{job_name}/config.xml/api/json
獲取 Job GET http://localhost:8080/job/{job_name}/api/json
獲取 JobXml GET http://localhost:8080/job/{job_name}/config.xml/api/json
建立 Build POST http://localhost:8080/job/{job_name}/build/api/json
獲取 QueueItem GET http://localhost:8080/queue/item/17/api/json
獲取 Build資訊 GET http://localhost:8080/job/test/6/api/json
獲取TXT日誌 GET http://localhost:8080/job/test/{build_number}/logText/progressiveText/api/json
獲取 Html 日誌 GET http://localhost:8080/job/test/{build_number}/logText/progressiveHtml/api/json

建立 Job API

jenkins 的配置都是靠 xml 的格式落地的,所以配置其實都是 xml 的形式.

POST http://localhost:8080/createItem/api/json?name=xxx
複製程式碼

將建立需要的 config.xml也用請求傳入到服務端,既可以建立成功.

如何知道 config.xml應該如何編寫呢?

  • 可以在 jenkins 收工建立一個需要的專案,然後編輯完成後,到 jenkins 工作目錄下 找到 jobs/{job_name}/config.xml 用他作為模板來書寫你需要的模板.
  • 通過獲取 xml 的 api 來獲取
GET http://localhost:8080/job/{job_name}/config.xml/api/json
複製程式碼

Java Client

jenkinsServer.createJob("auto_test_job", replacedText, true);
String xml = jenkinsServer.getJobXml("auto_test_job");
複製程式碼

修改 Job API

修改 job 也是修改xml.

POST http://localhost:8080/job/{job_name}/config.xml/api/json
複製程式碼

config.xml的內容傳入到 body 中,contentType 設定為text/xml

Java Client

 jenkinsServer.updateJob("auto_test_job", replacedText, true);
複製程式碼

構建 Build API

根據 job 名稱獲取 Job

GET http://localhost:8080/job/{job_name}/api/json 
複製程式碼

新的構建

POST http://localhost:8080/job/{job_name}/build/api/json 
複製程式碼

提交到伺服器成功後返回一個類似於佇列ID的東西,因為是非同步構建,那麼要獲取構建的狀態,就需要,用這個佇列 id去進一步的獲取. 例如:

 $ curl -v  -XPOST http://localhost:8080/job/test/build/api/json
*   Trying ::1...
* TCP_NODELAY set
* Connected to localhost (::1) port 8080 (#0)
> POST /job/test/build/api/json HTTP/1.1
> Host: localhost:8080
> User-Agent: curl/7.54.0
> Accept: */*
>
< HTTP/1.1 201 Created
< Date: Sat, 05 Jan 2019 08:33:45 GMT
< X-Content-Type-Options: nosniff
< Location: http://localhost:8080/queue/item/17/
< Content-Length: 0
< Server: Jetty(9.4.z-SNAPSHOT)
<
* Connection #0 to host localhost left intact
複製程式碼

上面的Location: http://localhost:8080/queue/item/17/就是返回的佇列資訊,下面的 queueItem 獲取就是依賴這個.

根據 QueueId 獲取 QueueItem

GET http://localhost:8080/queue/item/17/api/json 
複製程式碼

舉例

$ curl  http://localhost:8080/queue/item/17/api/json\?pretty\=true
{
  "_class" : "hudson.model.Queue$LeftItem",
  "actions" : [
    {
      "_class" : "hudson.model.CauseAction",
      "causes" : [
        {
          "_class" : "hudson.model.Cause$UserIdCause",
          "shortDescription" : "由使用者 anonymous 啟動",
          "userId" : null,
          "userName" : "anonymous"
        }
      ]
    }
  ],
  "blocked" : false,
  "buildable" : false,
  "id" : 17,
  "inQueueSince" : 1546677225670,
  "params" : "",
  "stuck" : false,
  "task" : {
    "_class" : "hudson.maven.MavenModuleSet",
    "name" : "test",
    "url" : "http://localhost:8080/job/test/",
    "color" : "blue"
  },
  "url" : "queue/item/17/",
  "why" : null,
  "cancelled" : false,
  "executable" : {
    "_class" : "hudson.maven.MavenModuleSetBuild",
    "number" : 6,
    "url" : "http://localhost:8080/job/test/6/"
  }
}
複製程式碼

獲取到的 QueueItem 上面就知道這個 item 有沒有被 build 執行,比較關鍵的引數就是executable,如果executable不為空,就說明 jenkins 已經在對這個任務進行 build 的了,build 的編號就是number,也就是我們在 jenkins 頁面上看到的編號.你可以通過url欄位的值在瀏覽器開啟.

獲取 Build 詳情

既然開始了 build,我們就可以獲取 build 的詳細資訊.

curl http://localhost:8080/job/test/6/api/json\?pretty\=true
{
  ...
  "building" : false,
  "description" : null,
  "displayName" : "#6",
  "duration" : 13631,
  "estimatedDuration" : 17999,
  "executor" : null,
  "fullDisplayName" : "test #6",
  "id" : "6",
  "keepLog" : false,
  "number" : 6,
  "queueId" : 17,
  "result" : "SUCCESS",
  "timestamp" : 1546677234794,
  "url" : "http://localhost:8080/job/test/6/",
  "builtOn" : "",
 ...
}
複製程式碼

從返回結果可以看到 是否還在 build:"building" : false,,如果 build 結束狀態就在:"result" : "SUCCESS",

獲取Build日誌

文字:

GET http://localhost:8080/job/test/{build_number}/logText/progressiveText/api/json
複製程式碼

html

GET http://localhost:8080/job/test/{build_number}/logText/progressiveHtml/api/json
複製程式碼

Java Client


JobWithDetails job = jenkinsServer.getJob(jenkinsJob);
...
 QueueReference reference = job.build( true);
...
QueueItem queueItem = jenkinsServer.getQueueItem(new QueueReference(queuePart));
...
Build build = jenkinsServer.getBuild(queueItem);
...
BuildWithDetails details = build.details();
BuildResult result = details.getResult();
...
String logs =  details.getConsoleOutputText();
複製程式碼

相關文章