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@/createItem?name=" --data-binary "@newconfig.xml" -H "Content-Type: text/xml"

Retrieve/Fetch a Job's config.xml

curl -X GET http://user:password@/job//config.xml

Update a Job's config.xml

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

Delete a job

curl -X POST http://user:password@/job//doDelete

Build - CONTROL

Perform a Build

curl -X POST http://user:password@/job//build

如果该 build 使用参数化构建，则需用如下方式进行构建：

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

Retrieve a Build

curl -X GET http://user:password@/queue/api/json?

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

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

或者可以直接按如下方式访问 Job 最近一次构建的详情：

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

Stop a Build

curl -X POST http://user:password@/job///stop

或者

curl -X POST http://user:password@/queue/cancelItem?id=