【クラウド版でも！】JiraのREST API を使ってみよう

2023年10月30日
【クラウド版でも！】JiraのREST API を使ってみよう

Author

鷲田拡平 Washida.Kohei

鷲田拡平</mt:Var>

--本ブログはクラウド版のJiraをお使いの方向けの記事です--

こんにちは、リックソフトの鷲田です。

皆さんはJiraを上手にご利用できていらっしゃいますでしょうか。
Jiraは非常に多機能なタスク管理ツールですが、ご利用する企業様それぞれのご都合で
「そうは言っても他のシステムとも連携が必要で...」とか、「Jiraにある情報からなんかゴリっと取ってきて、あれやこれやしたい」とかの様々なご要望をいただきます。

Jiraの利用者には技術者の方も多いため、そういったご要望につきましては

「REST APIが用意されていますので、是非ご利用ください！」

とご回答させていただくことが多いです。

...が。

そうはいっても、REST APIになかなか馴染みがない方も多いのではないかと思います。
今回はそういった方向け、また技術者の方でもJira APIを初めて使われる方向けに、REST APIの利用の事始めについて書いていこうと思います。

※本記事はJira Cloudを対象としています。

１．アトラシアンのREST API ドキュメント

まずは公式のドキュメントを見てみましょう。

https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/#about

ここにはできることが全て書かれています！

...と言われても、一度に見せられてもどれをどうすればいいのかよくわかりませんね。

ということで、今回は課題の参照、検索、登録をしてみたいと思います。

2．JiraでREST APIを活用するための下準備

まずは、APIトークンを作成します。APIトークンというのは、REST APIでアクセスをする際に、アクセスしたユーザを特定するための文字通り「鍵」となります。
ここで取得したトークンは、作成したユーザの参照範囲でしか参照できない、ということになります。

まずはJiraにログインした状態でこちらのURLにアクセスして

https://id.atlassian.com/manage-profile/security/api-tokens

APIトークンを作成する、を選択します。

Label　とありますが、名前は任意です。あまり処理には関係ないので、ご自由にご記入ください。

記入後、「作成」を選択しましょう。

すると、APIトークンの表示画面が出ます。マスクされていますが、「コピーする」を選んでいただくと、クリップボードにトークンがコピーされますので、これをどこかにペーストして控えておきましょう。

トークンができると、ラベルの通りのトークンが発行されていることを確認できます。

※余談かもしれませんが...このトークンの管理は充分にお気を付けください。
　流出してしまうと、「このユーザでできるJiraの操作はだいたいできる」ということになりますので、情報流出や不正アクセスの原因にもなり得ます。

３．Jira課題の参照（メソッド：GET)

ここまできたらいよいよAPIの実行です。

APIの実行方法には様々な方法がありますが、実行テストツールの代表として、Postmanというものがあります。
Linuxでcurlコマンド等でもできるのですが、パラメータの設定や結果が見やすくなっており、これで問題なく実行できるかを確認してから、ご自身の作成するツール等で実行いただくのがおすすめです。

以下はPostmanの実行画面で解説します。Postmanのインストールが完了している前提で記載しますのでご了承ください。

まずはAPIを作ります。Newを選択。

今回実行するAPIは、HTTP Requestです。

PIの設定をする画面が出てきました。ここに値を設定します。

今回実行するのはこちらのAPIですので、メソッドはGETを選択します。
URLですが、「https://（ご利用Jira環境ドメイン）.atlassian.net/rest/api/3/issue/（課題キー）」という形式で指定してください。

これが単体の課題検索のAPI実行URLとなります。

例の場合、「WSD-2」という課題キーの情報を取得するURLになります。

もう一つ、認証情報を設定します。

Authorizationタブを選択し、Typeに「Basic Auth」を指定。

usernameにはJiraへログインするユーザIDを、

Passwordに先ほど取得したAPIトークンを張り付けてください。

こちらは以後のAPI実行でも同じものを指定することになります。

ここまでできたら、右上の青い「Send」を押すと...

課題の情報が取得できました！　JSON形式でテータの取得ができていれば成功です。IDやkey、カスタムフィールドの情報が取得できていることが確認できるかと思います。

問題なく実行ができたら、Saveを押して設定を保存しておくと、あとで流用等しやすいかと思います。

４．Jira課題の検索（メソッド：GET）

次は課題の検索をしてみましょう。実行するAPIはこちら。

Authorizationは参照と同じものを設定します。

Paramsタブに下図の通りの設定をします。

URLには「https://（ご利用Jira環境ドメイン）.atlassian.net/rest/api/3/search」を指定してください。

メソッドには再びGETを指定。

Paramsタブを指定し、keyに「jql」、valueに任意のJQLを指定します。

例ではproject=WSDとしておりますので、プロジェクトキーが「WSD」となっているものを検索するものとなっています。

これで、実行してみますと...

検索が実行出来た結果が返ってきました！　検索結果は7件ある、とのこと。この下には、検索結果の詳細な情報が色々と取得できています。

検索は非常に便利なAPIなので、利用シーンが多いのではないでしょうか。

５．Jira課題の登録（メソッド：POST）

最後は課題の登録です。

課題の登録は、前２つと比べて少し大変です。というのも、様々な属性値をPOSTする情報に含む必要があるからですね。

以下はあくまで例としてですが...例えばプロジェクトキーや課題タイプのキー、カスタムフィールドのキーなど、環境ごとに設定すべき値が異なるため、参考の一つとしてご覧ください。

実行するAPIはこちらです。

Authorizationは参照と同じように設定していただいた上で...

メソッドにはPOSTを指定します。

URLには「https://（ご利用Jira環境ドメイン）.atlassian.net/rest/api/3/issue」を指定します。

その上で、Bodyタグを選択し、「raw」に以下のような形式のJSONを指定します。

<pre class="" brush:"="" html;"=""> { "fields":{ "summary":"api課題作成テスト", "description":{ "version":1, "type":"doc", "content":[ { "type":"paragraph", "content":[ { "type":"text", "text":"課題の説明です。" } ] } ] }, "assignee":null, "issuetype":{ "id":"10001" }, "project":{ "id":"10000", "key":"WSD" } } }

ここで指定するissuetypeやprojectの値は、登録する環境情報に依存します。不明な場合は検索APIを実行したり、管理者に問い合わせるなどの方法で調べる必要がありますのでご注意ください。

設定ができたらSendを押すと...