Posts Tagged ‘redmine’

Redmine APIによるデータ取得とjqで捗る話

水曜日, 8月 13th, 2014

RedmineのREST APIとjqコマンドで今更ながら色々捗るなーという話。

Redmine API

Redmine exposes some of its data through a REST API. This API provides access and basic CRUD operations (create, update, delete) for the resources described below. The API supports both XML and JSON formats.

jq

jq is like sed for JSON data – you can use it to slice and filter and map and transform structured data with the same ease that sed, awk, grep and friends let you play with text.

環境

jq version 1.3
Redmine version 2.5.2.stable

こんなチケットを作ってみて動かします。

チケット一覧画面

データを取ってくる

RedmineAPIはリクエストにAPI KEY(ユーザー管理画面より発行)を含めることで認証出来ます。

passed in as a “key” parameter
passed in as a username with a random password via HTTP Basic authentication
passed in as a “X-Redmine-API-Key” HTTP header (added in Redmine 1.1.0)

とドキュメントにあるように、三通りの方法があります。こんなに対応せんでもええんやないか、と思います。curlで叩いてみます。

keyパラメータを使用

curl -s http://redmine.mydomain.com/issues.json?key={myapikey}

Basic認証でユーザー名として使用(randome passwordって書いてああるけど無視されるので空でもよい)

curl -s http://{myapikey}@redmine.mydomain.com/issues.json

or

curl -s -u {myapikey}: http://redmine.mydomain.com/issues.json

X-Redmine-API-Key認証ヘッダを使用

curl -H "X-Redmine-API-Key:{myapikey}" -s http://redmine.mydomain.com/issues.json

認証に成功するとissuesのJSONがごちゃっと返ってきます。
そのままでは見づらいのでとりあえずjqに食わせてみます。

jqに渡してissuesの1件目を表示

curl -s  http://{myapikey}@redmine.mydomain.com/issues.json? | jq '.issues[0]'
{
  "updated_on": "2014-08-08T10:22:32Z",
  "created_on": "2014-08-08T10:19:40Z",
  "estimated_hours": 5,
  "done_ratio": 0,
  "start_date": "2014-08-08",
  "description": "機能追加タスク",
  "id": 4,
  "project": {
    "name": "myproject",
    "id": 1
  },
  "tracker": {
    "name": "機能",
    "id": 2
  },
  "status": {
    "name": "新規",
    "id": 1
  },
  "priority": {
    "name": "通常",
    "id": 2
  },
  "author": {
    "name": "Redmine Admin",
    "id": 1
  },
  "assigned_to": {
    "name": "Redmine Admin",
    "id": 1
  },
  "subject": "機能追加"
}

見やすいですね。

絞り込みとか加工とか

データが取れたので色々加工してみます。

自分のタスク情報を取得

自分にアサインされたissuesを取得してjqで表示項目を絞り込んでみる。

curl -s  http://{myapikey}@redmine.mydomain.com/issues.json?assigned_to_id=me | jq '.issues[] | {subject, id, assigned_to, estimated_hours}'
{
  "estimated_hours": 3,
  "assigned_to": {
    "name": "egmc .com",
    "id": 3
  },
  "id": 2,
  "subject": "機能追加だよ"
}
{
  "estimated_hours": 1.5,
  "assigned_to": {
    "name": "egmc .com",
    "id": 3
  },
  "id": 1,
  "subject": "バグだよ1"
}

文字列を整形してリストっぽくデータを取ってみる

jqは文字列内に取得したデータを入れ込んだり、各種演算子も使えたりするのでこんな出力も得られます。

curl -s http://{myapikey}@redmine.mydomain.com/issues.json?assigned_to_id=me | jq -r '.issues[] | "・#\(.id) \(.subject)[担当:\(.assigned_to.name)](\(.estimated_hours)h)"'
・#2 機能追加だよ[担当:egmc .com](3h)
・#1 バグだよ1[担当:egmc .com](1.5h)

作成済のカスタムクエリの条件を適用してみる

redmine側で作成した既存のカスタムクエリの出力をjsonで得ることも出来ます。
issuesのAPIにはないのですが、下記のように画面表示と同じURL構造にして/projects/{プロジェクト名}/issues.json?query_id={クエリID}というリクエストを送るとカスタムクエリの条件が適用されます。
というか単純に画面でリストを表示して、拡張子を.jsonとか.xmlにすることによってその形式で出力してくれるようです(なのでこちらは厳密にはAPIで提供されてるわけではないっぽい)

「担当が自分で見積もり時間が2以上かかるタスク」という条件のカスタムクエリで試してみます。

カスタムクエリ

curl -s http://{myapikey}@redmine.mydomain.com/projects/myproject/issues.json?query_id=3 | jq '.issues[] | {subject, id, assigned_to, estimated_hours}'
{
  "estimated_hours": 3,
  "assigned_to": {
    "name": "egmc .com",
    "id": 3
  },
  "id": 2,
  "subject": "機能追加だよ"
}

コマンドを組み合わせて集計とか

パイプでawkなどに渡すことによって簡単な集計処理も出来ます。

見積もり時間の合計を取得

curl -s http://{myapikey}@redmine.mydomain.com/issues.json?assigned_to_id=me | jq '.issues[].estimated_hours' | awk '{m+=$1} END{print m}'
4.5

特定の期間内のチケットの集計とか工夫次第で色々出来そうですね。

まとめ

RedmineAPIとjqの組み合わせでコマンドラインから色々出来るのでベンリだよ!という事を言いたかった。
とはいえ各種コマンドとの組み合わせでもうちょっとベンリに使える気がするのでシェル力アップのためにもうちょっと勉強しようと思います。