Jenkins REST API 使用指南

0X00 寫在前面

作為持續交付開源工具中最出名的一個，Jenkins 在業界使用範圍很廣。但筆者了解到絕大多數使用者都在考慮將 Jenkins 作為其持續交付系統的一個元件來使用，而恰好 Jenkins 也提供了強大的 REST API。因此，了解清楚 Jenkins REST API 的來龍去脈並使用好它，是一件至關重要的事情。

0X01Jenkins REST API 是怎麼弄出來的？

在 Jenkins Plugin 基礎開發入門 中，筆者詳細介紹了在設計上的三大主要概念，它們分別是：Stapler，持久化和外掛。

其中，Stapler 技術的引入使得 Jenkins 可以自動為應用程式物件系結 URL，並建立直觀的 URL 層次結構。

所以，通過該項技術的引入，我們可以快速存取對應的Job及其相應資源。而這些資源包含的內容有哪些呢？可以說 Jenkins 中幾乎所有的物件，包含 Jenkins，Job，Build，Computer 等等，都是可以通過具體的 URL 進行存取和控制的。

0X02 如何獲取 Jenkins REST API？

大家先來看看 Jenkins 自帶的這句文件：

Many objects of Jenkins provide the remote access API. They are available at /jenkins/…/api/ where “…” portion is the object for which you’d like to access.

在 Jenkins 設計之時就已經支援了讓我們通過 REST API 的方式拿到所有的物件的介面。

此外，再來看這一段：

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())

所以，物件的資料也可以通過固定的 URL 進行存取或者查詢，且均支援三種形式：

1. XML: /jenkins/…/api/xml
2. JSON: /jenkins/…/api/json
3. PYTHON:/jenkins/…/api/python

為了加深大家的主觀認知，大家可以看看 Jenkins 官方搭建的 Jenkins 的 以下三個 URL：

Jenkins on Jenkins

API in root URL

Data in root URL

0X03 常用 Jenkins REST API 列表

Job - CRUD

Create a Job with config.xml

curl -X POST "http://user:password@<Jenkins_URL>/createItem?name=<Job_Name>" --data-binary "@newconfig.xml" -H "Content-Type: text/xml"

Retrieve/Fetch a Job’s config.xml

curl -X GET http://user:password@<Jenkins_URL>/job/<Job_Name>/config.xml

Update a Job’s config.xml

curl -X POST http://user:password@<Jenkins_URL>/job/<Job_Name>/config.xml --data-binary "@mymodifiedlocalconfig.xml"

Delete a job

curl -X POST http://user:password@<Jenkins_URL>/job/<Job_Name>/doDelete

Build - CONTROL

Perform a Build

curl -X POST http://user:password@<Jenkins_URL>/job/<Job_Name>/build

如果該 build 使用引數化構建，則需用如下方式進行構建：

curl -X POST http://user:password@<Jenkins_URL>/job/JOB_NAME/build --data --data-urlencode json=<Parameters>

Retrieve a Build

curl -X GET http://user:password@<Jenkins_URL>/queue/api/json?<Filter_Condition>

例如，可以按照如下的方式查詢名字為 name 的 task :

curl -X GET http://user:password@<Jenkins_URL>/queue/api/json?tree=items[id,task[name]]

或者可以直接按如下方式存取 Job 最近一次構建的詳情：

curl -X GET http://user:password@<Jenkins_URL>/lastBuild/api/json

Stop a Build

curl -X POST http://user:password@<Jenkins_URL>/job/<Job_Name>/<Build_Number>/stop

或者

curl -X POST http://user:password@<Jenkins_URL>/queue/cancelItem?id=<Queue_Item>

區域網內利用GitLab+Jenkins自動生成GitBook並行布(Nginx)  http://www.linuxidc.com/Linux/2016-05/131136.htm

Linux+Git+Maven+Jenkins+Neuxs自動化編譯環境搭建 http://www.linuxidc.com/Linux/2016-02/128652.htm

在CentOS 7上安裝Jenkins  http://www.linuxidc.com/Linux/2016-11/137548.htm

CentOS6安裝Jenkins  http://www.linuxidc.com/Linux/2016-05/131365.htm

使用Jenkins設定Git+Maven的自動化構建 http://www.linuxidc.com/Linux/2016-02/128641.htm

Jenkins+Maven+Git搭建持續整合和自動化部署的設定手記 http://www.linuxidc.com/Linux/2015-06/118606.htm

Jenkins的分散式構建及部署——節點  http://www.linuxidc.com/Linux/2015-05/116903.htm