Ce diaporama a bien été signalé.
Nous utilisons votre profil LinkedIn et vos données d’activité pour vous proposer des publicités personnalisées et pertinentes. Vous pouvez changer vos préférences de publicités à tout moment.

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

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

Livres associés

Gratuit avec un essai de 30 jours de Scribd

Tout voir
  • Soyez le premier à commenter

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

  1. 1. Redmineをちょっと便利に!  プログラミング無しで使ってみるREST API   前田剛  (ファーエンドテクノロジー株式会社) 2018/05/26 redmine.tokyo スライド公開URL:  h ps://vividtone.github.io/redmine‐tokyo‐slide‐20180526/ 1
  2. 2. プログラミングをせずに、コマンドラインツールの組み合わせでRedmineのAPIにアクセス してみます。 curl: HTTPリクエストを行う jq: JSONデータを整形・加工する 2
  3. 3. RedmineのREST APIRedmineのREST API 3
  4. 4. REST APIとはREST APIとは Redmineが持つデータに、外部から  (Web UIを経由せず)アクセスできる仕組み。 4
  5. 5. アクセス方法アクセス方法 HTTPでリクエストすると、XMLまたはJSON形式のレスポンスが帰ってくる 5
  6. 6. REST APIの何がうれしい?REST APIの何がうれしい? 他システムからRedmineを操作できる 自動化、チャットボットなど Web UIの操作ではできないことが実現できる 6
  7. 7. APIを利用したツール例APIを利用したツール例 1. Redmineチケット★一括★ 2. Redmine No fier 7
  8. 8. ①Redmineチケット★一括★ Excelファイルを読み込んでチケットを登録 h ps://www.vector.co.jp/so /winnt/u l/se503347.html 8
  9. 9. ②Redmine No fier チケットの更新をデスクトップに通知 h ps://github.com/emsk/redmine‐no fier 9
  10. 10. REST APIの利用準備REST APIの利用準備 10
  11. 11. 前提条件前提条件 コマンドラインからAPIを利用してみます 扱いやすいJSON形式を利用します APIへのアクセスを行う端末のOSは Ubuntu または macOS を想定しています Windowsの人は Windows Subsystem for Linux をインストールするなどしてください 11
  12. 12. REST APIを有効にするREST APIを有効にする 「管理」→「設定」→「API」タブの「RESTによるWebサービスを有効にする」をON 12
  13. 13. jq をPCにインストールするjq をPCにインストールする jq はJSON形式のテキストを整形・加工するツール。APIで取得したデータの処理に使う。 ubuntu:ubuntu: macOS:macOS: sudo apt-get install jq brew install jq 13
  14. 14. APIにアクセスできるかテストAPIにアクセスできるかテスト curl --user ID: 'http://redmine.test/issues.json?limit=1' | jq . 14
  15. 15. こんな感じの画面が出ればOK
  16. 16. 15
  17. 17. APIで遊んでみるAPIで遊んでみる 16
  18. 18. ユーザー一覧の取得ユーザー一覧の取得 Redmineのユーザー一覧をJSON形式で取得する curl --user admin: 'http://redmine.test/users.json?limit=100' 17
  19. 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. 20. jq で見やすく整形jq で見やすく整形 curl --user admin: 'http://redmine.test/users.json?limit=100' | jq . 19
  21. 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. 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. 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. 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. 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. 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. 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. 28. 指定したチケットを取得する指定したチケットを取得する curl --user ID: 'http://redmine.test/issues/1.json' | jq . 27
  29. 29. { "issue": { "id": 1, "project": { "id": 1, "name": "eCookbook" }, "tracker": { "id": 1, "name": "Bug" }, "status": { "id": 1, "name": "New" }, 28
  30. 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. 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. 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. 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. 34. Redmine API 利用TIPSRedmine API 利用TIPS 33
  35. 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. 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. 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. 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. 39. 一部のオブジェクトはシステム管理者権限が必要一部のオブジェクトはシステム管理者権限が必要 ユーザー、グループ、カスタムフィールドの一覧など 38
  40. 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. 41. 情報源情報源 Redmine API   ドキュメント化されていない機能が一部あるjq h p://www.redmine.org/projects/redmine/wiki/Rest_api h ps://stedolan.github.io/jq/manual/ 40
  42. 42. まとめまとめ 41
  43. 43. curl と jq を使えば、プログラミング無しでAPIを活用できる。案外簡単! Web UIでできないこともAPIを使えば実現できる場合あり ちょっとした自動化にも使えそう APIでRedmineをちょっと便利に! 42
  44. 44. ありがとうございましたありがとうございました 前田剛 ( )  ファーエンドテクノロジー株式会社  代表取締役   というサイトを運営してます 「 」という本を書きました Redmineのコミッターとして開発を手伝っています @g_maeda Redmine.JP 入門Redmine 43

×