Hudson 扩展之Remote access API（译文）

 

近期由于开展 Hudson 报表系统的开发，再一次体会到了 Hudson 这样一个开源持续集成系统的强大，这里要谈的就是 Hudson 其强大的可扩展性的方法之一：远程访问 API 。

谈到 API ，我想大家一定会第一时间想到我们的淘宝开发平台—— TOP 。对，没错，作为大淘宝战略的一部分， TOP 就是通过提供一系列 API 供 ISV 以及其他第三方调用，使得他们能够将自己的电子商务事业构建在淘宝这样一个土壤上。同样， Hudson 作为一个人气极高的开源持续集成系统，也提供了强大的 API 支持。在本周的周会上我做了一个简单的分享，但没有留下文档，这里我将官网的介绍结合自己的理解做了一个翻译，希望大家能够很好的了解这一特性，在今后的工作中，可以根据自己的需要进行扩展。

（以下为译文，来自： http://wiki.hudson-ci.org/display/HUDSON/Remote+access+API ）

简介：

Hudson 提供了一系列远程访问 API 用以接入其内部提供的功能，目前为止， Hudson 可以支持以下三种 API ：

1. XML
2. JSON with JSONP support
3. Python

 

与 TOP API 一样， Hudson 也同样是提供基于 REST 风格的 API 访问。对于 Hudson 提供的这些特性，并没有一个唯一的入口，如果我们要对某些数据进行操作，只需要在相应的 URL 后面加上“ /api ”即可。类似这种形式：“ …/api/ ”，这里的“ … ”代表 hudson 操作某个数据时的 URL （如果你对 Hudson 熟悉的话，你应该会了解 Hudson 的 URL 形式，比如： …/hudson 代表就是对 Hudson 这个对象的访问）

如果你的 Hudson 地址是： http://deadlock.netbeans.org/hudson/ , 那么当你访问 http://deadlock.netbeans.org/hudson/api/ 的时候，你会看到一个页面，这个页面会向你展示在 Hudson 这个类可以提供的功能。比如，你可以从这个地址通过 XML 或者 JSON 接入所有的 job （在 Hudson 上配置的项目）。如果你想接入某次特定的构建，比如： http://deadlock.netbeans.org/hudson/job/trunk/lastSuccessfulBuild/ , 那么你就可以访问这个地址： http://deadlock.netbeans.org/hudson/job/trunk/lastSuccessfulBuild/api/ ，这样你就可以看到这次特定的构建可以提供哪些功能供 API 调用

你可以使用 API 来做些什么

使用远程 API ，你可以进行以下几个方面的扩展

1. 从 Hudson 中获取相应的信息，在你的程序中加以应用（ Hudson 报表系统就是利用的这一功能）
2. 触发一次构建
3. 创建 / 拷贝项目

远程 API 和安全

如果你的 Hudson 应用了安全机制，你可以使用 HTTP 的基本的认证机制来对你的 API 请求进行认证。点击 Authenticating scripted clients 可以看到更多的信息

代码示例

这里有一个简单的 客户端实现 ，向你们演示如何使用 java 调用 XML API 并且解析 XML( Java 源码 )

使用 XPath 对 XML 进行挑选

XML API 支持使用 XPath 来对返回的 XML 串进行选择。如何来使用这一特性呢？很简单，只要在访问的 URL 后面加上 ” xpath” 作为参数，然后设置你的 XPath 表达式既可。这在某些对 XML 进行操作非常麻烦的情况下（比如 shell 脚本）对进行信息进行提取非常方便。如果想具体了解如何使用，可以点击 issue #626 作为参考

使用 XPath 对 XML 进行排除

与上面的方式相似，你可以使用“ exclude ”这个参数来设置要排除的 XPath 表达式来排除需要返回的节点。所有匹配这个表达式的节点都将从返回的 XML 中去除。

深度控制

有时候，一次 API 访问并不能获取到你所想要的全部信息。比如，如果你想要获得某一个视图中所有成功的构建信息，你会发现调用视图 API 并不能返回所有的信息，你必须针对每个项目递归调用项目 API 来获取这些信息。这是一个很麻烦的过程，所幸的是自从 1.167 版以后，我们可以使用“深度控制”来很好的解决这个问题。为了能够更好的理解这一特性，我们先从简单的开始，让我们先来简单了解一下远程 API 是如何工作的。

Hudson 内部提供的数据类型其实可以被看作是一个树型的结构，每次我们访问一个 API 的时候，我们都会获得一个子树。子树代表着以你使用 API 访问得到的对象为根节点以下的部分，这个子树被划分为不同的深度，以避免每次访问时会返回过多的数据。通过指定 depth 这个查询参数，我们可以取舍我们获得的数据量。

所以最后的结果是，如果你指定了一个更大的深度值，你将会看到同样的一个 API 会返回更多的信息。由于这种算法，一个使用更大深度值的 API 调用返回的数据将包括一个较小深度值所有返回的数据

在网络中发现 Hudson 服务

 

Hudson 实例会在 33848 端口监听 UDP 数据包。只要一旦接受到 UDP 数据包，它就会产生一个 XML 响应，这个响应包含了连接信息。这个 XML 的格式如下：

 

<hudson>

  <version>1.280</version>           <!— Hudson版本 -->

  <url>http://somwhere/hudson/</url> <!-- URL.如果没有配置，就为空 -->

  <slave-port>12345</slave-port>     <!—如果配置了TCP salve的监听端口，那么这里返回端口号 -->

</hudson>

 

 

通过这种方式，客户端可以使用 UDP 广播来发现附近运行的 Hudson 实例

后记：

在 Hudson 报表系统的开发过程中，我们就是通过调用 Hudson API ，使用深度控制来一次性获取所有的信息，避免繁杂的递归调用过程。这使得整个数据抓取变得简单明了。另外，我们不光可以获取信息，同时还可以触发构建，新建项目等等。对于深度控制，这也是我觉得这是 TOP API 可以学习的地方。希望这篇译文可以帮助大家快速理解 Hudson API 的用途和用法，通过这样一个强大的特性，在持续集成过程中，开发出更多符合我们实际需要的工具。

更多关于 Hudson 信息请参考：

         http://hudson-ci.org/