基于Python SDK的Jenkins二次开发实战指南

背景与概述

背景

近期我们在搭建一个云执行平台，底层采用Jenkins作为执行引擎，旨在实现对各类脚本的统一调度与管理。

Jenkins提供了完善的RESTful API体系，极大地便利了二次开发工作。此外，官方提供的Python SDK进一步降低了操作门槛，使得通过代码控制Jenkins变得更为便捷。

Jenkins核心概念

常用的Jenkins概念

在使用Jenkins时，用户界面通常以View（视图）的形式呈现。

这意味着我们在前端看到的主要是各种视图布局。

所有的构建任务，无论是执行测试用例、运行脚本，还是进行打包编译及发布，在Jenkins中都被定义为一个Job。

每个Job都拥有唯一的name标识。若该Job被归类在某个文件夹下，其name即为“文件夹名+Job名”。在查询Job信息时，返回结果中的full_name字段即对应此命名规则。

Python SDK安装与文档

PythonSDK

通过执行pip install python-jenkins命令即可安装该SDK。

官方PyPI地址：https://pypi.org/project/python-jenkins/

文档地址：http://python-jenkins.readthedocs.io/en/latest/

虽然官方文档为英文，但鉴于该SDK设计简洁直观，即使直接阅读源码也能轻松上手。函数命名语义清晰，无需深入理解内部机制即可正常使用。在开发过程中，我主要依赖查阅源码进行编码。

以下列出开发中常用且涉及的方法，我将按开发步骤逐一详解。

核心功能开发实战

开发过程

Job信息查询

job信息查询

在Jenkins架构中，每次构建对应一个Job。为了在Web页面展示历史构建记录，我们需要获取历史Job的执行信息，这可以通过调用get_job_info方法实现。

 def get_job_info(self, name, depth=0, fetch_all_builds=False):
 '''Get job information dictionary.

 :param name: Job name, ``str``
 :param depth: JSON depth, ``int``
 :param fetch_all_builds: If true, all builds will be retrieved
     from Jenkins. Otherwise, Jenkins will
     only return the most recent 100
     builds. This comes at the expense of
     an additional API call which may
     return significant amounts of
     data. ``bool``
 :returns: dictionary of job information
 '''

name参数代表Job的名称。例如，新建名为“自动化测试”的Job，则name传“自动化测试”；若该Job位于某文件夹内，则name需传递“文件夹名/自动化测试”。

此处存在一个兼容性问题：在Python 2.7版本中，若直接以变量形式传递name参数，可能会引发报错。解决方法是对name进行utf-8编码处理，即name.encode('utf-8')。该方法返回的数据结构包含以下字段：

返回结果中的builds字段存储了所有历史构建数据，而property字段则包含了Jenkins构建时的各类参数配置。

构建日志获取

构建日志

获取构建数据后，若能在Web页面直接查看日志将极大提升体验。为此，我们需要调用get_build_console_output方法提取每次构建的日志。

 def get_build_console_output(self, name, number):
 '''Get build console text.

 :param name: Job name, ``str``
 :param number: Build number, ``int``
 :returns: Build console output, ``str``
 '''

该方法返回Jenkins构建日志的字符串内容。若需在构建过程中实时展示日志，只需在构建时调用此方法即可获取当前构建日志。通过Socket通信或轮询机制，均可实现日志的实时前端展示。

执行构建与注意事项

执行构建

触发构建是核心操作之一，可使用build_job方法来完成。

 def build_job(self, name, parameters=None, token=None):
 '''Trigger build job.

 This method returns a queue item number that you can pass to
 :meth:`Jenkins.get_queue_item`. Note that this queue number is only
 valid for about five minutes after the job completes, so you should
 get/poll the queue information as soon as possible to determine the
 job's URL.

 :param name: name of job
 :param parameters: parameters for job, or ``None``, ``dict``
 :param token: Jenkins API token
 :returns: ``int`` queue item
 '''

name参数与查询Job信息时的用法一致，同样需注意编码问题。parameters参数为字典类型，对应Web页面点击构建时需填写的参数。token参数在初始化Jenkins类时已配置，通常无需额外传入。该方法返回一个queue_item编号，即Jenkins的构建队列ID。此ID可用于查询构建状态、取消构建等其他操作，SDK中均提供了对应方法。

注意：严禁使用此queue_item编号来判断Job是否正在构建中。该编号在构建完成后约五分钟内失效，若构建耗时过长，查询将因编号失效而报错，尽管Job实际上仍在运行。

上述方法虽便捷，但存在局限性：若构建过程中使用了第三方插件，这些标准方法无法获取插件生成的结果。例如，使用RobotFramework插件处理测试结果时，无法通过上述API直接获取其输出结果。

源码原理与API解析

从原理入手

Jenkins对外暴露的是RESTful接口，Python SDK的作用是对这些接口请求进行封装以提升易用性。许多方法的核心实现均依赖于jenkins_request函数，例如：

response = self.jenkins_request(requests.Request( 'POST', self.build_job_url(name, parameters, token)))

有兴趣的开发者可自行研读源码。该SDK本质上是基于requests库进行的封装，最终均通过jenkins_request发起对RESTful API的请求。访问Jenkins页面右下角，可以看到类似“API”的标识。

带有此标识的页面即表示存在对应的API接口，那么如何获取这些接口地址呢？

答案隐藏在源码中，许多方法内部都包含类似的逻辑。

self.jenkins_open(requests.Request('GET', self._build_url(INFO),auth=auth),
   add_crumb=False, resolve_auth=False)

response = self.jenkins_open(requests.Request('GET', self._build_url(BUILD_INFO,locals())))

在页面顶部的配置信息中可以找到关键定义：

INFO = 'api/json'

这意味着，在页面URL后追加/api/json即可获取相应的数据接口。

所有操作均基于此数据接口实现。因此，只要掌握URL拼接规则，即可轻松进行二次开发。

当然，开发过程中仍会遇到诸多坑点。例如，在获取历史数据时，接口竟然不返回历史构建的状态信息，这给开发带来了额外挑战。

开发总结与建议

总结

整体开发过程较为顺利，得益于源码简单易懂，多数问题可通过阅读源码解决。然而，主要难点在于返回结果的枚举值缺乏统一文档说明，导致开发完成后仍需频繁修补代码。

以上关于基于Python的Jenkins二次开发操作的全部内容分享完毕，希望能为读者提供参考，并欢迎大家支持本站。