Jenkins API接入指南

小咪咪 2023-10-03 15:27 40阅读 0赞

## 文档 ##

API文档：[https://www.jenkins.io/doc/book/using/remote-access-api/][https_www.jenkins.io_doc_book_using_remote-access-api]  
可用API列表：[https://ci.jenkins.io/api/][https_ci.jenkins.io_api]

说明：**API格式为 `/.../api/`，"`...`" 就是要访问的对象。** 另外，**API的响应体支持 `xml` 和 `json` 格式，在API的末尾指定**，也就是说，当你需要json格式返回时，则访问`/.../api/json`，当需要xml格式返回时，则访问`/.../api/xml`。

**注意**：文档中提到了Jenkins的很多对象都暴露了API接口，但是并没有列举所有的API接口，所以，**很多时候在文档中找不到需要的API接口时，则需要借助Jenkins自带的Web管理端来得知。** 举个例子：你想要获取Jenkins的用户列表，发现文档中并没有用户相关的API，但是在Web管理端中有用户列表的页面，其url为：`http://ip:port/asynchPeople`。按照API的定义格式，拼接上`/api/json`得到：`http://ip:port/asynchPeople/api/json`，此url即为用户列表的API接口。（这个规则一般适用于查询类的接口，如果是新增、更新等接口一般是和Web管理端发送的请求路径一致的）

## 认证机制 ##

### HTTP BASIC 认证方式 ###

> [https://www.jenkins.io/doc/book/using/remote-access-api/\#RemoteaccessAPI-RemoteAPIandsecurity][https_www.jenkins.io_doc_book_using_remote-access-api_RemoteaccessAPI-RemoteAPIandsecurity]

`HTTP Basic`认证（即Header头添加 `Authorization: Basic {token}`）

token的来源：使用 `:` 将`帐号`和`个人API Token` 拼接，再通过Base64编码，即得到的字符串。  
API Token来源：登录web页面 -> 右上角个人 -> 设置 -> API Token

### Cookie + CSRF Token 方式 ###

Jenkins自带的Web管理端就是使用此认证方式。参考前端发送的请求。

*  Cookie  
    通过登录接口获取，登录接口为：`/j_acegi_security_check`  
    Cookie的key为`JSESSIONID.xxx`
 *  CSRF Token  
    文档：[https://www.jenkins.io/doc/book/security/csrf-protection/][https_www.jenkins.io_doc_book_security_csrf-protection]  
    获取接口：`/crumbIssuer/api/json`  
    CSRF Token的key为 `Jenkins-Crumb`，**该参数位于Query**。示例：`/asynchPeople/api/json?Jenkins-Crumb=xxx`

## Java 客户端库 ##

### jenkins-rest ###

https://github.com/cdancy/jenkins-rest

### java-client-api ###

https://github.com/jenkinsci/java-client-api

[https_www.jenkins.io_doc_book_using_remote-access-api]: https://www.jenkins.io/doc/book/using/remote-access-api/
[https_ci.jenkins.io_api]: https://ci.jenkins.io/api/
[https_www.jenkins.io_doc_book_using_remote-access-api_RemoteaccessAPI-RemoteAPIandsecurity]: https://www.jenkins.io/doc/book/using/remote-access-api/#RemoteaccessAPI-RemoteAPIandsecurity
[https_www.jenkins.io_doc_book_security_csrf-protection]: https://www.jenkins.io/doc/book/security/csrf-protection/