jenkins api_接触Jenkins（Hudson）API，第1部分

jenkins api

哪一个-哈德森还是詹金斯？

都。几个月前，我开始使用Hudson v1.395来从事这个小项目，在出现巨大分歧之后又回到了这个项目。我以此为契机，看我将来选择永久搬到詹金斯时是否会遇到任何重大问题。出现了一些麻烦-最值得注意的是，新的CLI jar不能立即使用，但是Jenkins的整体v1.401在切换后按预期工作。好消息是旧版本的CLI jar仍然可以使用，因此此示例实际上是使用混合代码来完成工作。无论如何，该软件非常出色，并且值得称赞的有余。

API

Jenkins / Hudson有一个便捷的远程API，其中包含有关您的构建的信息，并支持一组丰富的功能来远程控制它们以及整个服务器。可以触发构建，复制作业，停止服务器，甚至远程安装插件。与服务器的API交互时，可以选择XML，JSON或Python。而且，正如内置文档中所述，您可以在以下位置的相对路径中找到所需的功能：

“ /.../api/，其中“ ...”部分是您要访问的对象”。

如果您在浏览器中导航到该页面，它将显示一个简短的文档页面，如果您将所需的格式添加为路径的最后一部分，则将返回结果。例如，要加载有关运行本地托管Jenkins服务器的计算机的信息，对此URL的get请求将以JSON格式返回结果：http：// localhost：8080 / computer / api / json。

{'busyExecutors': 0,'displayName': 'nodes','computer': [{'idle': true,'executors': [{},{}],'actions': [],'temporarilyOffline': false,'loadStatistics': {},'displayName': 'master','oneOffExecutors': [],'manualLaunchAllowed': true,'offline': false,'launchSupported': true,'icon': 'computer.png','monitorData': {'hudson.node_monitors.ResponseTimeMonitor': {'average': 111},'hudson.node_monitors.ClockMonitor': {'diff': 0},'hudson.node_monitors.TemporarySpaceMonitor': {'size': 58392846336},'hudson.node_monitors.SwapSpaceMonitor': null,'hudson.node_monitors.DiskSpaceMonitor': {'size': 58392846336},'hudson.node_monitors.ArchitectureMonitor': 'Mac OS X (x86_64)'},'offlineCause': null,'numExecutors': 2,'jnlpAgent': false}],'totalExecutors': 2
}

这是使用GraphViz渲染的同一棵树。

此功能从服务器的根开始在树中扩展，您可以通过在URL上提供“ depth”参数来控制从任何特定分支加载的树的数量。请注意您指定此变量的高度。在人口众多，运行时间较长的构建服务器（数十个具有数千个作业执行的构建）上进行了四个负载深度的测试，从而为我定期超时。为了让您有个想法，这里是api根深3处的域的非常粗略的可视化。

从服务器中取出数据非常简单，但是远程触发服务器上的活动的能力更加有趣。为了触发名为“ test”的作业的构建，http：// localhost：8080 / job / test / build上的POST执行了该作业。使用可用的设施，很容易做到：

加载作业的配置文件，对其进行修改并通过发布新的config.xml文件来创建新作业
将作业从一台构建机器移至另一台
建立计划的构建概述

CLI Jar

还有另一种方法可以在与服务器一起分发的CLI jar中远程驱动构建服务器。这个jar提供了用于在构建服务器上远程执行某些命令的简单工具。值得注意的是，这使远程安装插件和执行远程Groovy Shell成为可能。我将这个功能与CLI罐公开的主类的非常薄的包装程序结合在一起，如下一个代码示例所示。

/*** Drive the CLI with multiple arguments to execute.* Optionally accepts streams for input, output and err, all of which* are set by default to System unless otherwise specified.* @param rootUrl* @param args* @param input* @param output* @param err* @return*/
def runCliCommand(String rootUrl, List<String> args, InputStream input = System.in,OutputStream output = System.out, OutputStream err = System.err)
{def CLI cli = new CLI(rootUrl.toURI().toURL())cli.execute(args, input, output, err)cli.close()
}

这是一个简单的测试，展示了如何执行Groovy脚本以加载有关作业的信息，类似于您可以从服务器上内置的Groovy脚本控制台执行的操作，该操作可在http：/本地安装的部署中找到。 / localhost：8080 / script。

def 'should be able to query hudson object through a groovy script'()
{final ByteArrayOutputStream output = new ByteArrayOutputStream()when:api.runCliCommand(rootUrl, ['groovysh', 'for(item in hudson.model.Hudson.instance.items) { println('job $item.name')}'],System.in, output, System.err)then:println output.toString()output.toString().split('\n')[0].startsWith('job')
}

如果您想了解更多信息，下面是一些有关CLI的文章链接：

哈德逊CLI Wikidoc
Jenkins CLI Wikidoc
Jenkins上PHP作业的模板
川口浩辅的文章
一个不错的教程

HTTPBuilder

如今，当针对HTTP API进行编程时， HTTPBuilder是我选择的工具。用法非常简单，我只能使用两种方法来支持到达整个API：一种用于GET，一种用于POST。这是GET方法，足以执行请求，解析JSON响应并完成（尽管很幼稚）错误处理。

/*** Load info from a particular rootUrl+path, optionally specifying a 'depth' query* parameter(default depth = 0)** @param rootUrl the base url to access* @param path  the api path to append to the rootUrl* @param depth the depth query parameter to send to the api, defaults to 0* @return parsed json(as a map) or xml(as GPathResult)*/
def get(String rootUrl, String path, int depth = 0)
{def statusHTTPBuilder http = new HTTPBuilder(rootUrl)http.handler.failure = { resp ->println 'Unexpected failure on $rootUrl$path: ${resp.statusLine} ${resp.status}'status = resp.status}def infohttp.get(path: path, query: [depth: depth]) { resp, json ->info = jsonstatus = resp.status}info ?: status
}

调用它来获取数据是一个内衬，因为唯一的真正区别是调用API时使用的“路径”变量。

private final GetRequestSupport requestSupport = new GetRequestSupport()...
/*** Display the job api for a particular Hudson job.* @param rootUrl the url for a particular build* @return job info in json format*/
def inspectJob(String rootUrl, int depth = 0)
{requestSupport.get(rootUrl, API_JSON, depth)
}

从技术上讲，这里没有什么可以将其限制为仅JSON。 HTTPBuilder的一大优点是，它将很高兴地尝试对响应进行正确的处理。如果返回的数据为JSON格式（如以下示例所示），则将其解析为JSONObject。另一方面，如果数据是XML，则将其解析为Groovy GPathResult。尽管导航对象图的语法不同，但它们都很容易导航。

你能做什么呢？

探索Hudson / Jenkins API的主要动机是了解如何使管理多台服务器变得更加容易。目前，我每天处理四台构建服务器和另一台从属计算机，并支持各种不同版本的分支。这包括单元测试套件和功能测试套件的混合，以及连续部署的作业，该作业定期将更改推送到与我们支持的平台矩阵匹配的测试机上，因此，不幸的是，事情并没有分支时复制单个作业那么简单。确实，以自动或至少半自动的方式为新功能分支创建构建基础结构确实很有吸引力，尤其是因为正在计划扩展构建自动化。对于最近的555天项目，我利用API层构建了Grails应用程序，该应用程序既可以作为跨服务器构建的辐射器，又可以用作服务器管理的中央设施。此概念证明能够连接到多个构建服务器，并可视化作业数据以及特定的系统配置，触发构建，并直接链接到每个连接的服务器，以允许进一步钻取。这是几个样机，几乎可以显示图片。