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。见下图




jenkins job build并发执行 jenkins build with parameter_json


API Token

(2)修改全局安全设置(Configure Global Security)

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


jenkins job build并发执行 jenkins build with parameter_表单_02


取消防止跨站点请求伪造

(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")。如下图


jenkins job build并发执行 jenkins build with parameter_API_03


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的参数修改下，增加一个文件参数。如下


jenkins job build并发执行 jenkins build with parameter_json_04


带文件参数

这种情况下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中的设置