# Jira Import Integration

Treasure Dataでは、Jiraからデータをインポートすることができます。

# 前提条件

- Treasure Dataの基本的な知識


# Jiraからの廃止予定のお知らせ

Atlassian CorporationはJiraの変更を発表しました。2018年12月以降、[パスワードとCookieベースの認証を使用してAPIにアクセスする基本認証方式は廃止されました](https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-basic-auth-and-cookie-based-auth/)。できるだけ早く既存の認証を更新してください。**認証を作成する際は、メールアドレスとAPIキーの方式を使用してください。**

# JiraウェブアプリケーションからJira APIキーを取得する方法

Jiraウェブアプリケーションサーバーにログインします。次の例ではJira cloud ([https://id.atlassian.com](https://id.atlassian.com/))を使用しています。

[https://id.atlassian.com/manage-profile/email](https://id.atlassian.com/manage-profile/email) にアクセスして、メールアドレスを確認してください。基本認証を使用しているユーザーは、**ユーザー名の値をメールアドレスに置き換える必要があります**。

![](/assets/image-20190923-174923.f5fd72ea954b8d15bbb32e810dfa86632a9e64e0a0b5e1026ecaec8c13aa50c9.7eaf6023.png)

**Security**を選択してから**Create or manage API tokens**を選択します(または直接リンク([https://id.atlassian.com/manage/api-tokens](https://id.atlassian.com/manage/api-tokens))にアクセスすることもできます)。

![](/assets/image-20190923-175000.3b01217ca7bb43a288f5ba40fb6683f4ba10bb399ad3aa1ff6bf30ce421f2838.7eaf6023.png)

次に、**Create API token**を選択します。

![](/assets/image-20190923-175059.609550313e8eed1419fddb1fd92c370ee8dfcbf086a4042bb26366f1c9743e24.7eaf6023.png)

表示されるペインで、APIトークンの名前を入力して**Create**を選択します。

![](/assets/image-20190923-175128.7cd7943b287141b8820f10b40b2e3230ea3c5177148becb651a3c97aa0d5b031.7eaf6023.png)

次のペインで、**View**を選択して新しいAPIキーを確認します。

![](/assets/image-20190923-175150.8553c49d68938935313d8a23c78d7440964b8f9994068736f6b0f6915f3718c5.7eaf6023.png)

これでAPIキーが表示されます。これをコピーして、TD ConsoleとJiraサーバーの認証に使用します。

![](/assets/image-20190923-175212.eb533c011235c3cb53072e02166ab6b0f1cca0e234cae7539370fc6d2845dee7.7eaf6023.png)

# TD Consoleを使用してJiraデータをTreasure Dataに転送する方法

**Integration Hub -> Catalog**に移動して、**JIRA**タイルを選択します。

![](/assets/image-20190923-175249.036594bd3f360c1b2134dcb0d6e267aa5e93c9dda5ee3ecacd0a2f40813505ed.7eaf6023.png)

**Email**、**API Key**、**JIRA API endpoint**を入力します。

![](/assets/image-20190923-175328.5afef6e2cba87dcc04c0179890476743afc21ca261c557785937e207fd833590.7eaf6023.png)

**Continue**を選択して、新しい接続の名前を入力します。

![](/assets/image-20190923-175409.a6d53732c4959e11d2dfe6db7ce72667b39fc48fd5978abd90cb98d5da73fc91.7eaf6023.png)

**Done**を選択します。

**Integrations Hub > Authentications**に戻り、作成した認証を選択して**New Source**を選択します。

![](/assets/image-20190923-175444.417352d7ba29572eacadab91ef6ac3764ac379eca0a6d1360dc473f24bcfd55f.7eaf6023.png)

**New Source**ポップアップで有効なJQLを入力して**Next**を選択します。

![](/assets/image-20190923-175519.6cb6f3bba87c77adfcf0d2b1d394e6115cfa207e08d19223203b62f0674f4992.7eaf6023.png)

プレビューが表示されたら、プラグインが取り込もうとするカラムを削除、追加、または変更したい場合は**Advanced Settings**を選択できます。**Next**を選択します。

![](/assets/image-20190923-175548.ae8fc13e1de315fb34a16134e13192a02b60e781fa03fa195ed4fe7144dca384.7eaf6023.png)

**Transfer to**タブで、データを挿入するデータベース名とテーブル名を入力します。

![](/assets/image-20190923-175622.b64aaa7e08f5bf3dfa01a244c3d7b2226a08689c61767c611d4c882f23f75696.7eaf6023.png)

新しいデータベースを作成する場合は、**Create new database**を選択してデータベース名を入力します。**Create new table**についても同じ手順を実行します。

既存のテーブルにレコードを**append**するか、既存のテーブルを**replace**するかを選択します。

デフォルトキーではなく異なる**partition key seed**を設定する場合は、ポップアップメニューを使用して指定できます。

![](/assets/image-20190923-175654.f981e307b7042086416363bd43db4912444239ced64586ebcb19984e4b15cda8.7eaf6023.png)

**Schedule**タブでは、1回限りの転送を指定するか、自動的に繰り返される転送をスケジュールすることができます。

![](/assets/image-20190923-175732.7012f0c64834a6f0c798b5df04bf935fefe63e8b591f900ea48f5273d67394fa.7eaf6023.png)

**Next**を選択します。オプションで、ソースの名前を変更できます。**Done**を選択すると、ジョブがスケジュールされます。完了したときに通知されます。

![](/assets/image-20190923-175757.43374ab2c2453418ca1ea6c72d33ba57aa6a5864741c6691e7aacd0c8c5b9314.7eaf6023.png)

# TD Toolbeltを使用してJiraデータをTreasure Dataに転送する方法

## 'td' コマンド v0.11.9以降をインストール

最新の[TD Toolbelt](https://toolbelt.treasuredata.com/)をインストールします。


```
$ td --version
0.11.10
```

## シード設定ファイル(seed.yml)を作成

以下の例に示すように`seed.yml`を準備します。JIRAのAPIキー付きメールアドレス、JIRA URI、そしてデフォルトでは空のjqlクエリを設定します。（認証にはユーザー名とパスワードはサポートされなくなりました）。「replace」モードを使用します:


```
in:
  type: jira
  username: user@example.com
  password: APIkeysXXXXXX
  uri: https://your-domain.atlassian.net
  jql: summary ~ fix and project = 'PLT'  # example query. be sure to use singlequotes
out:
  mode: replace
```

JiraのData Connectorは、指定されたJQLに一致するすべてのチケットをインポートします。

利用可能な`out`モードの詳細については、付録を参照してください。

## フィールドを推測(load.ymlを生成)

`connector:guess`を使用します。このコマンドは、ターゲットデータを自動的に読み取り、データ形式をインテリジェントに推測します。


```
$ td connector:guess seed.yml -o load.yml
```

`load.yml`を開くと、ファイル形式、エンコーディング、カラム名、タイプなど、推測されたファイル形式の定義が表示されます。


```
in:
  type: jira
  username: user@example.com  password: APIkeysXXXXXX
  uri: https://your-domain.atlassian.net
  jql: ''
  columns:
  - name: id
    type: long
  - name: key
    type: string
  - name: issuetype.name
    type: string
  ...
out:
  mode: replace
```

次に、`preview`コマンドを使用して、システムがファイルをどのように解析するかをプレビューできます。


```
$ td connector:preview load.yml
```

システムがカラム名やタイプを予期しない形で検出した場合は、`load.yml`を直接修正して再度プレビューしてください。

現在、Data Connectorは「boolean」、「long」、「double」、「string」、「timestamp」タイプの解析をサポートしています。

## ロードジョブを実行

ロードジョブを送信します。データサイズによっては数時間かかる場合があります。ユーザーは、データを保存するデータベースとテーブルを指定する必要があります。


```
$ td connector:issue load.yml --database td_sample_db --table td_sample_table
```

上記のコマンドは、*database(td_sample_db)*と*table(td_sample_table)*がすでに作成されていることを前提としています。データベースまたはテーブルがTDに存在しない場合、このコマンドは成功しないため、[データベースとテーブルを作成](https://docs.treasuredata.com/articles/project-product-documentation/database-and-table-management)するか、`td connector:issue`コマンドで`--auto-create-table`オプションを使用してデータベースとテーブルを自動作成してください:


```
$ td connector:issue load.yml --database td_sample_db --table td_sample_table --time-column created_at --auto-create-table
```

「--time-column」オプションを使用して、Time Formatカラムを「パーティショニングキー」に割り当てることができます。

## スケジュール実行

定期的なJIRAインポートのために、定期的なData Connectorの実行をスケジュールすることができます。当社は高可用性を確保するためにスケジューラーを慎重に管理しています。この機能を使用することで、ローカルデータセンターに`cron`デーモンを配置する必要がなくなります。

スケジュール済みインポートの場合、Data Connector for JIRAは指定されたJQLに一致するすべてのファイルをインポートします。

## スケジュールを作成する

新しいスケジュールは、`td connector:create`コマンドを使用して作成できます。スケジュールの名前、cron形式のスケジュール、データが格納されるデータベースとテーブル、およびData Connectorの設定ファイルが必要です。


```
$ td connector:create     daily_jira_import     "10 0 * * *"     td_sample_db     td_sample_table     load.yml
```

`cron`パラメータは、3つの特別なオプション（`@hourly`、`@daily`、`@monthly`）も受け付けます。デフォルトでは、スケジュールはUTCタイムゾーンで設定されます。-tまたは--timezoneオプションを使用して、タイムゾーンでスケジュールを設定できます。`--timezone`オプションは、'Asia/Tokyo'や'America/Los_Angeles'などの拡張タイムゾーン形式のみをサポートします。PSTやCSTなどのタイムゾーンの略語はサポートされて*いない*ため、予期しないスケジュールになる可能性があります。

## スケジュールを一覧表示する

現在スケジュールされているエントリのリストは、`td connector:list`で確認できます。


```
$ td connector:list
+-------------------+--------------+----------+-------+--------------+-----------------+------------------------+
| Name              | Cron         | Timezone | Delay | Database     | Table           | Config                 |
+-------------------+--------------+----------+-------+--------------+-----------------+------------------------+
| daily_jira_import | 10 0 * * *   | UTC      | 0     | td_sample_db | td_sample_table | {"type"=>"jira", ... } |
+-------------------+--------------+----------+-------+--------------+-----------------+------------------------+
```

## スケジュールの設定と履歴を表示する

`td connector:show`は、スケジュールエントリの実行設定を表示します。


```
$ td connector:show daily_jira_import
```

`td connector:history`は、スケジュールエントリの実行履歴を表示します。個々の実行結果を調査するには、`td job jobid`を使用します。


```
% td connector:history daily_jira_import
+--------+---------+---------+--------------+-----------------+----------+---------------------------+----------+
| JobID  | Status  | Records | Database     | Table           | Priority | Started                   | Duration |
+--------+---------+---------+--------------+-----------------+----------+---------------------------+----------+
| 578066 | success | 10000   | td_sample_db | td_sample_table | 0        | 2015-04-18 00:10:05 +0000 | 160      |
| 577968 | success | 10000   | td_sample_db | td_sample_table | 0        | 2015-04-17 00:10:07 +0000 | 161      |
| 577914 | success | 10000   | td_sample_db | td_sample_table | 0        | 2015-04-16 00:10:03 +0000 | 152      |
| 577872 | success | 10000   | td_sample_db | td_sample_table | 0        | 2015-04-15 00:10:04 +0000 | 163      |
| 577810 | success | 10000   | td_sample_db | td_sample_table | 0        | 2015-04-14 00:10:04 +0000 | 164      |
| 577766 | success | 10000   | td_sample_db | td_sample_table | 0        | 2015-04-13 00:10:04 +0000 | 155      |
| 577710 | success | 10000   | td_sample_db | td_sample_table | 0        | 2015-04-12 00:10:05 +0000 | 156      |
| 577610 | success | 10000   | td_sample_db | td_sample_table | 0        | 2015-04-11 00:10:04 +0000 | 157      |
+--------+---------+---------+--------------+-----------------+----------+---------------------------+----------+
8 rows in set
```

## スケジュールを削除する

`td connector:delete`は、スケジュールを削除します。


```
$ td connector:delete daily_jira_import
```

# 付録

## outプラグインのモード

seed.ymlの`out`セクションでファイルインポートモードを指定できます。

### append（デフォルト）

これはデフォルトのモードで、レコードはターゲットテーブルに追加されます。


```
in:
  ...
out:
  mode: append
```

### replace（td 0.11.10以降）

このモードは、ターゲットテーブル内のデータを置き換えます。ターゲットテーブルに加えられた手動のスキーマ変更は、このモードでは保持されます。


```
in:
  ...
out:
  mode: replace
```