Author
南澤 華代Hanayo Minamisawa
こんにちは。リックソフト ヘルプデスク担当の南澤です。
今回も リックソフトブログで一番人気？！の りっくまのお便り投稿シリーズ をお送りします。
このシリーズは、技術知識があまりなく、Jira初心者の新米プロジェクトリーダーのりっくまくんが、弊社ヘルプデスクへ悩みを相談しながら成長していく物語です。
今回は、りっくまからヘルプデスクにこんなお便りが届きました。
こんにちは！ 僕はりっくまです。
社内システム開発担当者から、他のシステムからJira課題の検索や作成をしたいけど、JiraはREST APIが使えるのかヘルプデスクへ確認して～と頼まれたクマ。
僕、REST APIって初耳でなんのことかよくわからないクマ！
僕にわかるように説明してほしいクマ！
今回のりっくまさんの質問は、高度な内容ですね。
まず答えから言いますと、JiraにはREST APIが用意されていますので、REST APIを使用してJiraの課題の検索や作成は可能です。
社内システム開発者の方へは、以下のJiraのREST APIリファレンスや利用例を渡してもらえれば開発できると思います。
さてこれから、りっくまさんのようにREST APIって何？という方に向けて、REST APIを使ってJiraを操作する利用例を紹介します。
REST APIとは？
REST API を利用すると、HTTP メソッドの POST / PUT / GET / DELETE を使って、データの「追加、更新、検索、削除」操作ができます。
Jiraの場合も、REST APIを利用すると、追加（例：課題の作成）、更新（例：課題の編集）、検索（例：希望の課題を検索して取得する）、削除（例：課題の削除）といった操作ができるのです。
このように説明してもピンとこないかもしれません。
りっくまさんのように初めてREST APIを知った方は、Jiraアプリケーション以外から Jiraの操作ができる呪文（魔法のURL）とでも思ってください。
つづけて実際にJiraでREST APIを使用した利用例を紹介します。
REST APIでJira課題を検索
例として りっくま(rickuma)が担当者になっている課題を取得してみましょう。
Jiraの検索画面でこの条件で検索すると、以下のように4件ヒットするような結果になります。
つづけて、上記をREST APIで取得する方法を考えてみましょう。
REST APIでJira課題を検索して結果を取得する場合は、JIRA Server platform REST API referenceを見ると、 /rest/api/2/searchのGETメソッドでできそうなことがわかります。
JIRA Server platform REST API referenceには指定できるパラメータも記載されています。 今回の例では、以下のパラメータを使ってみます。
| パラメータ | 型 | 設定する値 | 説明 |
|---|---|---|---|
| jql | string | assignee in (rickuma) （rickumaが担当している課題） | JQL文字列 （Jiraの検索で利用できる検索言語。例えば、「status = closed」でステータスがクローズの課題を検索できる。） |
| maxResults | int | 40件 | 結果を返す課題の上限数。50件がデフォルト。 |
| fields | string | 要約、担当者、期限 | 課題から取得したいフィールドをカンマ区切りで指定できる |
以上を踏まえると、課題を取得できるURLは以下になります。
（JiraのベースURLは、http://192.168.56.103:8080/jira です）
ためしにこのURLをブラウザで参照してみましょう。
Firefoxの場合だと、以下のようにJSONフォーマットで見やすい状態で参照できます。
課題の取得件数は4件（青いバーのtotalの数値）で、Jira検索画面の結果件数と一致しています。
それから、取得したいフィールドも課題ごとに取得できていることもわかります。
また、これを Linux の curl コマンドで実行する場合は下記の通りとなります。admin:password は Jira にログイン可能で課題の閲覧権限を持つ ユーザー名(admin)とパスワード(password)です。
[html] # curl \ -D- \ -u admin:password \ -X GET \ -H "Content-Type: application/json" \ http://192.168.56.103:8080/jira/rest/api/2/search?maxResults=40&fields=issuekey,summary,assignee,duedate&jql=assignee=rickuma [/html]REST APIでJira課題を作成
今度は、REST APIを使ってJira課題を作ってみましょう。
ためしに以下の情報で課題を作ってみます。
| 項目名 | 値 |
|---|---|
| プロジェクト | RSKUMA (りっくまプロジェクト) |
| 要約 | りっくまブログ 2018/5 作成 |
| 課題タイプ | タスク |
| 担当者 | rickuma (りっくま) |
| 報告者 | meganekuma (めがねっくま) |
| 優先度 | Medium |
| 説明 | 2018年リックソフトブログに掲載する内容を作成してください。 |
上記情報をJSONファイルにすると以下のようになります。
createissue.json の内容
[html] { "fields":{ "project":{ "key":"RSKUMA" }, "summary": "りっくまブログ 2018/5 作成", "issuetype": { "name": "Task" }, "assignee": { "name": "rickuma" }, "reporter": { "name": "meganekuma" }, "priority": { "id": "3" }, "description": "2018年リックソフトブログに掲載する内容を作成してください。" } } [/html]このJSONファイルを作業ディレクトリに保管し、そこで以下のCurlコマンドを実行して、Jiraへ情報をPOSTします。
[html] # curl \ -D- \ -u admin:password \ -X POST \ --data @createissue.json \ -H "Content-Type: application/json" \ http://192.168.56.103:8080/jira/rest/api/2/issue/ [/html]Curlコマンド実行後の結果は次のようになります。SENなど一部情報はマスクしています。
最後の一行は、実行結果で、課題ID「10400」課題キー「RSKUMA-6」で課題作成できているという意味です。
curlコマンド実行後の結果（一部情報をマスク）
[html] HTTP/1.1 201 X-AREQUESTID: 1425x871x1 X-XSS-Protection: 1; mode=block X-Content-Type-Options: nosniff X-Frame-Options: SAMEORIGIN Content-Security-Policy: frame-ancestors 'self' X-ASEN: SEN-XXXXXXXXXXXX Set-Cookie: XXXXXXXXXXXXXXXXXXXXXXXXXXXXX;path=/jira;HttpOnly X-Seraph-LoginReason: OK Set-Cookie: atlassian.xsrf.token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX;path=/jira X-ASESSIONID: XXXXXXX X-AUSERNAME: admin Cache-Control: no-cache, no-store, no-transform Content-Type: application/json;charset=UTF-8 Transfer-Encoding: chunked Date: Sun, 27 May 2018 14:45:16 GMT {"id":"10400","key":"RSKUMA-6","self":"http://192.168.56.103:8080/jira/rest/api/2/issue/10400"} [/html]実際に課題キー「RSKUMA-6」の課題(http://192.168.56.103:8080/jira/browse/RSKUMA-6)へアクセスすると、指定した内容で課題が作成できていることが分かります。
最後に
今回は難しい質問でしたが、りっくまさん、このような回答でいかがでしょうか？
REST APIで課題の編集や、ステータス変更、それからユーザー追加などの管理機能も操作できますよ。
この話は、また後日ブログに書きますね～
ご不明な点がございましたら、お気軽に弊社にお問合せください。
また３０日の無料評価ライセンスがありますので、ぜひお試しください。