業務ハッカーへの道 (#3 Redmine REST APIによる業務効率化)

RedmineFig1技術開発部の原田です。
通常業務の中から効率化できる部分を見つけて技術で解決する(ハックする)方法を提案しようと思います。

TL;DR ※まとめです

  • Redmine REST APIで、画面の操作なしにRedmineの操作が可能。
  • エラーログが発生した際にRedmineチケット登録するといった作業を自動化できる。
  • Redmine管理 -> API -> REST APIのチェックボックスをONでRedmine REST APIが使える。

はじめに

RedmineをAPIで操作する話です。本稿はチケット起票を自動化する手段を紹介します。

プロジェクト運営にあたり、Redmineはとても便利ですよね。
課題/不具合/QAなどをチケット化していると漏れなく作業が出来るので便利です。
不具合チケットを日々の業務の中で消化しているという方も多いことかと思われます。

ただ、日々の運用で使う際、不具合が発生した時などにチケットの入力作業が人力で行われているならば、まだ効率的な業務運営ではないと思います。
人の手で毎回起票しているとなると、起票内容が属人化してしまいます。
運用上も単純に面倒ですよね。安心してお酒も飲めません。
仮にエラーログが出力された場合、不具合チケットを自動的にRedmineに登録してくれるようになっていれば、人の手間が減って良いのではないでしょうか。

というわけで本稿では、ログファイルにエラーが出た際に、Redmineの不具合チケットが自動生成されるようにしてみます。
本稿が現場での機械的なチケット登録操作の工数削減に寄与することを願います。

RedmineのAPI詳細はコチラ→Redmine REST API
本稿ではHTTP REST リクエストを行うために、cURL(カール)を用います。cURLについてはコチラ→cURL(プロトコルのクライアントツール・ライブラリ)

本稿では以下を前提とします。

使用OS 問わない(Redmineサーバに対してcURLコマンドが実行できる環境ならば可)
前提知識 RedmineとcURLを知っている、普段業務として扱っている。
使用方法 コンソール
使用ソフトウェア cURL(コマンドラインツールであって、ソフトウェア?ですが)
環境前提 エラーログの出る環境から、RedmineサーバへのHTTPリクエストが届くこと(課題を単純化するため)

ただRedmine APIの使用について記載しても退屈なため、課題を設定します。

課題設定

課題

課題は導入部分での記載の通りとします。

  • エラーログが出力された場合に、エラーの内容を含んだ不具合チケットを登録する

なお、Remineのプロジェクト設定に依存する箇所については特に説明を行いません。

幸いRedmineにはREST APIが準備されています
RedmineでREST APIを使うためには、システム管理者での作業と利用者のAPIアクセスキーの取得が必要です。取得手順は備考で後述します。

ここではRedmine REST APIが使える状態にあり、利用者のAPIアクセスキーを把握しているものとします。

解答はこちらです。

これをコンソール画面から実行しておくと、エラーログが出力された場合に、不具合のチケットを自動的にRedmineに登録してくれます。

$ tail -f app.log | grep ERR | createIssueJson.sh && curl -X POST -H "Content-Type: application/json" --data-binary "@issue.json" "http://REDMINE_URL/redmine/issues.json?key=REDMINE_API_KEY"

※ REDMINE_URL : Redmineのホスト名やIPに置き換えて実行してください。
※ REDMINE_API_KEY : 利用者のAPIアクセスキーに置き換えて実行してください。
※ 本質でないので割愛しますが、createIssueJson.shの内容としては、ERRメッセージを受けたらjson形式のファイル(issue.json)を作成します。
issue.jsonファイルの内容は以下の通りです。ERR*****の部分には実際のエラーメッセージが含まれていると考えてください。

issue.json

{
  "issue": {
    "project_id":2,
    "tracker_id":2,
    "status_id":1,
    "priority_id":2,
    "subject": "APIテスト",
    "description": "ERR****"
  }
}

以上です。

・・・・すみません、あまりに省略しすぎでした(笑)解説します。

解説1

tail -f app.log | grep ERR | createIssueJson.sh まで

これは、ログファイル(app.log)に”ERR”という文字列が出力された場合にjson形式ファイル(issue.json)を作成するということを行っています。
Redmine APIを用いてHTTP(POST)リクエストを行うための下準備となります。例としてtail – grepからのshellで作成しています。
…が、ここではissue.jsonファイルさえ出来ていれば良く、この部分はどのように作成しても構いません。

ファイルの内容ですが、連想配列issueを作成し、
その要素としてプロジェクトID,トラッカーID,ステータスID,優先度ID,題名,説明を含むようにします。
※各IDの値は、登録したいRedmineのプロジェクト設定に合わせて適宜変更してください。
※Redmineのプロジェクトによってはカスタムフィールドの選択が必須になると思いますが、その場合は適宜要素を追加してください。

issue.json

{
  "issue": {
    "project_id":2,
    "tracker_id":2,
    "status_id":1,
    "priority_id":2,
    "subject": "APIテスト",
    "description": "ERR_MESSAGE"
  }
}

解説2

curl -X POST -H “Content-Type: application/json” –data-binary “@issue.json” “http://REDMINE_URL/redmine/issues.json?key=REDMINE_API_KEY”

ここが本投稿の本質部分です。

まず、RedmineはREST APIが用意されており、Redmineの画面経由でなくても、情報の参照/追加/更新/削除が出来るようになっています。
今回はREST APIのチケットを登録する機能を用いて、画面を経由せずにチケットを作成します。

curlコマンドにより、HTTP(POST)リクエストをRedmineサーバに向けて送信しています。
HTTPリクエストヘッダにjson形式であることを指定(-H “Content-Type: application/json”)して、json形式であるissue.jsonファイルの内容を宛先宛に送信していることになります。
(Redmineサーバの、issues.json宛にPOST送信することは、Redmineでは「チケットを作成すること」として解釈されます。)
そしてどのユーザが作成したかは、APIアクセスキーを元に判別されます。(APIアクセスキー情報はユーザIDを一意に特定できる情報なので流出すると危険です。)
上記のコマンドが成功した場合、画面を操作せずにRedmineのチケットが作成されます。Redmineのページから直接確認してください。

最後に

いかがでしょうか。
上記の通り、簡易的ではありますが、エラーメッセージが出た際にRedmineチケットの作成が自動化できました。
今回は「ERR」が含まれていた場合に動作するようにしましたが、特定のエラーメッセージにのみ反応するよう改変しても良さそうです。
実際の本番環境で同様のことをする場合、tail -f することは許されないと思うため、Zabbixからの通知などが入力ソースとなることでしょう。

Redmine REST APIはチケット登録以外にも機能があり、例えば以下のような操作がAPIから実施できます。

  • チケットを参照/更新/削除する
  • チケットにファイルを添付する
  • チケットにウォッチャーを登録/削除する(Redmine API ver 2.3より可能)
  • Redmineユーザを登録/更新/削除する

これを応用して、例えば以下のような冗長な作業を機械的に実施することが可能になると思います。
(オペレーションとして実施して良いかどうかはもちろん要検討)

  • 特定の条件に合ったチケットのステータスを強制的に進行させる
  • 特定のメンバーが起票した新規チケットに、自分をウォッチャーとして登録する

実際のところ、業務はRedmineに起票したところで終わりではありません。問題を解決することが必要です。
ただ、通常の業務のうち、起票という定型で冗長な作業について機械化することで、問題解決の時間を増やすことができると思います。
現場での冗長な作業が減少し、問題解決が進むことを願います。

ここまで読んでいただきありがとうございました。

備考

Redmine REST APIを用いるための事前手順やリクエスト例を記載します。

Redmine REST APIを使用可能にする手順(Redmineシステム管理者作業)

管理 → 設定 → API → RESTによるWebサービスを有効にする:チェックなし→チェックありにチェックを入れる。

RedmineのAPIアクセスキーを取得する手順(Redmine各ユーザ作業)

個人設定 → APIアクセスキー → 表示 表示文字列をコピーする。
ユーザ毎に異なるため、複数人で共有しないでください。

特定条件にあるチケット一覧を取得するリクエスト例

担当者のユーザIDが6、ステータスが未完了のチケット一覧を取得する

$ curl "http://REDMINE_URL/redmine/issues.json?assigned_to_id=6&status_id=open&key=REDMINE_API_KEY"

  • -XによるHTTPメソッドの指定は不要です。(省略するとGETになります)
  • assigned_to_idでユーザのIDを指定します。
  • status_idでステータスを指定します。(openは未完了状態にあるステータスすべて)
  • 送信するjsonファイルは不要です。
  • URL部分をそのままブラウザ(Firefox推奨)で表示してもデータを確認できます。

チケットを更新するリクエスト例

チケット番号XXXの説明の記述を上書きする。

$ curl -X PUT -H "Content-Type: application/json" --data-binary "@updateissue.json" "http://REDMINE_URL/redmine/issues/XXX.json?key=REDMINE_API_KEY"

updateissue.json

{
  "issue": {
    "description": "NEW_MESSAGE"
  }
}

※ jsonファイル内は変更したい項目のみ記述してください。説明文以外の部分を更新したい場合はdescription以外に任意の項目を増やすと良いです。

関連記事

  1. Zabbix 4.0の新機能の紹介

    Zabbix 4.0の新機能

  2. Zabbix 4.0の新機能の紹介

    Zabbix 4.0の新機能(追加版)

PAGE TOP