WekanAPIとjqを使ってカードから作業時間を抽出してみた話

はじめに

かんばん方式タスク管理ツール「Wekan」を用いてタスク管理をしている。
様々なAPIも提供されてるようなので、それらを使ってカードから情報を抽出してみる。

環境

• クライアントPC：Windows10 Pro
• コマンド：Git Bash

WekanのAPIを呼び出す

WekanがREST APIを提供してくれているのでそれを使う。

できることを要約すると、以下の通り。

　- ログイン処理
　- ユーザ一覧、ログイン済みユーザ一覧
　- ユーザの登録・有効化・無効化・情報取得
　- カードの登録・削除・更新　などが挙げられる

公式にも記載されてるが、まだまだ未完成状態のよう。

アクセストークンの取得

ログイン状態でないとカードを見れないため、事前にトークンを発行する。
※${ServerName}、${email}、${password}は適宜入力すること

HTTP Method	Url	Short Description
POST	/users/login	Authenticate with the REST API.

$ curl http://${ServerName}/users/login \
  -d "email=${email}&password=${password}" -s
{"id":"FtDartLCavnm2NbFC","token":"YLerKsBaQMP3MwX7iLRioWKHXbewQ-e9jyPLcFbL1Nw","tokenExpires":"2019-03-17T01:28:38.347Z"}

これ以降の処理ではヘッダにトークン情報をセットしてカード情報を取得する。

swinlaneidの取得

対象のスイムレーン一覧を取得する。※かんばんの各行のidに該当する箇所

HTTP Method	Url	Short Description
GET	/api/boards/:boardId/swimlanes	REST API Swimlanes

$ curl -X GET -H "Authorization: Bearer YLerKsBaQMP3MwX7iLRioWKHXbewQ-e9jyPLcFbL1Nw" \ 
http://${ServerName}/api/boards/pMBEMbm2KfrR2P73n/swimlanes -s 
[{"_id":"qHg6qGGShDPmgdrN4","title":"tasks"},{"_id":"sSjG6txBwCGcSviPW","title":"event"},{"_id":"AYcP8gYYDpK2niCxX","title":"backlog"},{"_id":"w53X5PSWDt28dzxxN","title":"sprint"}]

カードの取得

上記で取得したスイムレーン内のカード一覧を取得する。※特定の行に含まれる全てのカード

HTTP Method	Url	Short Description
GET	/api/boards/:boardId/swimlanes/:swimlaneId/cards	REST-API-Cards

$ curl -X GET -H "Authorization: Bearer YLerKsBaQMP3MwX7iLRioWKHXbewQ-e9jyPLcFbL1Nw" \
http://${ServerName}/api/boards/pMBEMbm2KfrR2P73n/swimlanes/w53X5PSWDt28dzxxN/cards -s
[{"_id":"FRDjZf9FQcZ4ayXip","title":"Java11検証:2h","description":"","listId":"uK7Thp97rGdtEXQvC"},{"_id":"EmXHtfv7d3y2FQkkM","title":"UnitTest:3h","description":"","listId":"uK7Thp97rGdtEXQvC"},]

jqツールを使用

返却されたJSON形式データはコンソールに一行で表示されるため見づらい。

そのため、文字列の整形やデータの抽出機能を持つツール「jq」を使う。

インストール

公式のダウンロードからインストールしようとしたが、exeが実行できないので別の方法で試す。

以下のサイトを参考に、別の方法としてWindowsのパッケージマネージャChocolateyで入れる。

jsonを楽に扱えるjqコマンドを導入(Mac, Windows)

確認OK

$ chocolatey list jq
Chocolatey v0.10.11
jq 1.5

JSONを整形して出力

パイプでjq .をつなぐ。

$ curl -X GET -H "Authorization: Bearer YLerKsBaQMP3MwX7iLRioWKHXbewQ-e9jyPLcFbL1Nw" \
http://${ServerName}/api/boards/pMBEMbm2KfrR2P73n/swimlanes/w53X5PSWDt28dzxxN/cards -s | jq .
[
  {
    "_id": "FRDjZf9FQcZ4ayXip",
    "title": "Java11検証:2h",
    "description": "",
    "listId": "uK7Thp97rGdtEXQvC"
  },
  {
    "_id": "n7dHW6KsDMGaRjkTA",
    "title": "UnitTest:3h",
    "description": "",
    "listId": "uK7Thp97rGdtEXQvC"
  }
]

jqツールの活用

:以降に2hのように作業時間を記載しているので、すべてのカードの合計値を計算してみる。

リスト内のカードで絞り込み

タスクのステータスが「TODO」「DOING」「DONE」に分かれているため、

select関数を用いてリストIDで「TODO」に絞り込む。※かんばんの各行のidに該当する箇所

$ curl -X GET -H "Authorization: Bearer YLerKsBaQMP3MwX7iLRioWKHXbewQ-e9jyPLcFbL1Nw" \
http://${ServerName}/api/boards/pMBEMbm2KfrR2P73n/swimlanes/w53X5PSWDt28dzxxN/cards -s \
| jq '.[] | select(.listId == "uK7Thp97rGdtEXQvC" or.listId == "JCsuKobA4wBL8jvmb")'
{
  "_id": "FRDjZf9FQcZ4ayXip",
  "title": "Java11検証:2h",
  "description": "",
  "listId": "uK7Thp97rGdtEXQvC"
}
{
  "_id": "n7dHW6KsDMGaRjkTA",
  "title": "UnitTest:3h",
  "description": "",
  "listId": "uK7Thp97rGdtEXQvC"
}

カードの中身で絞り込み

カード内のタイトルのみが欲しいのでキー(title)で絞り込む。

$ curl -X GET -H "Authorization: Bearer YLerKsBaQMP3MwX7iLRioWKHXbewQ-e9jyPLcFbL1Nw" \
http://${ServerName}/api/boards/pMBEMbm2KfrR2P73n/swimlanes/w53X5PSWDt28dzxxN/cards | \
 jq '.[] | select(.listId == "uK7Thp97rGdtEXQvC" or.listId == "JCsuKobA4wBL8jvmb") | .title'
"Java11検証:2h"
"UnitTest:3h"

余計なダブルクオーテーションを削除する

オプション-rを付与する。

$ curl -X GET -H "Authorization: Bearer YLerKsBaQMP3MwX7iLRioWKHXbewQ-e9jyPLcFbL1Nw" \
http://${ServerName}/api/boards/pMBEMbm2KfrR2P73n/swimlanes/w53X5PSWDt28dzxxN/cards -s | \
jq '.[] | select(.listId == "uK7Thp97rGdtEXQvC" or.listId == "JCsuKobA4wBL8jvmb") | .title' -r
Java11検証:2h
UnitTest:3h

作業時間のみを抽出する

splitで:より後ろの文字列を取得し、gsubでhを削除する。

$ curl -X GET -H "Authorization: Bearer YLerKsBaQMP3MwX7iLRioWKHXbewQ-e9jyPLcFbL1Nw" \
http:/${ServerName}/api/boards/pMBEMbm2KfrR2P73n/swimlanes/w53X5PSWDt28dzxxN/cards  -s | \
jq -c '.[] | select(.listId == "uK7Thp97rGdtEXQvC" or.listId == "JCsuKobA4wBL8jvmb") | .title | split(":")[1] | gsub("h";"") | tonumber' -r
2
3

作業時間を配列にする

数値形式の配列でないと合計値が算出できないため、tonumberで数値変換かつ[]で囲む。

$ curl -X GET -H "Authorization: Bearer YLerKsBaQMP3MwX7iLRioWKHXbewQ-e9jyPLcFbL1Nw" \
http://${ServerName}/api/boards/pMBEMbm2KfrR2P73n/swimlanes/w53X5PSWDt28dzxxN/cards  -s | \
jq -c '[.[] | select(.listId == "uK7Thp97rGdtEXQvC" or.listId == "JCsuKobA4wBL8jvmb") | .title | split(":")[1] | gsub("h";"") | tonumber]' -r
[2,3]

合計を算出する

addで配列内の数値の合計値を求める。

$ curl -X GET -H "Authorization: Bearer YLerKsBaQMP3MwX7iLRioWKHXbewQ-e9jyPLcFbL1Nw" \
http://${ServerName}/api/boards/pMBEMbm2KfrR2P73n/swimlanes/w53X5PSWDt28dzxxN/cards -s | \
jq -c '[.[] | select(.listId == "uK7Thp97rGdtEXQvC" or.listId == "JCsuKobA4wBL8jvmb") | \
.title | split(":")[1] | gsub("h";"") | tonumber] | add' -r
5

参考

• jqを活用してAPIレスポンス等から欲しい情報だけを抽出する
• jq コマンドを使う日常のご紹介
• jqコマンドで覚えておきたい使い方17個
• jq Manual