データ パイプライン
要件
REST API を使用してデータのエクスポートをトリガーするには、次が必要です。
- 有効な Jira Data Center ライセンス
- Jira システム管理者の権限。サポートされている API 認証方法の詳細については、「セキュリティの概要」を参照してください。
Considerations
開始する前に、多数のセキュリティとパフォーマンスへの影響を考慮する必要があります。
セキュリティ
セキュリティと機密性に基づいてデータを除外する必要がある場合は、データをエクスポートした後に行う必要があります。
エクスポートされたファイルは共有ホーム ディレクトリに保存されるため、このファイルが適切に保護されていることも確認できます。
エクスポート パフォーマンス
パフォーマンスの問題のリスクを最小限に抑えるため、次を強くお勧めします。
- データのエクスポートは、アクティビティが少ない時間帯またはアクティビティのないノードで実行します。
fromDate
パラメーターを使用してエクスポートするデータの量を制限します。日付が古過ぎるとより多くのデータがエクスポートされるため、データのエクスポート時間が長くなります。
エクスポート スコープ | おおよそのエクスポート時間 | |
---|---|---|
課題 1,000,000 件 | 課題 7,000,000 件 | |
Jira Software | ||
| 15 分 | 2 時間 |
| 1 時間 | 9 時間 |
| 5 時間 | 22 時間 |
Jira Software と Jira Service Management | ||
| 30 分から 2 時間 | 3 ~ 6 時間 |
テスト パフォーマンス対本番環境の比較
ここで紹介するパフォーマンス データは、当社独自の内部回帰テストに基づいています。データ エクスポートに要する実際の時間とお客様の環境にもたらす影響は、次の条件に基いて異なる場合があります。
- インフラストラクチャ、構成、負荷
- インストールしているアプリケーション (Jira Software と Jira Service Management)
- エクスポートするカスタム フィールドと課題の履歴データの量
Jira パフォーマンス テストを使用して、AWS 上の Jira Data Center 環境でデータ エクスポートのパフォーマンスをテストしました。この環境には 1 つの c5.9xlarge Jira ノードと 1 つの PostgreSQL データベースがありました。ユーザーの負荷をテストするために、2 つの仮想ユーザー ノード全体で 24 人の仮想ユーザーを使用しました。
エクスポートを実行するノードのパフォーマンス低下をしきい値 5% 未満に保つため、データのエクスポート速度を意図的に大幅に下げています。エクスポートを実行するノードからトラフィックをリダイレクトするため、ロード バランサを使用することをお勧めします。
エクスポートを実行する
アプリケーションが、/jira などのコンテキスト パスを使用するように設定されている場合は、これを必ず以下の例の <base-url>
に含めます。
現在の状態データをエクスポートするには、<base-url>/rest/datapipeline/latest/export
に POST
リクエストを実行します。
エクスポートされるデータを fromDate
値の後に作成または更新されたエンティティだけに制限するには、fromDate
パラメーターを使用します。
このパラメーターは、ISO 8601 形式 (yyyy-MM-ddTHH:mmTZD) で設定された日付値のみを受け付けます。以下に例を示します。
- 2020-12-30T23:01Z
- 2020-12-30 T 22:01+01:00
(たとえば、リクエストで URL エンコーディングを使用する必要があります2020-12-30T22%3A03%2B01%3A00
)
fromDate パラメーターなしでエクスポートをトリガーすると、直近の 365 日内のすべてのデータがエクスポートされます。
認証に cURL と個人アクセス トークンを使用するリクエストの例を次に示します。
curl -H "Authorization:Bearer ABCD1234" -H "X-Atlassian-Token: no-check"
-X POST https://myexamplesite.com/rest/datapipeline/latest/
export?fromDate=2020-10-22T01:30:11Z
"X-Atlassian-Token: no-check"
ヘッダーは Confluence にのみ必要です。Jira の場合は省略できます。
POST
リクエストには次の応答があります。
エクスポートのステータスを確認する
アプリケーションの管理コンソールからエクスポートのステータスを確認して、最後にエクスポートを実行した日時を確認できます。データ エクスポート ステータスを表示するには、次の手順に従います。
- In the upper-right corner of the screen, select Administration > System.
- [データ パイプライン] を選択します。
- 開始前 - エクスポートは現在実行されていません
- 開始 - エクスポートは現在実行中です
- 完了 - エクスポートが完了しました
- リクエストをキャンセル - キャンセル リクエストが送信されました
- キャンセル - エクスポートがキャンセルされました
- 失敗 - エクスポートに失敗しました。
失敗したエクスポートまたはキャンセルされたエクスポートの解決については、「データ パイプラインのトラブルシューティング」をご参照ください。
<base-url>/rest/datapipeline/latest/export
に GET
リクエストを実行します。GET
リクエストは 200
コードを返しますが、エクスポートがどのステージにあるかによって応答が異なります。
GET
リクエストには次の応答があります。
エクスポートをキャンセルする
<base-url>/rest/datapipeline/latest/export
に DELETE
リクエストを実行します。DELETE
リクエストには次の応答があります。
自動データ エクスポート キャンセル
CANCELLED
と自動でマークされます。ただし、クラッシュまたはハードウェア レベルの障害が発生して JVM に通知されなかった場合、エクスポート プロセスはロックされることがあります。この場合、DELETE
リクエストを通じてエクスポートを CANCELLED としてマークする必要があります。これによって、プロセスがロックから解放されて別のデータ エクスポートを実行できます。
データ エクスポートを設定する
次のシステム プロパティを使用して、エクスポート データの形式を設定できます。
既定値 | 説明 |
---|---|
plugin.data.pipeline.embedded.line.break.preserve | |
false | 埋め込まれた改行を出力ファイルに保持するかどうかを指定します。Hadoop などのツールでは、改行が問題になる場合があります。 このプロパティはデフォルトで |
plugin.data.pipeline.embedded.line.break.escape.char | |
\\n | 埋め込まれた改行の文字をエスケープします。デフォルトでは、 |
機能フラグを使用して、特定のタイプのデータを除外するようにエクスポートを詳細に設定できます。機能フラグの使用方法については「Jira でダーク機能を管理する方法」をご参照ください。
既定値 | 説明 |
---|---|
data.pipeline.feature.jira.all.exportable.custom.fields.enabled | |
Enabled | カスタム フィールド データをエクスポートに含めるかどうかを指定します。カスタム フィールド データをエクスポートすると、カスタム フィールド データの量によってはエクスポートに掛かる時間が長くなる場合があります。
|
data.pipeline.feature.jira.issue.history.export.enabled | |
Enabled | 課題の履歴データをエクスポートに含めるかどうかを指定します。履歴データをエクスポートすると、エクスポートに掛かる時間が大幅に増加します。
|
出力ファイル
データ エクスポートを実行するたびに、数値ジョブ ID をタスクに割り当てます (最初のデータ エクスポートに対して 1 から開始)。このジョブ ID は、エクスポートされたデータを含むファイルのファイル名と場所で使用されます。
エクスポートされたファイルの場所
エクスポートされたデータは個別の CSV ファイルとして保存されます。ファイルは次のディレクトリに保存されます。
<shared-home>/data-pipeline/export/<job-id>
(クラスターで Jira を実行する場合)<local-home>/data-pipeline/export/<job-id>
クラスタ化されていない Jira を使用している
<job-id>
ディレクトリ内には次のファイルが表示されます。
issues_job<job_id>_<timestamp>.csv
(for issues)
(Jira Software フィールドと Jira Service Management フィールドの場合)issue_fields_job<job_id>_<timestamp>.csv
issue_history_job<job_id>_<timestamp>.csv
(課題アクティビティの履歴の場合)sla_cycles_job<job_id>_<timestamp>.csv
(Jira Service Management がインストールされている場合の SLA サイクル情報の場合)
このエクスポートでデータを読み込んで変換するには、そのスキーマを理解する必要があります。「データ パイプライン エクスポート スキーマ」をご参照ください。
カスタム エクスポート パスを設定する
ルート エクスポート パスを変更するには、<base-url>/rest/datapipeline/1.0/config/export-path
に PUT
リクエストを実行します。
リクエストの本文で、次のように優先するディレクトリに絶対パスを渡します。
{
"path": "/tmp/new/path"
}
PUT
リクエストには次の応答があります。
エクスポート パスを確認するには、<base-url>/rest/datapipeline/1.0/config/export-path
に GET
リクエストを実行します。
GET
リクエストには次の応答があります。
デフォルトのエクスポート パスに戻す
デフォルト パスに戻すには、<base-url>/rest/datapipeline/1.0/config/export-path
に DELETE
リクエストを実行します。
Spark と Hadoop のインポート設定の例
既存の Spark インスタンスまたは Hadoop インスタンスがある場合、次の参照を使用し、さらに変換するためにデータをインポートする方法を設定します。