RedmineのREST APIを利用すると、外部のアプリケーションからRedmineのデータにアクセスできます。 これまでAPIを利用したことがない方にも簡単な手順でRedmineをちょっと便利に使っていただくために、プログラミング無しでREST APIを使う例を紹介します。 HTML版: https://vividtone.github.io/redmine-tokyo-slide-20180526/ 2018/05/26 Redmine東京 第14回勉強会講演資料 https://redmine.tokyo/versions/30

1. Redmineをちょっと便利に!
プログラミング無しで使ってみるREST API
前田剛
(ファーエンドテクノロジー株式会社)
2018/05/26 redmine.tokyo
スライド公開URL:
h ps://vividtone.github.io/redmine‐tokyo‐slide‐20180526/
1

2. プログラミングをせずに、コマンドラインツールの組み合わせでRedmineのAPIにアクセス
してみます。
curl: HTTPリクエストを行う
jq: JSONデータを整形・加工する
2

3. RedmineのREST APIRedmineのREST API
3

4. REST APIとはREST APIとは
Redmineが持つデータに、外部から
（Web UIを経由せず）アクセスできる仕組み。
4

5. アクセス方法アクセス方法
HTTPでリクエストすると、XMLまたはJSON形式のレスポンスが帰ってくる
5

6. REST APIの何がうれしい?REST APIの何がうれしい?
他システムからRedmineを操作できる
自動化、チャットボットなど
Web UIの操作ではできないことが実現できる
6

7. APIを利用したツール例APIを利用したツール例
1. Redmineチケット★一括★
2. Redmine No fier
7

8. ①Redmineチケット★一括★
Excelファイルを読み込んでチケットを登録
h ps://www.vector.co.jp/so /winnt/u l/se503347.html
8

9. ②Redmine No fier
チケットの更新をデスクトップに通知
h ps://github.com/emsk/redmine‐no fier
9

10. REST APIの利用準備REST APIの利用準備
10

11. 前提条件前提条件
コマンドラインからAPIを利用してみます
扱いやすいJSON形式を利用します
APIへのアクセスを行う端末のOSは Ubuntu または macOS を想定しています
Windowsの人は Windows Subsystem for Linux をインストールするなどしてください
11

12. REST APIを有効にするREST APIを有効にする
「管理」→「設定」→「API」タブの「RESTによるWebサービスを有効にする」をON
12

13. jq をPCにインストールするjq をPCにインストールする
jq はJSON形式のテキストを整形・加工するツール。APIで取得したデータの処理に使う。
ubuntu:ubuntu:
macOS:macOS:
sudo apt-get install jq
brew install jq
13

14. APIにアクセスできるかテストAPIにアクセスできるかテスト
curl --user ID: 'http://redmine.test/issues.json?limit=1'
| jq .
14

15. こんな感じの画面が出ればOK

16. 15

17. APIで遊んでみるAPIで遊んでみる
16

18. ユーザー一覧の取得ユーザー一覧の取得
Redmineのユーザー一覧をJSON形式で取得する
curl --user admin: 'http://redmine.test/users.json?limit=100'
17

19. {"users":
[{"id":1,"login":"admin","firstname":"Redmine","lastname":"Admin","mail"
07-19T17:12:21Z","last_login_on":"2018-05-
25T20:24:22Z","custom_fields":[{"id":4,"name":"Phone
number","value":""},{"id":5,"name":"Money","value":""}]},
{"id":3,"login":"dlopper","firstname":"Dave","lastname":"Lopper","mail":
07-19T17:33:19Z","custom_fields":[{"id":4,"name":"Phone
number","value":""},{"id":5,"name":"Money","value":""}]},
{"id":22,"login":"example","firstname":"Some","lastname":"One","mail":"s
05-24T13:40:12Z","custom_fields":[{"id":4,"name":"Phone
number","value":""},{"id":5,"name":"Money","value":""}]},
{"id":2,"login":"jsmith","firstname":"John","lastname":"Smith","mail":"j
07-19T17:32:09Z","last_login_on":"2006-07-
19T20:42:15Z","custom_fields":[{"id":4,"name":"Phone
number","value":"01 42 50 00 00"},{"id":5,"name":"Money","value":""}]},
18

20. jq で見やすく整形jq で見やすく整形
curl --user admin: 'http://redmine.test/users.json?limit=100' |
jq .
19

21. {
"users": [
{
"id": 1,
"login": "admin",
"firstname": "Redmine",
"lastname": "Admin",
"mail": "admin@somenet.foo",
"created_on": "2006-07-19T17:12:21Z",
"last_login_on": "2018-05-25T20:33:44Z",
"custom_fields": [
{
"id": 4,
"name": "Phone number",
"value": ""
20

22. ユーザー一覧のJSONをCSVに変換ユーザー一覧のJSONをCSVに変換
1. users[] の値を取り出して、
2. 各ユーザーのデータから必要な値を取り出して配列に変換して、
3. CSVに変換
curl --user admin: http://redmine.test/users.json | jq -r
'.users[] | [.login, .mail, .firstname, .lastname] | @csv'
21

23. フォーマット: ログインID,メールアドレス,名,姓
"admin","admin@somenet.foo","Redmine","Admin"
"dlopper","dlopper@somenet.foo","Dave","Lopper"
"jsmith","jsmith@somenet.foo","John","Smith"
"miscuser8","miscuser8@foo.bar","User","Misc"
"miscuser9","miscuser9@foo.bar","User","Misc"
"rhill","rhill@somenet.foo","Robert","Hill"
"someone","someone@foo.bar","Some","One"
22

24. ユーザーを登録するユーザーを登録する
ファイル newuser.json を用意して
実行
{
"user": {
"login": "maeda",
"mail": "maeda@example.com",
"firstname": " ",
"lastname": " ",
"password": "I3JlZG1pbmV0"
}
}
cat newuser.json | curl 'http://redmine.test/users.json' --user admin:
--header 'Content-type: application/json' --data @-
23

25. ユーザーをCSVから一括登録するユーザーをCSVから一括登録する
ファイル user.csv を用意して
実行
user0001,foo@example.com,Joe,Bloggs,HiaH4JJd
user0002,bar@example.com,Jane,Public,9iQYyLn5
user0003,baz@example.com,Chris,Wong,dG9EFggG
cat /tmp/users.csv | while read LINE
do
echo $LINE | jq -R 'gsub(""";"") | split(",") | {"user": {"login": .
[0], "mail": .[1], "firstname": .[2], "lastname": .[3], "password": .
[4]}}' | curl -v 'http://redmine.test/users.json' --user admin:
--header 'Content-type: application/json' --data @-
done
24

26. 1. 1行ずつ読み取りコマンド実行:
2. ダブルクォーテーションを削除:
3. コンマで分割:
4. JSONに変換:
5. 標準入力からJSONを受け取りAPIを呼び出してユーザー登録:
cat /tmp/users.csv | while read LINE
do
echo $LINE | jq -R 'gsub(""";"") | split(",") | {"user": {"login": .
[0], "mail": .[1], "firstname": .[2], "lastname": .[3], "password": .
[4]}}' | curl 'http://redmine.test/users.json' --user admin: --
header 'Content-type: application/json' --data @-
done
25

27. チケット操作チケット操作
#
curl http:// /issues.json --user ID:
#
curl http:// /issues/1.json --user ID:
#
curl http:// /issues.json --user ID: --header
'Content-type: application/json' --data '{"issue": {"project_id": 1,
"tracker_id": 1, "subject": " ", "description": " "}}'
#
curl http:// /issues/5.json --user ID: --request
'PUT' --header 'Content-type: application/json' --data '{"issue":
{"subject": " ", "description": " "}}'
#
curl http:// /issues/16.json --user ID: --request
'DELETE'
26

28. 指定したチケットを取得する指定したチケットを取得する
curl --user ID: 'http://redmine.test/issues/1.json' | jq .
27

29. {
"issue": {
"id": 1,
"project": {
"id": 1,
"name": "eCookbook"
},
"tracker": {
"id": 1,
"name": "Bug"
},
"status": {
"id": 1,
"name": "New"
},
28

30. チケットを1行のテキストに変換チケットを1行のテキストに変換
コマンド
結果
curl --user ID: 'http://redmine.test/issues/1.json?
limit=100' | jq '.issue | "(.tracker.name) #(.id) - (.subject) (
(.status.name)) http://redmine.test/issues/(.id)" | @text'
Bug #1 - Cannot print recipes (New) http://redmine.test/issues/1
29

31. 開始日が今日以前のチケットを抽出開始日が今日以前のチケットを抽出
コマンド
結果
curl --user ID: "http://redmine.test/issues.json?
limit=100&start_date=<=`date +%Y-%m-%d`&sort=start_date" | jq -r
'.issues[] | "(.tracker["name"]) #(.id) - (.subject) (
(.start_date))" | @text'
Bug #3 - Error 281 when updating a recipe (2018-05-08)
Bug #7 - Issue due today (2018-05-13)
Feature request #2 - Add ingredients categories (2018-05-21)
Bug #1 - Cannot print recipes (2018-05-22)
Bug #6 - Issue of a private subproject (2018-05-23)
Bug #9 - Blocked Issue (2018-05-23)
Bug #10 - Issue Doing the Blocking (2018-05-23)
30

32. 未完了で、自分が担当で、更新日が7日以上前のチケット未完了で、自分が担当で、更新日が7日以上前のチケット
から1件をランダムに表示から1件をランダムに表示
コマンド
結果
curl --user ID: "http://redmine.test/issues.json?
limit=100&assigned_to_id=me&updated_on=<=`date -v-7d +%Y-%m-%d`" | jq -
r '.issues[] | "(.tracker.name) #(.id) - (.subject) ((.updated_on))
http://redmine.test/issues/(.id)" | @text' | python -c 'import sys,
random; print(random.choice(sys.stdin.readlines()));'
Bug #3 - Error 281 when updating a recipe (2006-07-19T19:07:27Z)
http://redmine.test/issues/3
31

33. 題名が正規表現にマッチするチケットを探す題名が正規表現にマッチするチケットを探す
1万件の未完了チケットの中から、題名が にマッチするチケットを探す
※すごく遅いです
for OFFSET in `seq 0 100 10000`; do curl --user ID:
"https:// /issues.json?limit=100&offset=$OFFSET" | jq -r
'.issues[] | select(.subject | test(" | "; "i")) | "
(.tracker["name"]) #(.id) - (.subject)"'; done
32

34. Redmine API 利用TIPSRedmine API 利用TIPS
33

35. レスポンスはXMLかJSONレスポンスはXMLかJSON
URLの拡張子でXMLかJSONか決まる
コマンドラインで使うなら JSON がおすすめ。 jq が強力で、また 登録用データを作るのもXMLより楽
# XML
curl --user ID: 'http://redmine.test/issues/1.xml'
# JSON
curl --user ID: 'http://redmine.test/issues/1.json'
34

36. 1回のリクエストで取得できるのは最大100件1回のリクエストで取得できるのは最大100件
デフォルトは25件。URLのパラメータ を指定して増やせるが、上限は100
それ以上のデータを取得するには の値を変えながら複数のリクエストを行う
# 0..99
curl --user admin: 'http://redmine.test/users.json?limit=100'
# 100..199
curl --user admin: 'http://redmine.test/users.json?
limit=100&offset=100'
# 200..299
curl --user admin: 'http://redmine.test/users.json?
limit=100&offset=200'
35

37. 認証はbasic認証またはAPIキーで行う認証はbasic認証またはAPIキーで行う
basic認証basic認証
APIキーAPIキー
APIキーは「個人設定」画面のサイドバー内「APIアクセスキー」で確認する
curl --user ID: 'http://redmine.test/issues.json'
curl --header 'X-Redmine-API-Key: API '
'http://redmine.test/issues.json'
36

38. offsetを 0 から 900 まで100ずつ増やしながら10回のリクエストを行う例
for OFFSET in `seq 0 100 900`; do curl --user admin:
"http://redmine.test/users.json?limit=100&offset=$OFFSET" | jq -r
'.users[] | [.login, .mail, .firstname, .lastname] | @csv'; done >
support-users.csv
37

39. 一部のオブジェクトはシステム管理者権限が必要一部のオブジェクトはシステム管理者権限が必要
ユーザー、グループ、カスタムフィールドの一覧など
38

40. デバッグにはcurl のデバッグにはcurl の オプションが便利オプションが便利
ヘッダが見えるのでRedmineサーバとの通信で何が起こっているか把握しやすい
#
$ curl -v --user ID: "http://redmine.test/users.json"
.
( )
.
< HTTP/1.1 403 Forbidden
< X-Frame-Options: SAMEORIGIN
< X-XSS-Protection: 1; mode=block
< X-Content-Type-Options: nosniff
< Content-Type: application/json
.
.
39

41. 情報源情報源
Redmine API
ドキュメント化されていない機能が一部あるjq
h p://www.redmine.org/projects/redmine/wiki/Rest_api
h ps://stedolan.github.io/jq/manual/
40

42. まとめまとめ
41

43. curl と jq を使えば、プログラミング無しでAPIを活用できる。案外簡単!
Web UIでできないこともAPIを使えば実現できる場合あり
ちょっとした自動化にも使えそう
APIでRedmineをちょっと便利に!
42

44. ありがとうございましたありがとうございました
前田剛 ( )
ファーエンドテクノロジー株式会社
代表取締役
というサイトを運営してます
「 」という本を書きました
Redmineのコミッターとして開発を手伝っています
@g_maeda
Redmine.JP
入門Redmine
43