Jenkins REST API 使用指南

1、Rest API的位置

参考文档：https://wiki.jenkins.io/display/JENKINS/Remote+access+API

请求的跟地址

http://hostname:port/jenkins

2、配置步骤

（1）新建一个用户，专门用来做rest api请求，只给必要的权限。

在这个指南中，新建了一个rest的用户。仅仅给指定job的build权限和overall的read权限。

用新建的用户登陆jenkins，在用户配置页获取API Token。见下图

API Token

（2）修改全局安全设置（Configure Global Security）

取消掉“防止跨站点请求伪造”选项。否则使用API跨站点请求的时候，会返回403。

取消防止跨站点请求伪造

（2）client认证方式

client是Basic Auth认证方式。认证信息是第一步中获取到的userId和API Token。有两种形式。

直接将认证信息放到请求URL中

curl -x GET http://rest:00118045a097b9d50ffe1617d9c690c8@192.168.32.180:8080/jenkins/job/rest-test

放到header中

curl -x GET http://192.168.32.180:8080/jenkins/job/rest-test
 -H Authorization: Basic encode_base64(userId:API_Token)

（3）启动带参数job的build

启动build是一个POST请求（即创建一个新的build资源）的形式触发的。参数的传递，是以表单的形式。需要特别指出：

表单的key是json
表单的value是一个json串。在这个json中，参数是都放到一个以parameter为key的ArrayObject中的。

比如启动rest-test job。这个job有两个参数，一个是选择参数（name="choice_param",value in ["a","b"])，另一个是字符串参数(name="string_param")。如下图

Job Param

POST请求：

curl -X POST \
 http://rest:00118045a097b9d50ffe1617d9c690c8@192.168.32.180:8080/jenkins/job/rest-test/build \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'content-type: multipart/form-data;  \
  -F 'json={"parameter":[{"name":"choice_param","value":"a"},{"name":"string_param","value":"ddd"}]}'

可以看到具体的参数也是一个JsonObject。name表示参数的名字，value表示参数的内容，String格式。

{
  "name":"string_param",
  "value":"ddd"
}

如果参数需要传递文件应该如何操作？把rest-test的参数修改下，增加一个文件参数。如下

带文件参数

这种情况下POST的请求如下

curl -X POST \
http://rest:00118045a097b9d50ffe1617d9c690c8@192.168.32.180:8080/jenkins/job/rest-test/build \
  -H 'Postman-Token: d4f3e2b8-8098-4899-8c6c-835c198e74fb' \
  -H 'content-type: multipart/form-data; \
  -F 'json={"parameter":[{"name":"choice_param","value":"a"},{"name":"string_param","value":"ddd"},{"name":"test-file.yaml","file":"file0"}]}' \
  -F file0=@/Users/peng/Desktop/test.yaml

可以看到，仍然是一个form表单的提交。只是需要增加一个key。然后传递文件。在原json key中增加一个file参数。

{
  "name":"FILE_LOCATION_AS_SET_IN_JENKINS",
  "file":"FILE_KEY_AS_SET_IN_FORM"
}

异常说明：
1、选择参数如果携带了不在列表里边的value，会触发错误异常返回。比如这个地方传递

{
  "name":"choice_param",
  "value":"12"
}

会触发异常，表示使用了未在选择列表里边的参数。
2、没有携带必须参数（不含有默认值的参数）也会触发异常
3、携带了没有在jenkins配置的参数也会触发异常
4、文件参数是非必须的。也就是说启动的时候，可以不携带文件参数，jenkins并不会立刻返回异常
5、传递的文件后缀名不需要和location_set_in_jenkins中的设置相同。jenkins会自动重命名成jenkins中的设置

最后编辑于：2018.04.20 14:10:45