接触Jenkins（Hudson）API，第2部分

这篇文章从本教程的第1部分继续。已经快一年了，但是我终于有时间重新审视我为与Jenkins api交互而编写的一些代码。我已经使用了部分工作来帮助管理许多Jenkins构建服务器，主要是保持插件同步以及将作业从一台机器移动到另一台机器。在本文中，我将主要关注CLI jar功能以及您可以使用它进行的一些操作。这主要是针对Jenkins开发的，但是我对Hudson进行了一些轻量级测试，并且可以在我尝试过的所有地方工作，因此对于您选择的构建服务器，代码始终是不可知的。

项目结构

该代码托管在Github上，并提供一个Gradle构建，该构建可在本地下载并启动Jenkins（或Hudson）服务器以执行测试。服务器设置为使用Gradle构建目录作为其工作目录，因此只需执行gradle clean即可将其删除。我使用所需库的Jenkins版本和Hudson版本进行了尝试，除了两个CLI实现之间的一些古怪之处外，它们的功能仍然相同。如果要使用Hudson而不是Jenkins进行尝试，请传递命令标志-Pswitch，并将使用适当的war和库。该项目旨在与Gradle 1.0-milestone-8一起运行，并带有该版本的Gradle包装器。自原始文章以来，大多数代码都保持不变，但是对Jenkins和Hudson的较新版本进行了一些增强和更改。
该项目产生的库以Maven工件的形式发布，稍后我将确切描述如何实现。还包括一些示例，这些示例演示了在Gradle或Maven项目中以及在Grapes的Groovy脚本中如何使用该库。我们使用Groovy 1.8.6，Gradle 1.0-milestone-8和Maven 3.0.3构建所有内容。

充分利用CLI

作为api的替代方法，CLI jar是一种非常强大的与构建服务器进行交互的方式。除了各种内置命令之外，Groovy脚本还可以远程执行，而我们只需付出一点努力就可以轻松地序列化响应，以处理服务器上提取的数据。作为执行环境，服务器提供Groovysh Shell并为hudson.model包存储导入。该包中的Jenkins / Hudson单例对象的实例也传递给Binding 。在这些示例中，我使用的是向后兼容的Hudson版本，因为该代码旨在在两种服务器上均可运行。

可用命令

内置命令种类繁多，所有这些命令均在hudson.cli包中实现。以下是正在运行的应用程序的CLI页面上列出的内容：

build：构建作业，并且可以选择等待直到完成。
cancel-quiet-down：取消“ quiet-down”命令的效果。
clear-queue：清除构建队列
connect-node：重新连接到节点
复制作业：复制一份工作。
create-job：通过读取stdin作为配置XML文件来创建新作业。
delete-builds：删除构建记录。
delete-job：删除工作
delete-node：删除节点
disable-job：禁用工作
断开节点：与节点断开连接
enable-job：启用工作
get-job：将作业定义XML转储到stdout
groovy：执行指定的Groovy脚本。
groovysh：运行交互式groovy shell。
help：列出所有可用的命令。
install-plugin：从文件，URL或从更新中心安装插件。
install-tool：执行自动工具安装，并将其位置打印到stdout。只能从
内部版本。
keep-build：标记该构建以永久保留该构建。
list-changes：转储指定构建的变更日志。
login：保存当前凭证，以允许将来的命令在没有显式凭证信息的情况下运行。
注销：删除使用登录命令存储的凭证。
邮件：读取stdin并将其作为电子邮件发送出去。
offline-node：停止使用临时执行构建的节点，直到下一个“ online-node”命令。
online-node：在线使用节点执行构建，以取消先前的“ offline-node”命令。
安静：安静下詹金斯，为重新启动做准备。不要开始任何构建。
重新加载配置：丢弃内存中所有已加载的数据，然后从文件系统重新加载所有内容。有用的时候
您直接在磁盘上修改了配置文件。
重新启动：重新启动詹金斯
安全重启：安全重启詹金斯
安全关闭：将Jenkins置于安静模式，等待现有构建完成，然后关闭
詹金斯
set-build-description：设置构建的描述。
set-build-display-name：设置构建的displayName
set-build-result：设置当前构建的结果。仅当从内部调用时才有效。
shutdown：立即关闭Jenkins服务器
update-job：从stdin更新作业定义XML。与get-job命令相反
version：输出当前版本。
wait-node-offline：等待节点脱机
wait-node-online：等待节点联机
我是谁：报告您的凭据和权限

目前尚不清楚每个参数都需要什么参数，但是在不带参数调用时，它们几乎普遍遵循打印使用情况详细信息的CLI模式。例如，当您不带任何参数调用build命令时，以下是您在错误流中返回的内容：

参数“ JOB”为必填项
java -jar jenkins-cli.jar建立args…
开始构建，然后选择等待完成。除了一般的脚本使用之外，该命令可以是用于从一个作业的构建中调用另一个作业。使用-s选项，此命令将根据以下命令更改退出代码构建的结果（退出代码0表示成功。）使用-c选项，只有在存在 SCM变更职位：要建立的工作名称 -c：在开始构建之前检查SCM更改，如果没有，请检查更改，不进行构建即退出 -p：以键=值格式指定构建参数。 -s：等待命令完成/中止

从系统中取出数据

与远程系统的所有交互都由流处理，编写脚本非常容易，这些脚本将使用内置的Groovy工具以易于解析的String格式返回数据。从理论上讲，您也应该能够封送更复杂的对象，但是现在让我们保持简单。这是一个Groovy脚本，该脚本仅将所有作业名称提取到List中，并调用Groovy inspect方法引用所有值。

@GrabResolver(name = 'glassfish', root = 'http://maven.glassfish.org/content/groups/public/')
@GrabResolver(name = "github", root = "http://kellyrob99.github.com/Jenkins-api-tour/repository")
@Grab('org.kar:hudson-api:0.2-SNAPSHOT')
@GrabExclude('org.codehaus.groovy:groovy')
import org.kar.hudson.api.cli.HudsonCliApiString rootUrl = 'http://localhost:8080'
HudsonCliApi cliApi = new HudsonCliApi()
OutputStream out = new ByteArrayOutputStream()
cliApi.runCliCommand(rootUrl, ['groovysh', 'hudson.jobNames.inspect()'], System.in, out, System.err)
List allJobs = Eval.me(cliApi.parseResponse(out.toString()))
println allJobs

收到响应后，我们将做一些整理工作以删除String开头的一些多余字符，并使用Eval.me将String转换为List。 Groovy提供了多种将文本转换为代码的方法，因此，如果您的使用情况比这种简单情况复杂，则可以使用GroovyShell和Binding或其他替代方法将结果解析为有用的东西。这种简单的技术也扩展到了Maps和其他类型，从而使得处理从服务器发送回的数据变得简单。

一些有用的例子

查找具有更新的插件并更新所有插件

这是一个使用Groovy脚本查找所有具有可用更新的插件，然后将结果返回给调用者，然后在所有插件上调用CLI'install-plugin'命令的示例。方便地，此命令将安装插件（如果尚未安装）或将其更新到最新版本（如果已安装）。

def findPluginsWithUpdates = '''
Hudson.instance.pluginManager.plugins.inject([]) { List toUpdate, plugin ->if(plugin.hasUpdate()){toUpdate << plugin.shortName}toUpdate
}.inspect()
'''
OutputStream updateablePlugins = new ByteArrayOutputStream()
cliApi.runCliCommand(rootUrl, ['groovysh', findPluginsWithUpdates], System.in, updateablePlugins, System.err)def listOfPlugins = Eval.me(parseOutput(updateablePlugins.toString()))
listOfPlugins.each{ plugin ->cliApi.runCliCommand(rootUrl, ['install-plugin', plugin])
}

一次安装或升级一套插件

使用“管理插件” UI绝对可以胜任，并且是幂等的，因此多次运行它只会导致可能升级已安装的插件。这套插件可能有些过分，但是我最近调查了一些插件以供使用。

@GrabResolver(name='glassfish', root='http://maven.glassfish.org/content/groups/public/')
@GrabResolver(name="github", root="http://kellyrob99.github.com/Jenkins-api-tour/repository")
@Grab('org.kar:hudson-api:0.2-SNAPSHOT')
@GrabExclude('org.codehaus.groovy:groovy')
import static java.net.HttpURLConnection.*
import org.kar.hudson.api.*
import org.kar.hudson.api.cli.HudsonCliApiString rootUrl = 'http://localhost:8080'
HudsonCliApi cliApi = new HudsonCliApi()['groovy', 'gradle', 'chucknorris', 'greenballs', 'github', 'analysis-core', 'analysis-collector', 'cobertura','project-stats-plugin','audit-trail', 'view-job-filters', 'disk-usage', 'global-build-stats','radiatorviewplugin', 'violations', 'build-pipeline-plugin', 'monitoring', 'dashboard-view','iphoneview', 'jenkinswalldisplay'].each{ plugin ->cliApi.runCliCommand(rootUrl, ['install-plugin', plugin])
}//  Restart a node, required for newly installed plugins to be made available.
cliApi.runCliCommand(rootUrl, 'safe-restart')

查找所有失败的构建并触发它们

网络问题或基础设施事件可能导致大量构建一次全部失败，这并非罕见。解决问题后，该脚本可用于验证构建是否均正常工作。

@GrabResolver(name = 'glassfish', root = 'http://maven.glassfish.org/content/groups/public/')
@GrabResolver(name = "github", root = "http://kellyrob99.github.com/Jenkins-api-tour/repository")
@Grab('org.kar:hudson-api:0.2-SNAPSHOT')
@GrabExclude('org.codehaus.groovy:groovy')
import org.kar.hudson.api.cli.HudsonCliApiString rootUrl = 'http://localhost:8080'
HudsonCliApi cliApi = new HudsonCliApi()
OutputStream out = new ByteArrayOutputStream()
def script = '''hudson.items.findAll{ job ->job.isBuildable() && job.lastBuild && job.lastBuild.result == Result.FAILURE
}.collect{it.name}.inspect()
'''
cliApi.runCliCommand(rootUrl, ['groovysh', script], System.in, out, System.err)
List failedJobs = Eval.me(cliApi.parseResponse(out.toString()))
failedJobs.each{ job ->cliApi.runCliCommand(rootUrl, ['build', job])
}

打开一个交互式Groovy Shell

如果您确实想在服务器上戳戳，则可以启动一个交互式外壳程序以检查状态并执行命令。绑定了System.in流，并立即回显了来自服务器的响应。

@GrabResolver(name = 'glassfish', root = 'http://maven.glassfish.org/content/groups/public/')
@GrabResolver(name = "github", root = "http://kellyrob99.github.com/Jenkins-api-tour/repository")
@Grab('org.kar:hudson-api:0.2-SNAPSHOT')
@GrabExclude('org.codehaus.groovy:groovy')
import org.kar.hudson.api.cli.HudsonCliApi
/*** Open an interactive Groovy shell that imports the hudson.model.* classes and exposes* a 'hudson' and/or 'jenkins' object in the Binding which is an instance of hudson.model.Hudson*/
HudsonCliApi cliApi = new HudsonCliApi()
String rootUrl = args ? args[0] :'http://localhost:8080'
cliApi.runCliCommand(rootUrl, 'groovysh')

项目更新

去年发生了很多事情，所有项目依赖项都需要更新。特别是，对Groovy，Gradle和Spock进行了一些非常不错的改进。最值得注意的是，自0.9.2版以来，Gradle已经走了很长一段路。 Groovy 1.8中添加的JSON支持也很方便。 Spock在使用@Unroll时需要进行一些小的调整才能在测试报告中呈现动态内容，但这对于“老”方法和“ 链式存根 ”之类的功能来说是一笔不小的代价。本质上，为了响应Groovy 1.8+中的更改，Spock @Unroll注释需要从以下更改：

@Unroll('querying of #rootUrl should match #xmlResponse')

闭包封装的GString表达式：

@Unroll({'querying of $rootUrl should match $xmlResponse'})

听起来语法还在不断变化，很高兴我在网上找到了关于这个问题的讨论。

在Github上托管Maven存储库

也许您从前面的脚本示例中注意到了，我们正在引用一个已发布的库来获取HudsonCliApi类。上周，我读了一篇有趣的文章，描述了如何使用内置的Github Pages发布Maven存储库。尽管它的功能不如Nexus或Artifactory这样的存储库，但足以以标准方式将一些二进制文件提供给大多数常见的构建工具。只需在标准Maven回购布局中发布二进制文件以及相关的Pom，即可开始比赛！每个依赖关系管理系统都有其怪癖（我在看着您Ivy！），但是它们很容易解决，因此这里是Gradle，Maven和Groovy Grapes使用此项目代码生成的库的示例。请注意，Jenkins / Hudson所需的某些依赖项在Maven中央存储库中不可用，因此我们从Glassfish存储库中获取它们。

摇篮

很简单，这适用于最新版本的Gradle，并假定您使用的是Groovy插件。

repositories {mavenCentral()maven {url 'http://maven.glassfish.org/content/groups/public/'}maven {url 'http://kellyrob99.github.com/Jenkins-api-tour/repository'}
}
dependencies {groovy 'org.codehaus.groovy:groovy-all:${versions.groovy}'compile 'org.kar:hudson-api:0.2-SNAPSHOT'
}

马文

xml中的内容基本上相同，在这种情况下，假设您使用的是GMaven插件

<repositories><repository><id>glassfish</id><name>glassfish</name><url>http://maven.glassfish.org/content/groups/public/</url></repository><repository><id>github</id><name>Jenkins-api-tour maven repo on github</name><url>http://kellyrob99.github.com/Jenkins-api-tour/repository</url></repository>
</repositories><dependencies><dependency><groupId>org.codehaus.groovy</groupId><artifactId>groovy-all</artifactId><version>${groovy.version}</version></dependency><dependency><groupId>org.kar</groupId><artifactId>hudson-api</artifactId><version>0.2-SNAPSHOT</version></dependency>
</dependencies>

葡萄

在这种情况下，解决旧版本Groovy的某些传递依赖关系似乎存在问题，这就是为什么对此有显式排除的原因。

@GrabResolver(name='glassfish', root='http://maven.glassfish.org/content/groups/public/')
@GrabResolver(name='github', root='http://kellyrob99.github.com/Jenkins-api-tour/repository')
@Grab('org.kar:hudson-api:0.2-SNAPSHOT')
@GrabExclude('org.codehaus.groovy:groovy')

链接