狠狠撸

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

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

RedmineのREST APIRedmineのREST API
3

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

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

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

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

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

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

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

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

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

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

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

こんな感じの画面が出れば翱碍

APIで遊んでみるAPIで遊んでみる
16

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

{"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
{"id":22,"login":"example","firstname":"Some","lastname":"One","mail":"s
05-24T13:40:12Z","custom_fields":[{"id":4,"name":"Phone
{"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

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

{
"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

ユーザー一覧の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

フォーマット:?ログイン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

ユーザーを登録するユーザーを登録する
ファイル?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

ユーザーを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

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

チケット操作チケット操作
#
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

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

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

チケットを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

開始日が今日以前のチケットを抽出開始日が今日以前のチケットを抽出
コマンド
結果
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

未完了で、自分が担当で、更新日が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

題名が正規表現にマッチするチケットを探す題名が正規表現にマッチするチケットを探す
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

Redmine API 利用TIPSRedmine API 利用TIPS
33

レスポンスは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

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

認証は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

o?setを?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

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

デバッグには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

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

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

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

狠狠撸

Redmineをちょっと便利に! プログラミング無しで使ってみるREST API

Recommended

More Related Content

What's hot (20)

Similar to Redmineをちょっと便利に! プログラミング無しで使ってみるREST API (20)

More from Go Maeda (20)

Redmineをちょっと便利に! プログラミング無しで使ってみるREST API