Jenkins 的 REST API
一、简介
Jenkins API 是一个强大的接口,允许用户以编程方式访问和控制 Jenkins 服务。通过这个 API,您可以远程执行许多在 Jenkins 用户界面中可用的任务,如获取构建信息、管理作业、触发构建等。Jenkins 提供了几种不同格式的 API,包括 XML、JSON 和 Python 可解析的 Python Remote Access API。
Jenkins API 主要功能
-
作业管理:通过 API,您可以创建、配置和删除作业(Job)。
-
构建触发:可以远程触发新的构建过程。
-
获取构建信息:您可以检索特定构建的详细信息,如构建状态、构建日志、测试结果等。
-
节点管理:允许您获取 Jenkins 节点(代理)的信息,甚至可以创建和删除节点。
-
用户管理:可以通过 API 管理用户账户和权限。
-
插件管理:允许您远程安装、更新或删除 Jenkins 插件。
使用 Jenkins API
要使用 Jenkins API,您通常需要:
- Jenkins URL:Jenkins 服务器的地址。
- API Token/用户名和密码:用于身份验证的凭据。建议使用 API Token 而非密码。
示例:获取 Jenkins 作业列表
以获取 Jenkins 作业列表的 JSON 数据为例,您可以使用以下 URL:
http://[jenkins-server]/api/json?pretty=true
这里 [jenkins-server]
是您的 Jenkins 服务器地址。如果 Jenkins 需要身份验证,您需要提供 API Token 或用户名和密码。
示例:调用Jenkins的REST API添加全局凭据
在Postman中调用Jenkins的REST API添加全局凭据,可以按照以下步骤进行操作:
- 打开Postman,并创建一个新的请求。
- 在请求的URL栏中输入Jenkins的API地址,例如:http://your-jenkins-url/credentials/store/system/domain/_/createCredentials。
- 在请求的Headers中添加Content-Type为application/x-www-form-urlencoded。
- 在请求的Body中选择"form-data"格式,并添加以下参数:
- name:凭据的名称
- username:用户名
- password:密码
- description:凭据的描述
- json:{“”: “1”, “credentials”: {“scope”: “GLOBAL”, “id”: “global-credentials-id”, “username”: “username”, “password”: “password”, “description”: “description”, “$class”: “com.cloudbees.plugins.credentials.impl.UsernamePasswordCredentialsImpl”}}(将其中的global-credentials-id替换为你自己的全局凭据ID)
- 发送请求,如果一切正常,你将收到一个成功的响应。
请注意,上述步骤中的URL、参数和凭据信息需要根据你自己的Jenkins配置进行相应的修改。
使用 cURL 访问 API
您可以使用 cURL 或任何 HTTP 客户端工具来访问 Jenkins API。例如,使用 cURL 获取 Jenkins 主页的 JSON 数据:
curl -u username:token http://[jenkins-server]/api/json?pretty=true
注意事项
- 访问 Jenkins API 时,确保您的请求遵守了 Jenkins 服务器的访问权限和安全设置。
- 不同的 API 请求可能需要不同的权限。确保使用的 Jenkins 账户具有执行特定请求所需的权限。
- 对于复杂的任务或高级集成,您可能需要结合使用多个 API 请求或处理复杂的 JSON/XML 响应。
Jenkins API 是一个非常有用的工具,用于扩展 Jenkins 的功能和集成 Jenkins 与其他系统或自动化工具。通过编程方式访问 Jenkins,您可以高效地管理和控制 Jenkins 服务,从而实现更高级的自动化和监控。
二、Jenkins Api 环境准备
创建一个有任务运行和查询权限的用户
较老版本的Jenkins操作关闭跨站脚本伪造请求保护,新版本的Jenkins无此选项了
1、获取所有job接口
curl -u USERNAME:PASSWORD “JENKINSURL:PORT/api/json?pretty=true”
[root@mylinux1 ~]# curl -u admin:admin "http://192.168.22.3:8080/api/json?retty=true"
2、获取所有job名字接口
[root@mylinux1 ~]# curl -u admin:admin -g "http://192.168.22.3:8080/api/json?pretty=true&tree=jobs[name]"{"_class" : "hudson.model.Hudson","jobs" : [{"_class" : "hudson.model.FreeStyleProject","name" : "build_no_params"},{"_class" : "hudson.model.FreeStyleProject","name" : "build_with_params"},{"_class" : "hudson.model.FreeStyleProject","name" : "father_job"},{"_class" : "hudson.model.FreeStyleProject","name" : "first_job"},{"_class" : "hudson.model.FreeStyleProject","name" : "git_demo"
3、获取所有job名字和url接口
[root@mylinux1 ~]# curl -u admin:admin -g "http://192.168.22.3:8080/api/json?pretty=true&tree=jobs[name,url]"{"_class" : "hudson.model.Hudson","jobs" : [{"_class" : "hudson.model.FreeStyleProject","name" : "build_no_params","url" : "http://192.168.22.3:8080/job/build_no_params/"},{"_class" : "hudson.model.FreeStyleProject","name" : "build_with_params","url" : "http://192.168.22.3:8080/job/build_with_params/"},{"_class" : "hudson.model.FreeStyleProject","name" : "father_job","url" : "http://192.168.22.3:8080/job/father_job/"},
三、使用curl调用 获取所有构建队列
curl -u USERNAME:PASSWORD JENKINSURL:PORT/queue/api/json?pretty=true
[root@mylinux1 ~]# curl -u admin:admin "http://192.168.22.3:8080/queue/api/json?pretty=true"
{"_class" : "hudson.model.Queue","discoverableItems" : [],"items" : []
四、使用curl调用 获取Job信息
获取任务所有信息
curl -u USERNAME:PASSWORD JENKINSURL:PORT/job/JOBNAME/api/json?pretty=true
[root@mylinux1 ~]# curl -u admin:admin "http://192.168.22.3:8080/job/build_with_params/api/json?pretty=true"
获取最后一次构建信息
curl -u USERNAME:PASSWORD JENKINSURL:PORT/job/JOBNAME/lastBuild/api/json?pretty=true
[root@mylinux1 ~]# curl -u admin:admin "http://192.168.22.3:8080/job/build_with_params/lastBuild/api/json?pretty=true"
获取最后稳定构建信息
curl -u USERNAME:PASSWORD JENKINSURL:PORT/job/JOBNAME/lastStableBuild/api/json?pretty=true
[root@mylinux1 ~]# curl -u admin:admin "http://192.168.22.3:8080/job/build_with_params/lastStableBuild/api/json?pretty=true"
获取最后成功的构建
curl -u USERNAME:PASSWORD JENKINSURL:PORT/job/JOBNAME/lastSuccessfulBuild/api/json?pretty=true
[root@mylinux1 ~]# curl -u admin:admin "http://192.168.22.3:8080/job/build_with_params/lastSuccessfulBuild/api/json?pretty=true"
获取最后完成的构建
curl -u USERNAME:PASSWORD JENKINSURL:PORT/job/JOBNAME/lastCompletedBuild/api/json?pretty=true
[root@mylinux1 ~]# curl -u admin:admin "http://192.168.22.3:8080/job/build_with_params/lastCompletedBuild/api/json?pretty=true"
最近失败的构建
curl -u USERNAME:PASSWORD JENKINSURL:PORT/job/JOBNAME/lastFailedBuild/api/json?pretty=true
[root@mylinux1 ~]# curl -u admin:admin "http://192.168.22.3:8080/job/maven_demo/lastFailedBuild/api/json?pretty=true"
五、使用curl调用操作Job
1、操作Job需要验证crumb
a、使用token发起接口(不推荐)
b、获取crumb使用
[root@mylinux1 ~]# username_password="admin:admin"
[root@mylinux1 ~]# jenkins_url="http://192.168.22.3:8080"
[root@mylinux1 ~]# cookie_file="$(mktemp)"
[root@mylinux1 ~]# jenkins_crumb=$(curl -s -f -u "${username_password}" --cookie-jar "${cookie_file}" -s "${jenkins_url}/crumbIssuer/api/xml?xpath=concat(//crumbRequestField,%22:%22,//crumb)")
[root@mylinux1 ~]# echo $jenkins_crumb
Jenkins-Crumb:bcc9f0c335fbcffe6e12f5aa4398ec2bdc74749b72b3389003bdc3f321d9b164
c、上面命令操作完成后会生成config.xml文件
[root@mylinux1 ~]# ls config.xml
config.xml
vim config.xml<?xml version='1.1' encoding='UTF-8'?>
<project><description></description><keepDependencies>false</keepDependencies><properties/><scm class="hudson.scm.NullSCM"/><canRoam>true</canRoam><disabled>false</disabled><blockBuildWhenDownstreamBuilding>false</blockBuildWhenDownstreamBuilding><blockBuildWhenUpstreamBuilding>false</blockBuildWhenUpstreamBuilding><triggers/><concurrentBuild>false</concurrentBuild><builders><hudson.tasks.Shell><command>echo "good"</command><configuredLocalRules/></hudson.tasks.Shell></builders><publishers/><buildWrappers/>
</project>
2、创建job
[root@mylinux1 ~]# curl -u "${username_password}" "${jenkins_url}/createItem?name=create_job2" --cookie "${cookie_file}" -X POST -H "${jenkins_crumb}" -H 'Content-Type:text/xml' --data-binary "@./config.xml"
[root@mylinux1 ~]#
3、复制job
[root@mylinux1 ~]# curl -u "${username_password}" "${jenkins_url}/createItem?name=create_job3&mode=copy&from=create_job1" --cookie "${cookie_file}" -X POST -H "${jenkins_crumb}"
[root@mylinux1 ~]#
4、修改job
[root@mylinux1 ~]# curl -u "${username_password}" "${jenkins_url}/job/create_job2/config.xml" --cookie "${cookie_file}" -X POST -H "${jenkins_crumb}" -H 'Content-Type:text/xml' --data-binary "@./config.xml"
[root@mylinux1 ~]#
5、无参构建
[root@mylinux1 ~]# curl -u "${username_password}" "${jenkins_url}/job/build_no_params/build" --cookie "${cookie_file}" -X POST -H "${jenkins_crumb}"
[root@mylinux1 ~]#
6、有参构建
[root@mylinux1 ~]# curl -u "${username_password}" "${jenkins_url}/job/build_with_params/buildWithParameters" --cookie "${cookie_file}" -X POST -H "${jenkins_crumb}" --data-urlencode json='{"env":"dev"}'
7、删除job
[root@mylinux1 ~]# curl -u "${username_password}" "${jenkins_url}/job/create_job2/doDelete" --cookie "${cookie_file}" -X POST -H "${jenkins_crumb}"
六、使用curl调用 操作指定构建的Job
查看最新构建任务编号
curl -u USERNAME:PASSWORD “JENKINSURL:PORT/job/son_demo/lastBuild/buildNumber”
查看某次构建控制台日志
curl -u USERNAME:PASSWORD “JENKINSURL:PORT/job/JOBNAME/ID/logText/progressiveText”
删除某次构建
curl -u USERNAME:PASSWORD "JENKINSURL:PORT/job/JOBNAME/ID/doDelete" -X POST --cookie "${cookie_file}" -H "${jenkins_crumb}"
1、查看最新构建任务编号
[root@mylinux1 ~]# curl -u "${username_password}" "${jenkins_url}/job/build_with_params/lastBuild/buildNumber"
2、查看某次构建控制台日志
[root@mylinux1 ~]# curl -u "${username_password}" "${jenkins_url}/job/build_with_params/6/logText/progressiveText"Started by user admin
Running as SYSTEM
Building on the built-in node in workspace /var/jenkins_home/workspace/build_with_params
[build_with_params] $ /bin/sh -xe /tmp/jenkins11717514708564825855.sh
+ [ online = dev ]
+ [ online = test ]
+ [ online = online ]
+ echo online runtime
online runtime
Finished: SUCCESS
七、Python Jenkins Api常用接口操作
1、安装 pip install jenkinsapi
2、jenkinsapi 连接Jenkins服务
from jenkinsapi import jenkins
class JenkinsApiStudy:
def __init__(self):"""实现对jenkins的连接"""jenkins_url="http://192.168.22.3:8080"
#username="admin"
#password="admin"用户名="admin"密码="admin"self.my_jenkins = jenkins.Jenkins(jenkins_url, username, password, use_crumb=True)
3、jenkinsapi 获取所有jobs
def get_all_jobs(self):"""jenkinsapi 获取所有jobs:
return:"""jobs=[]
# 需要注意,如果请求的url与Jenkins Location配置的Jenkins URL不一致时,获取到的key会拼接上一截地址
#jobs=self.my_jenkins.keys()
# 获取所有的job名称
for info in self.my_jenkins.get_jobs_info():jobs.append(info)
# 获取job的url与名称 比较卡return jobs
4、jenkinsapi 获取构建队列
def get_queue(self):"""获取队列信息:return:"""
return self.my_jenkins.get_queue().keys()
5、jenkinsapi 获取Job信息
def get_job_info(self,job_name):
"""jenkinsapi 获取Job信息:return:"""
# 获取job对象
my_job=self.my_jenkins.get_job(job_name)
# 获取最后一次构建对象
print(my_job.get_last_build())
# 获取最后一次完成的构建对象
print(my_job.get_last_completed_build())
# 获取最后一次成功的构建对象
print(my_job.get_last_good_build())
# 获取最后一次失败的构建编号
print(my_job.get_last_failed_buildnumber())
6、jenkinsapi 操作Job信息
def deal_job(self,job_name):"""jenkinsapi 操作Job信息:param job_name: job名称:return:"""
#my_job = self.my_jenkins.get_job(job_name)
# 获取job的config
#print(my_job.get_config())
# 创建job# 先获取到job的config
with open(f"{job_name}_config.xml", "w", encoding="utf-8") as f:my = self.my_jenkins.get_job(job_name).get_config()f.write(my)self.my_jenkins.create_job("create_python_job", open("./build_no_params_config.xml", encoding="utf-8").read())
# 复制
jobself.my_jenkins.copy_job(job_name, "build_no_params_job1")
#todo 禁用job:当创建job或者复制job时,会出现job没有构建功能;操作:禁用后再操作启用
#my_job.disable()
# 启用job
#my_job.enable()
# 重命名
jobself.my_jenkins.rename_job(job_name, f"{job_name}_new")
# 无参构建
self.my_jenkins.build_job(job_name)
# 有参构建
self.my_jenkins.build_job(job_name, params={"env": "test"})
# 删除job
#self.my_jenkins.delete_job(job_name)
a、查看my_job.get_config()信息
b、查看生成的config.xml文件
def deal_job(self,job_name):"""jenkinsapi 操作Job信息:param job_name: job名称:return:"""
#my_job = self.my_jenkins.get_job(job_name)
# 获取job的config
#print(my_job.get_config())
# 创建job# 先获取到job的configwith open(f"{job_name}_config.xml", "w", encoding="utf-8") as f:my = self.my_jenkins.get_job(job_name).get_config()f.write(my)self.my_jenkins.create_job("create_python_job", open("./build_no_params_config.xml", encoding="utf-8").read())
7、jenkinsapi 操作指定构建的Job
def get_build_info(self,job_name,build_id=None):"""jenkinsapi 操作指定构建的Job 获取build信息:param job_name: job名称:param build_id: 构建id:return:"""
my_job = self.my_jenkins.get_job(job_name)
# 当前job对象是否在队列/构建中
print(my_job.is_queued_or_running())
# 获取指定构建ID的对象
build_object = my_job.get_build(build_id)
# 获取构建对象的时间戳
print(build_object.get_timestamp())
# 获取控制台日志
print(build_object.get_console())
# 获取构建参数
print(build_object.get_params())
# 获取构建的状态
print(build_object.get_status())
# 获取构建的变更日志
print(build_object.get_changeset_items())
# 删除指定构建
#my_job.delete_build(build_id)
输出结果
2023-04-16 05:52:26+00:00
Started by user admin
Running as SYSTEM
Building on the built-in node in workspace /var/jenkins_home/workspace/build_with_params
[build_with_params] $ /bin/sh -xe /tmp/jenkins12197874264732667620.sh
+ [ test = dev ]
+ [ test = test ]
+ echo test runtime
test runtime
Finished: SUCCESS{'env': 'test'}
SUCCESS