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

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

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

API

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

“ /.../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渲染的同一棵树。

此功能从服务器的根开始在树中扩展，您可以通过在网址上提供“ 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 status
    HTTPBuilder http = new HTTPBuilder(rootUrl)
    http.handler.failure = { resp ->
        println 'Unexpected failure on $rootUrl$path: ${resp.statusLine} ${resp.status}'
        status = resp.status
    }

    def info
    http.get(path: path, query: [depth: depth]) { resp, json ->
        info = json
        status = 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应用程序，该应用程序既可以作为跨服务器构建的辐射器，又可以用作服务器管理的中央工具。 该概念证明能够连接到多个构建服务器并可视化作业数据以及特定的系统配置，触发构建，并直接链接到每个连接的服务器以允许进一步钻取。 这是几个样机，几乎可以显示图片。

只是一个非常酷的应用程序，用于安装Jenkins

这只是非常间接的关系，但是我遇到了一个非常漂亮且简单的Griffon应用程序，称为Jenkins-Assembler ，它简化了构建服务器的准备工作。 它为您提供了一系列插件，让您选择并选择，然后下载并将它们组合成一个可部署的战争。

足够多的谈话–代码在哪里？？？

与本文相关的源代码可在github上找到 。 这些测试更多地是对实时API的探索，而不是对该项目中代码的实际测试。 它们在使用Gradle Jetty插件启动的本地服务器上运行。 最后，这是为您准备的一些漂亮图片。
[以幻灯片显示]
[使用PicLens查看]

继续第2部分 。

参考：在The Kaptain on…博客上，从我们的JCG合作伙伴 Kelly Robinson接触到Jenkins（Hudson）API 。

翻译自: https://www.javacodegeeks.com/2012/08/hooking-into-jenkins-hudson-api-part-1.html