近期由于开展 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 :
- XML
- JSON with JSONP support
- 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 ,你可以进行以下几个方面的扩展
- 从 Hudson 中获取相应的信息,在你的程序中加以应用( Hudson 报表系统就是利用的这一功能)
- 触发一次构建
- 创建 / 拷贝项目
远程 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 信息请参考: