JIRA Advent Calendarの12/15担当 @shoito です。
今回は、フライング気味にJIRA 5.0(12/15時点ではRC2)のREST APIとREST API Browser(RAB)について紹介します。
12/14担当の@showyouさんとREST APIネタで被っている気がしますが気にしませんｗ
12/14担当の@showyouさんとREST APIネタで被っている気がしますが気にしませんｗ
みなさんはJIRAプラグインやJIRA連携ツールはご存知でしょうか？
初耳という方はどんなものがあるのかAtlassian Plugin Exchangeをご覧ください。
JIRAプラグイン
JIRA以外にも、Confluence, FishEye, Bamboo, Crowd, CrucibleなどAtlassian製品のプラグインが1000以上あり、JIRAだけでも12/15時点で、395のプラグイン(または連携ツール)が公開されています。
Atlassian製品のGreenHopperやBonfireもJIRAプラグイン(+ブラウザ拡張)ですので、Atlassian Plugin Exchangeで見つけることができます。
JIRA連携ツール
JIRAはAPIを公開してくれているので、他のツールと連携させることが可能です。
SOAP、XML-RPC、REST APIと受け口は設けられていて、連携元の構成に合わせて選択できますが、今回はREST APIに焦点を絞って話を進めます。
ちなみに、連携ツールとしてはEclipseやVisualStudioなどのIDEと連携するAtlassian Connectorが私は思い浮かびます。
REST APIを試す準備
JIRA 5.0のREST APIを試すためには、まずAtlassian SDKをインストールします。
Mac OS X環境でHomebrewを使っていれば、下記のコマンドでインストールできます。
$ brew install atlassian-plugin-sdk
他の環境の方はAtlassian Developersからダウンロードし、PATH変数の設定などを行います。
この辺はInstalling the Atlassian Plugin SDKが参考になります。
次に、JIRAプラグイン/連携ツール開発用のJIRAを立ち上げるために、プロジェクトを作ります。
JIRA 5にするのかい？4にするのかい？と聞かれるので、JIRA 5を使うように1を選択しましょう。
$atlas-create-jira-plugin
A new plugin structure is required for JIRA 5 plugins due to significant changes in the APIs.Create a plugin for?1) Shiny new JIRA 52) Regular 'ol JIRA 4 (or earlier)
mavenプロジェクトのgroupIdやartifactIdなどの入力を求められるので、適当に入力します。
Define value for groupId: : com.github.astahDefine value for artifactId: : jira-connectorDefine value for version: 1.0-SNAPSHOT: :Define value for package: com.github.astah: : com.github.astah.connector.jiraConfirm properties configuration:groupId: com.github.astahartifactId: jira-connectorversion: 1.0-SNAPSHOTpackage: com.github.astah.connector.jira
このままの状態で、atlas-run コマンドを実行してJIRAを起動すると5.0-beta1で起動してしまうので、pom.xmlのjira.versionを最新バージョンに変更します。
REST APIは5.0 finalに向けてどんどん追加されていっていたので、beta1のままだと扱えないAPIがあるためです。
[before]
＜jira.version＞5.0-beta1＜/jira.version＞
[after]
＜jira.version＞5.0-rc2＜/jira.version＞
pom.xmlを編集し終えたら、atlas-run コマンドを実行します。
$ atlas-run
JIRAの実行に必要なライブラリが大量にmavenリポジトリからダウンロードされ、私の家の貧弱な回線では30分程度時間がかかったので、この間にランチやディナーにでも行ってください。
さぁ、これでJIRAのREST APIを試す環境はできましたが、このままではプロジェクトも課題もadmin以外のユーザーも存在しないので、適当なプロジェクトを作って、課題を幾つか登録しておくことをお勧めします。
(準備でここまで...)
REST API
REST APIを使うことでプロジェクト、ユーザー、課題の検索や操作などが行えます。
では、JIRA REST API Tutorials を見ながら幾つか試してみましょう。
下記の例では、初期状態で登録されているadminユーザー、パスワードadminでREST APIを読んでいます。
- 課題JAC-1の詳細をJSON形式で取得
$ curl -u admin:admin http://localhost:2990/jira/rest/api/2/issue/JAC-1
- JIRAにあるプロジェクトの一覧をJSON形式で取得
$ curl -u admin:admin http://localhost:2990/jira/rest/api/2/project/
- adminユーザーにアサインされている課題の一覧をJSON形式で取得
$ curl -u admin:admin http://localhost:2990/jira/rest/api/2/search?jql=assignee=admin
というように、これは一例ですがこれまでもREST APIを試すことが出来ました。
しかし、curlコマンドやREST ConsoleよりもJIRAに特化して試しやすいツールがAtlassian SDK 3.6.2から登場しました。それがREST API Browserです。
REST API Browser(RAB)
Atlassian SDKに含まれるJIRAプラグイン。各種REST APIをブラウザ上から試すことができます。
何が便利かというと、まず各APIのパラメーターをイチイチ調べなくて良くなりました。
各APIを試すためのフォームが設けられていて、そこにパラメーターの入力フィールドもあるため、このAPIのパラメーターはprojectIdと何を指定するんだっけ？issueId？fieldsだっけ？ということがなくなりました。
レスポンスのJSONも当たり前のように整形されていてステキです。
まず上部から試したいAPIを選択します。
ここでは、11番目くらいにあるAtlassian JIRA - Plugins - REST Plugin (/rest/api/2)を試しましょう。
次に、adminユーザーにアサインされている課題の一覧を取得してみます。
/search を選択し、jql フォームに assignee=admin と入力し、Executeボタンを押下します。
するとスクリーンショットにあるように、リクエスト、レスポンスヘッダ、レスポンスボディが確認できます。
ちなみに、選択できるカテゴリを数えてみたら34ありました。スゴいなー。
Applinks Product Plugin
Atlassian Developer Toolbox
Atlassian Embedded Crowd - Administration Plugin
Atlassian JIRA - Plugins - Admin Quick Navigation
Atlassian JIRA - Plugins - Common AppLinks Based Issue Link Plugin
Atlassian JIRA - Plugins - Confluence Link
Atlassian JIRA - Plugins - Gadgets Plugin
….
まとめ
準備のため長い前置きとREST APIとREST API Browserについて紹介しました。
REST API Browserの登場のおかげで、連携ツールの開発が進めやすくなったと思います。
是非、来年(？)正式リリース予定のJIRA 5.0のREST APIで遊んでみてください。
注意
atlas-runで起動したJIRAでは、JIRA_HOMEがtarget/jira/home ディレクトリに設定されているため、atlas-cleanコマンド(mvn clean)を実行するとキレイさっぱりと消えてしまいます。
そもそも開発用ですので、適宜データをExportしておくか、消えるのを覚悟しておいてください。
次の担当は @literaliceさんです。お楽しみに！
JIRA Advent Calendar (#jiraadvent) ではあと10人(9人？)の書き手が不足しているようなので、JIRAを既に使いこなしている方もまだまだこれからという方も立候補してみてはいかがでしょう。
最後に
REST API周りでは @kompiroさんとの会話で気づいたことや存在を教えてもらったことが含まれています。@kompiroさん、ありがとうございます。
最後に
REST API周りでは @kompiroさんとの会話で気づいたことや存在を教えてもらったことが含まれています。@kompiroさん、ありがとうございます。
0 件のコメント:
コメントを投稿