日本語 : Remote access API

Created by Unknown User (sogabe), last modified by Unknown User (akiko_pusu) on Dec 26, 2011

オリジナル: Remote access API

Jenkinsは、コンピュータからの操作が可能なリモートアクセスAPIも提供しています。現在は3つの形式があります。

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

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

例えば、インストールしたJenkinsが http://deadlock.netbeans.org/hudson/ であれば、http://deadlock.netbeans.org/hudson/api/ から、Jenkinsのルートで実行できる全ての機能のリストをHTMLで取得できます。例えば、ここからXML/JSONを使ってJenkins上のすべてのジョブにアクセスすることができます。もしくは、 http://deadlock.netbeans.org/hudson/job/trunk/lastSuccessfulBuild/ の特定のビルドについての情報にアクセスしたいのであれば、 http://deadlock.netbeans.org/hudson/job/trunk/lastSuccessfulBuild/api/ にアクセスすれば、ビルドに関する（APIの）機能の一覧を取得できます。

この機能は現在開発中なので、もし、不十分な機能があるのであれば、チケット管理システムに登録してください。

いったい何ができるの?

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

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

ジョブの実行

パラメータ指定の無いジョブは、単純にHTTP GETメソッドを使い、下記のように、

JENKINS_URL/job/JOBNAME/build?token=TOKEN

というURLに、ジョブの設定画面で指定したTOKENを付加してアクセスするだけで実行できます。

パラメータ指定がある場合は、JSONを利用する必要があります。下記はshellのコードの抜粋です。
（読みやすくするために、いくつか改行をしています）

json="{\"parameter\": [{\"name\": \"taskfile\", \"value\": \"$taskfile\"},
{\"name\": \"task\", \"value\": \"$task\"},
{\"name\": \"jobParameters\", \"value\": \"$jobargs\"}], \"\": \"\"}"
url=http://hudson.basistech.net/job/benson-segmentation-training/build
curl -X POST $url -d token=zorn --data-urlencode json="$json"

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

Jenkinsのセキュリティが有効化されているときは、リモートAPIの認証用に、HTTP BASIC認証を利用できます。詳しくは、Authenticating scripted clientsを参照してください。

サンプルコード

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

XPathによる検索

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

Depth control

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

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

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

詳しくは、Jenkinsサーバの .../api/ を参照して下さい。

Jenkinsのバージョンの検出

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

ネットワーク上のJenkinsを検出する

JenkinsのインスタンスはUDP ポート33848をリッスンしています。JenkinsがUDPパケットを受け取ると、レスポンスとして接続情報を示す短いXMLフラグメントを返します。
XMLは下記のようなフォーマットになります:

<hudson>
  <version>1.380</version>           <!-- version of Jenkins -->
  <url>http://somwhere/jenkins/</url> <!-- HTTP URL. Not available if not configured -->
  <slave-port>12345</slave-port>     <!-- if TCP slave listener port is configured, its number -->
</hudson>

この情報を利用し、クライアントはUDPブロードキャストを通して最寄のJenkinsインスタンスを検出できます。この方法は、自律的なビルドクラスタを構成する場合にとても有効です。