Jenkins基础：API：1：使用方式简介

Jenkins提供了远程访问应用编程接口（Remote Access API）的方式来对于Job等进行控制。这篇文章整理一下常见的使用方式。

应用场景

为什么需要使用API方式进行Job的创建？自然是有很多原因的，比如：

需要创建的Jenkins的Job非常之多，大多又呈现有规律的方式，所以Job的创建成为了一个繁琐而又需要频繁操作的任务。这种场景下，使用API结合脚本进行自动化可以提高效率，降低手工错误的几率。
如果需要动态的生成Jenkins的Job，比如需要根据一定的中间结果在某个触发点进行自动生成，再比如生成的Job需要使用的参数也是动态运行阶段才能取到的值的场景下，事前手工创建Jenkins就不太可行了。
产品或者相关的功能，不希望用户直接使用Jenkins，而将Jenkins作为背后的执行引擎的场景，这种情况下自然也是使用API进行Job的创建更为妥切。
…

Jenkins在设计的时候就考虑到了Restful的API的实现，可以通过如下三种方式对Jenkins中的对象进行访问控制以达到相关的目的

可以使用xml方式进行API的使用，这种方式的优势在于可以使用强大的xpath特性进行相关的访问控制。

使用JSON方式进行操作，因为json基本上已经是应用之间数据交换的准标准格式之一，这种方式比较方便Javascript或者和其他应用的集成。

可以通过python-jenkins库对Jenkins进行控制操作。此库对Jenkins的API进行了进一步的包装，使用起来更加方便，但是一般需要安装python-jenkins，并通过python脚本的执行来达到集成的方式。可以较为方便的实现如下功能：

所以可以看到常见对于Job和构建操作的需求大多已被包含，除此之外，还能做到如下的一些对于Jenkins的操作，所以对于权限的控制显得非常重要。

更加具体的功能可以参看如下链接的说明：

这种方式功能较为强大，依赖也非常明显。

从上述对于python-jenkins的介绍中可以看到，通过API可以实现如下功能：

在实际的实践中，对于Jenkins Job的增删改查操作以及执行构建或取消构建等常见操作均可实现，至于需要使用哪种方式，开发者则需要根据自己的情况进行选择。

操作	HTTP动作	URI	使用示例
创建Job	POST	/createItem	/createItem?name=Job名称
拷贝Job	POST	/createItem	/createItem?name=Job名称&mode=copy&from=源Job名称
起用Job	POST	/job/job名称/enable	/job/job名称/enable
禁用Job	POST	/job/job名称/disable	/job/job名称/disable
删除Job	POST	/job/job名称/doDelete	/job/job名称/doDelete
获取Job描述信息	GET	/job/job名称/description	/job/job名称/description
更新Job描述信息	POST	/job/job名称/description	/job/job名称/description
执行Job	POST	/job/job名称/build	/job/job名称/build
获取Job的API信息	GET	/job/job名称/api	/job/job名称/api
停止执行中的Job	POS	/job/Job名称/构建序号/stop	/job/Job名称/构建序号/stop
停止尚未执行的Job	POS	/queue/cancelItem?id=队列等待序号/queue/cancelItem?id=队列等待序号

返回信息可以指定为xml/json/python方式，以/api为例，使用方式如下所示。

xml格式返回api信息示例：/api/xml

json格式返回api信息示例：/api/json

python格式返回api信息示例：/api/python

如果相关的操作，比如创建Job需要相应的用户权限才能执行的情况下，通过API执行此操作自然也需要进行设定。Jenkins的API支持如下两种方式进行认证：

以curl客户端访问为例，通过如下方式进行相关的用户认证

curl -u 用户名:用户密码 http://Jenkins服务的URL/具体操作的URI

以curl客户端访问为例，通过如下方式进行相关的用户认证

curl -u 用户名:用户Token http://Jenkins服务的URL/具体操作的URI

注：此处使用的Token为在Jenkins中可以查询到的(用户的配置页面可以查询到的API Token即为此处认证所使用的信息，而Token的修改也可以在此页面通过点击Change API Token按钮来进行)
Jenkins基础：API：1：使用方式简介