JenkinsJobの情報を取得する

はじめに

jobの実行状況(しっかり動いているか、成功しているか)を監視できるような仕組みを作る必要があり、
備忘のため、そういった情報をjenkinsの基本的なディレクトリ構成から取得方法までをまとめました。

Jenkinsの基本的なディレクトリ構成

jenkinsのホームディレクトリは/var/lib/jenkinsに設定されます。
各jobは配下のjobsにjob名ごとにディレクトリが存在しています。

/var/lib/jenkins/jobs/${JOB_NAME}
　├ config.xml
　├ builds/
　　├${BUILD_NUMBER}/
　　　　├ build.xml
　　　　├ changelog.xml
　　　　├ log

各jobの設定ファイルは${JENKINS_HOME}/jobs/${JOB_NAME}/config.xmlに配置されます。
ここのconfig.xmlまたはjenkinsコンソールを編集することでjobの設定を変更することが可能です。

各jobのbuildごとの実行情報は${JENKINS_HOME}/jobs/${JOB_NAME}/builds/${BUILD_NUMBER}/build.xmlに保存されます。

job情報 config.xml

config.xmlには下記の情報などが記載されます。
・jobの説明
・jobのデフォルト有効化フラグ
・実行されるスクリプト
(設定がある場合)
・上流job
・必要とされるパラメータ情報
・トリガー/実行タイミング(crontab形式で設定)
・過去のbuildの保存日数/保存最大数
　　などなど・・・

Build情報　build.xml

build.xmlには下記の情報などが記載されます。
・登録時間
・開始時間
・実行結果
・実行時間
・作業ディレクトリ情報
(設定がある場合)
・パラメータ情報
　　などなど・・・

job/build情報の取得

取得方法

jenkinsサーバからであれば上記のxmlファイルを参照することで基本的な情報を取得することは可能です。
他のサーバからアクセスする場合や、より詳細な情報を取得する際にはそのためのAPIが用意されています。

取得方法・取得可能情報について解説します。

API実行の基本文法

#jenkins内のjob一覧取得
 curl -X POST http://${JENKINS_HOST}/jenkins/api/json　
#jenkinsのjob情報取得
 curl -X POST http://${JENKINS_HOST}/jenkins/job/${JOB_NAME}/api/json
#対象jobのbuild番号別情報取得
 curl -X POST http://${JENKINS_HOST}/jenkins/job/${JOB_NAME}/${BUILD_NUMBER}/api/json

${JENKINS_HOST}の部分を自身(localhost:8080)に変更することでそのサーバ自身の情報取得も可能です。
結果はjsonで返ってきますが、最後のjson部分をxmlにすることでxml形式でも取得可能です。

取得可能情報

※各種結果class,プロパティはjenkins公式を参照

実行コマンド

#jenkins内のjob一覧取得
 curl -X POST http://${JENKINS_HOST}/jenkins/api/json

結果sample1

{
  "_class": "hudson.model.Hudson",
  "assignedLabels": [
    {
      "name": "master"
    }
  ],
  "mode": "NORMAL",
  "nodeDescription": "the master Jenkins node",
  "nodeName": "",
  "numExecutors": 3,
  "description": null,
  "jobs": [
    {
      "_class": "hudson.model.FreeStyleProject",
      "name": "job1",
      "url": "http://${JENKINS_HOST}/jenkins/job/job1/",
      "color": "blue"
    },
    {
      "_class": "hudson.model.FreeStyleProject",
      "name": "job2",
      "url": "http://${JENKINS_HOST}/jenkins/job/job1/",
      "color": "disabled"
    },
    {
      "_class": "hudson.model.FreeStyleProject",
      "name": "job3",
      "url": "http://${JENKINS_HOST}/jenkins/job/job1/",
      "color": "blue_anime"
    }
  ],
  "overallLoad": {},
  "primaryView": {
    "_class": "hudson.model.AllView",
    "name": "all",
    "url": "http://${JENKINS_HOST}/"
  },
  "quietingDown": false,
  "slaveAgentPort": -1,
  "unlabeledLoad": {
    "_class": "jenkins.model.UnlabeledLoadStatistics"
  },
  "useCrumbs": false,
  "useSecurity": false
}

実行コマンド

#jenkinsのjob情報取得
 curl -X POST http://${JENKINS_HOST}/jenkins/job/${JOB_NAME}/api/json

結果sample2

{
  "_class": "hudson.model.FreeStyleProject",
  "actions": [
    {
      "_class": "com.cloudbees.plugins.credentials.ViewCredentialsAction"
    }
  ],
  "description": "ここにはjobの説明",
  "displayName": "jobの表示名",
  "displayNameOrNull": null,
  "fullDisplayName": "job名の表示フルテキスト",
  "fullName": "job名のフルテキスト",
  "name": "jobの名前",
  "url": "http://${JENKINS_HOST}/jobs/${JOB_NAME}/",
  "buildable": false,
  "builds": [
    {
      "_class": "hudson.model.FreeStyleBuild",
      "number": 1,
      "url": "http://${JENKINS_HOST}/jobs/${JOB_NAME}/1/"
    }
  ]
  "color": "disabled",
  "firstBuild": {
    "_class": "hudson.model.FreeStyleBuild",
    "number": 1,
    "url": "http://${JENKINS_HOST}/jobs/${JOB_NAME}/1/"
  },
  "healthReport": [
    {
      "description": "Build stability: No recent builds failed.",
      "iconClassName": "icon-health-80plus",
      "iconUrl": "health-80plus.png",
      "score": 100
    }
  ],
  "inQueue": false,
  "keepDependencies": false,
  "lastBuild": {
    "_class": "hudson.model.FreeStyleBuild",
    "number": 1,
    "url": "http://${JENKINS_HOST}/jobs/${JOB_NAME}/1/"
  },
  "lastCompletedBuild": {
    "_class": "hudson.model.FreeStyleBuild",
    "number": 1,
    "url": "http://${JENKINS_HOST}/jobs/${JOB_NAME}/1/"
  },
  "lastFailedBuild": null,
  "lastStableBuild": {
    "_class": "hudson.model.FreeStyleBuild",
    "number": 1,
    "url": "http://${JENKINS_HOST}/jobs/${JOB_NAME}/1/"
  },
  "lastSuccessfulBuild": {
    "_class": "hudson.model.FreeStyleBuild",
    "number": 1,
    "url": "http://${JENKINS_HOST}/jobs/${JOB_NAME}/1/"
  },
  "lastUnstableBuild": null,
  "lastUnsuccessfulBuild": null,
  "nextBuildNumber": 2,
  "property": [],
  "queueItem": null,
  "concurrentBuild": false,
  "downstreamProjects": [],
  "labelExpression": null,
  "scm": {
    "_class": "hudson.scm.NullSCM"
  },
  "upstreamProjects": []
}

実行コマンド

#対象jobのbuild番号別情報取得
 curl -X POST http://${JENKINS_HOST}/jenkins/job/${JOB_NAME}/${BUILD_NUMBER}/api/json

結果sample3

{
  "_class": "hudson.model.FreeStyleBuild",
  "actions": [
    {
      "_class": "hudson.model.CauseAction",
      "causes": [
        {
          "_class": "hudson.model.Cause$UserIdCause",
          "shortDescription": "Started by user anonymous",
          "userId": null,
          "userName": "anonymous"
        }
      ]
    }
  ],
  "artifacts": [],
  "building": false,
  "description": null,
  "displayName": "#1",
  "duration": 100,
  "estimatedDuration": 100,
  "executor": null,
  "fullDisplayName": "job1 #1",
  "id": "1",
  "keepLog": false,
  "number": 1,
  "queueId": 1,
  "result": "SUCCESS",
  "timestamp": 1575005659380,
  "url": "http://${JENKINS_HOST}/jobs/${JOB_NAME}/1/",
  "builtOn": "",
  "changeSet": {
    "_class": "hudson.scm.EmptyChangeLogSet",
    "items": [],
    "kind": null
  },
  "culprits": []
}

また下記のように、より詳細な情報を取得するにはdepthパラメータを付与することで詳細階層を指定できます。
値の数値を大きくすればするほど詳細なレスポンスを取得できます。

#jenkins内のjob一覧取得 depth=1
 curl -X POST http://${JENKINS_HOST}/jenkins/api/json?depth=1

おまけ　APIの結果をより見やすく

jqコマンドを利用するとAPIの結果をより見やすく整形・取得してくれます。

jobのURLを取得する例

#APIの実行結果をjob.txtに格納
curl-X POST http://${JENKINS_HOST}/jenkins/api/json > job.txt
#結果sample1から1つめのjobのURLを取得
cat job.txt | jq .jobs[1].url

結果

"http://${JENKINS_HOST}/jenkins/job/job1/"

参考

JenkinsAPIでジョブ情報を取得する
jqコマンドを使う日常のご紹介