Remote access API

Hudsonは、その機能へのリモートアクセスAPIを提供します。現在は2つの形式があります。

XML
JSON with JSONP support

リモートアクセスAPIはRESTのような形式で提供されます。つまり、すべての機能に対して1つのエントリポイントがあるのではなく、かわりに ".../api/" (ここで、 "..." は対象となるデータ)というURLで有効です。

例えば、インストールしたHudsonがhttp://deadlock.netbeans.org/hudson/であれば、http://deadlock.netbeans.org/hudson/api/はHudsonのルートで作用するすべての有効な機能のリストを提供します。例えば、ここからXML/JSONでHudson上のすべてのジョブにアクセスすることができます。もしくは、http://deadlock.netbeans.org/hudson/job/trunk/lastSuccessfulBuild/の特定のビルドについての情報にアクセスしたいのであれば、http://deadlock.netbeans.org/hudson/job/trunk/lastSuccessfulBuild/api/にアクセスすれば、ビルドの機能の一覧を見ることができます。

この機能は現在開発中なので、足りない機能があるならバグ管理システムに登録してください。

いったい何ができるの?

リモートアクセスAPIは次のようなことに使用できます。

プログラムでHudsonから情報を取得する
新しいビルドを起動する
ジョブの作成、コピー

リモートAPIとセキュリティ

Hudsonのセキュリティが有効化されているときは、リモートAPIのいくつかは認証キーを必要とします。Hudsonのセキュリティを参照してください。

サンプルコード

JavaでXMLインタフェースを実行するサンプルがここにあります(Java ソース)。

XPathによる検索

XML APIはクエリーパラメータ'xpath'を使ったXPathによる検索をサポートしています。 (シェルスクリプトのような）XMLの操作が面倒な環境で情報の抽出するのに便利です。どうやって使うかは課題 #626を参照してください。

Depth control

リモートAPIを1回呼ぶだけで十分な情報を取得できないことがあります。例えば、ビューの最後に成功したすべてのビルドを調査したい場合、ビューのリモートAPIを実行しても取得できないことがわかります。そして、取得した各プロジェクト毎にリモートAPIを再帰的に呼ばなくてはなりません。1.167で実装された"depth control"はこの問題を解決します。この機能を理解するには、リモートAPIがどのように機能するのかから始めるのがいいでしょう。

Hudsonが内部に保持するデータモデルは、巨大な木構造と考えることができます。リモートAPIを呼ぶと、小さな木構造のサブツリーを取得します。サブツリーはリモートAPIを呼んだオブジェクトを先頭にし、巨大なデータを返さないようにある深さを超えないようにカットされます。深さを表すクエリーパラメータを指定すればこのカットする振る舞いを調整できます。正の深さを指定すると、 the subtree cut-off happens that much later.

結果的に、大きな値を指定すればするほど、リモートAPIはより大量にデータを返します。アルゴリズム上、深さが大きいデータは小さなものが返すすべてのデータを含むのでそうなります。

Hudsonのバージョンの検出

Hudsonのバージョンをチェックするには、トップ画面を読み込んでレスポンスヘッダーの"X-Hudson"ヘッダをチェックします。このヘッダには"1.171"のようなHudsonのバージョン番号を含んでいます。HudsonのURLかどうかチェックするにはこのヘッダをチェックするといいでしょう。