Jira API を使ったチケットの自動作成、編集、検索

Jira APIを使うと、チケットの検索、作成、編集などをプログラムで自動化できます。この記事では、Jira APIを初めて使用する方のために、導入から具体的なコード例までをわかりやすく解説します。

---

## 目次

1. [Jira APIとは？](#1-jira-apiとは)
2. [Jira APIの導入準備](#2-jira-apiの導入準備)
3. [Jira クライアントの設定](#3-jira-クライアントの設定)
4. [Jiraチケットのフィールド説明](#4-jiraチケットのフィールド説明)
5. [チケットの作成](#5-チケットの作成)
6. [チケットの検索](#6-チケットの検索)
7. [チケットの編集](#7-チケットの編集)
8. [カスタムフィールドについて](#8-カスタムフィールドについて)
9. [今後の展望](#9-今後の展望)
9. [応用例](#10-応用例)

---

## 1. Jira APIとは？

Jira APIを使用すると、Jira上のタスクやプロジェクトをプログラムで操作できます。例えば、次のような操作を自動化できます。

- 新しいチケットの作成
- 既存チケットの検索・取得
- チケットの内容を編集
- カスタムフィールドの取得や設定

これにより、業務の効率化やツールとの連携が可能になります。Rubyでは、`jira-ruby` というGemを使用することで、簡単にAPIを扱えます。

---

## 2. Jira APIの導入準備

### Gemのインストール

1. **Gemfileに以下を追加**  

   ```ruby:ターミナル
   gem 'jira-ruby'
   ```

2. **ターミナルで以下を実行**  

   ```bash:ターミナル
   bundle install
   ```

### Jira APIトークンの取得

Jiraアカウントにログインし、[APIトークン管理ページ](https://id.atlassian.com/manage/api-tokens)からトークンを作成してください。

### 環境変数の設定

トークンやユーザー情報をセキュリティのために環境変数に設定します。以下の例を参考にしてください。

```ruby:.env
JIRA_USERNAME="your-email@example.com"
JIRA_API_TOKEN="your-api-token"
JIRA_URL="https://your-domain.atlassian.net"
```

## 3. Jira クライアントの設定

Jira APIを使うには、最初にクライアントを設定する必要があります。このクライアントを通じて、Jiraとやり取りを行います。

```ruby
require 'jira-ruby'

# Jira クライアント設定
options = {
  username: ENV['JIRA_USERNAME'], # Jiraユーザー名
  password: ENV['JIRA_API_TOKEN'], # APIトークン
  site: ENV['JIRA_URL'], # JiraインスタンスのURL
  context_path: '', # 通常は空で問題ありません
  auth_type: :basic # 認証方式。基本認証を使用
}

client = JIRA::Client.new(options)
```

## 4. Jiraチケットのフィールド説明

Jira APIを通してチケット操作を行う場合、以下のフィールド名を使用します。

| フィールド名      | 必須 | 説明                                                                                      |
|-------------------|------|-------------------------------------------------------------------------------------------|
| `project`         | ✅   | チケットを関連付けるプロジェクト。`key` を指定（例: `"TEST"`）。                          |
| `summary`         | ✅   | チケットのタイトル。                                                                      |
| `description`     | ❌   | チケットの詳細説明。                                                                      |
| `issuetype`       | ✅   | チケットの種類。`name` を指定（例: `"Task"` や `"Bug"`）。                                 |
| `priority`        | ❌   | チケットの優先度。`name` を指定（例: `"High"` や `"Low"`）。                              |
| `assignee`        | ❌   | チケットの担当者。`accountId` を指定。                                                    |
| `labels`          | ❌   | チケットに付けるラベル。リスト形式で指定（例: `["backend", "urgent"]`）。                 |
| `customfield_*`   | ❌   | カスタムフィールド。Jira環境によって異なるため、`GET /rest/api/2/issue/{issueIdOrKey}`で確認可能。 |


## 5. チケットの作成

新しいタスクを作成したい場合のコード例です。以下のフィールドを埋めることで簡単にチケットを作成できます。

```ruby
# チケットを作成する
issue = client.Issue.build
issue.save({
  'fields' => {
    'project' => { 'key' => 'TEST' }, # プロジェクトキーを指定
    'summary' => '新しいタスクのタイトル', # 必須: チケットのタイトル
    'description' => 'このタスクはAPIで作成されました。', # 任意: 詳細説明
    'issuetype' => { 'name' => 'Task' }, # 必須: チケットの種類
    'priority' => { 'name' => 'High' }, # 任意: 優先度
    'labels' => ['api', 'test'] # 任意: ラベル（複数可）
  }
})
puts "チケットを作成しました: #{issue.key}"
```

### 実行結果ログ

```bash:ターミナル
チケットを作成しました: TEST-123
```

## 6. チケットの検索

既存のチケットをキー（例: `TEST-1`）で検索する方法です。
チケットキー以外にも、各フィールドの値での検索やプロジェクトごとのチケット取得なども可能です。

```ruby
# チケットを検索する
issue_key = 'TEST-1'
begin
  issue = client.Issue.find(issue_key)
  puts "チケット情報: #{issue.summary} (#{issue.key})"
rescue JIRA::HTTPError => e
  puts "チケットが見つかりません: #{e.message}"
end
```

### 実行結果ログ

```bash:ターミナル
チケット情報: 新しいタスク (TEST-1)
```

## 7. チケットの編集

既存のチケットの情報を更新するコード例です。

```ruby
# チケットを編集する
issue_key = 'TEST-1'
begin
  issue = client.Issue.find(issue_key)
  issue.save({
    'fields' => {
      'summary' => '更新されたタスクタイトル', # タイトルを変更
      'description' => '内容が更新されました。', # 詳細を変更
      'priority' => { 'name' => 'Low' } # 優先度を変更
    }
  })
  puts "チケットを更新しました: #{issue.key}"
rescue JIRA::HTTPError => e
  puts "チケットの更新に失敗しました: #{e.message}"
end
```

### 実行結果ログ

```bash:ターミナル
チケットを更新しました: TEST-1
```

## 8. カスタムフィールドについて

   Jiraには環境ごとに異なるカスタムフィールド（例: `customfield_XXXXX`）があります。管理者アカウントであればブラウザからも確認できますが、以下のAPIリクエスト使用することでもカスタムフィールドの値を取得できます。

```bash
# 以下はキーで検索している
GET /rest/api/2/issue/{issueIdOrKey}
```

## 9. 今後の展望

Jira APIの活用をさらに進めることで、以下のような機能を実現できます。

- **一括操作**  
  複数のチケットを一括で作成・編集するスクリプトを構築。これにより、大量のチケット管理が効率化されます。

- **高度な検索**  
  JQL（Jira Query Language）を使用して、条件に合致するチケットを柔軟に検索。特定のフィルターに基づいて必要な情報を迅速に取得できます。

- **定期的なチケット作成**  
  特定のプロジェクトやタスクの進捗状況を自動的に収集し、関連するチケットをスケジュールに基づいて生成します。

---

## 10. 応用例

これらの機能を応用すれば、以下のような実用的なシステムを構築することが可能です。

- **自動エラー管理**  
  本番環境で発生したエラーを自動的にキャッチし、関連情報を元にJiraチケットを生成。これにより、問題を素早く把握してチームで共有し、解決までのプロセスを一元管理できます。

---

今後の記事では、これらを実現するための具体的なコード例や手法を紹介してまいります。