データ パイプライン

この機能は、Confluence Data Center ライセンスを持っている場合にのみ利用できます。

データ パイプラインを使用すると、Jira、Confluence、または Bitbucket からデータをエクスポートして、既存のデータ プラットフォーム (Tableau PowerBI など) に簡単にフィードできます。これによって、次を行えます。
  • 内容がより豊富なレポートを生成して、サイト アクティビティを視覚化する
  • チームがどのようにアプリケーションを使用しているかをより詳しく理解する
  • 組織における Jira または Confluence の使用の最適化に関してより適切な決定を下す

アプリケーションの管理コンソールまたは REST API を使用で、データ エクスポートをトリガーできます。データは CSV 形式でエクスポートされます。一度に実行できるデータ エクスポートは 1 つだけです。

エクスポートされたデータのスキーマの詳細については、「データ パイプライン エクスポート スキーマ」を参照してください。

データ パイプラインは、次の製品の Data Center 版で提供されます。

  • Jira 8.14 以降
  • Confluence 7.12 以降
  • Bitbucket 7.13 以降

On this page:

要件

REST API を使用してデータのエクスポートをトリガーするには、次が必要です。

Considerations

開始する前に、多数のセキュリティとパフォーマンスへの影響を考慮する必要があります。

セキュリティ

エクスポートには、PII (個人情報) と制限されたコンテンツを含むすべてのデータが含まれます。これはできる限り多くのデータを提供するためであり、フィルターや変換を行ってインサイトを生成できます。

セキュリティと機密性に基づいてデータを除外する必要がある場合は、データをエクスポートした後に行う必要があります。

エクスポートされたファイルは共有ホーム ディレクトリに保存されるため、このファイルが適切に保護されていることも確認できます。 

エクスポート パフォーマンス

大規模なインスタンスでは、データのエクスポートに時間がかかることがあります。サイトへのパフォーマンスの影響を 5% というしきい値未満に保つために、意図的に制限された速度でデータをエクスポートします。エクスポートが進行中でない限り、パフォーマンスに影響はないことに注意してください。

エクスポートのスケジュールを設定するときは、次のことをお勧めします。

  • fromDate パラメーターを使用してエクスポートするデータの量を制限します。日付が古すぎるとより多くのデータがエクスポートされるため、データのエクスポートに要する時間が長くなります。
  • エクスポート中にパフォーマンスの低下が見られる場合は、アクティビティが少ない時間帯またはアクティビティのないノードでエクスポートをスケジュールします。

テストの結果、エクスポートのおおよその期間は次のようになりました…

数値おおよそのエクスポート時間
ユーザー100,0008 分
スペース15,00012 分
ページ2500 万12 時間
コメント1500 万1 時間
アナリティクス イベント2000 万2 時間

総エクスポート時間は約 16 時間でした。 

テスト パフォーマンス対本番環境の比較

ここで紹介するデータは、当社独自の内部回帰テストに基づいています。お客様の環境におけるデータ エクスポートの実際の時間と影響は、インフラストラクチャ、構成、負荷によって異なります。 

テストは、AWS の単一ノード Data Center インスタンスで実施されました。

  • EC2 インスタンス タイプ: c5.4xlarge
  • RDS インスタンス タイプ: db.m5.4xlarge

データ パイプラインにアクセスする

データ パイプラインにアクセスするには、[管理] > [一般設定] > [データ パイプライン] に移動します。

定期エクスポートをスケジュール

データ パイプラインの価値を最大限に引き出す方法は、定期エクスポートをスケジュールすることです。データ パイプラインではフル エクスポートが毎回実行されるため、大規模なサイトがある場合は週に 1 回だけエクスポートすることをお勧めします。

エクスポート スケジュールを設定するには、次の手順に従います。

  1. データ パイプラインの画面で [スケジュールの設定] を選択します。
  2. [定期エクスポートをスケジュール] チェックボックスをオンにします。
  3. データを含める日付を選択します。この日付より前のデータは含まれません。通常、12 か月以下に設定されます。
  4. エクスポートを繰り返す頻度を選択します。
  5. エクスポートを開始する時刻を選択します。勤務時間外にエクスポートが実行されるようにスケジュールすることをお勧めします。
  6. 使用するスキーマ バージョンを選択します (使用可能なスキーマが複数ある場合)。
  7. スケジュールを保存します。

タイムゾーンと反復するエクスポート

エクスポートをスケジュールするときは、サーバーのタイムゾーンを使用します (アプリケーションでサーバーの時刻を上書きした場合はシステムのタイムゾーンを使用します)。タイムゾーンを変更しても、エクスポート スケジュールは更新されません。タイムゾーンを変更する必要がある場合は、スケジュールを編集してエクスポート時刻を再入力する必要があります。

エクスポートは必要な頻度で実行するようにスケジュールできます。複数の曜日にエクスポートすることを選択した場合、最初のエクスポートはスケジュールを保存した後の直近の曜日に行われます。上のスクリーンショットの例では、木曜日にスケジュールを設定した場合は最初のエクスポートは土曜日に、2 回目のエクスポートは月曜日に行われます。週の始まりを待ちません。

エクスポート スキーマ

エクスポート スキーマでは、エクスポートの構造を定義します。エクスポートが以前のエクスポートと同じ構造になることがわかるように、スキーマのバージョンを管理します。これによって、このデータに基づいてダッシュボードまたはレポートを作成した場合の問題を回避できます。

フィールドの削除などの重大な変更やデータの構造化方法の変更が発生した場合にのみ、新しいスキーマ バージョンを導入します。新しいフィールドは、最新のスキーマ バージョンにのみ追加されます。

古いスキーマ バージョンは「非推奨」としてマークされて、将来のバージョンで削除される可能性があります。これらのバージョンを使用して引き続きエクスポートできますが、新しいフィールドではこれらのバージョンは更新されませんのでご注意ください。

エクスポートのステータスを確認する

[データ パイプライン] 画面で、エクスポートのステータスを確認して、前回のエクスポートが実行された日時を表示できます。 

[エクスポートの詳細] テーブルには、最新のエクスポートと現在のステータスが表示されます。

[] > [詳細を表示] の順に選択すると、エクスポートの詳細が JSON 形式で表示されます。詳細には、エクスポート パラメーター、ステータス、すべての返されたエラー (エクスポートが失敗した場合) が含まれます。

失敗したエクスポートまたはキャンセルされたエクスポートの解決については、「データ パイプラインのトラブルシューティング」をご参照ください。 

エクスポートをキャンセルする

進行中のエクスポートをキャンセルするには、次の手順に従います。
  • [データ パイプライン] 画面に移動します。
  • エクスポートの横にある 、エクスポートの [キャンセル] の順に選択します。
  • エクスポートのキャンセルを確定します。

プロセスが終了するまでに数分かかることがあります。すでに書き込まれたファイルは、エクスポート ディレクトリに残ります。これらのファイルが不要なら削除できます。

プロジェクトをエクスポートから除外する

スペースをオプトアウト リストに追加することで、エクスポートから除外できます。特定のスペースについては報告が不要、または機密情報が含まれていてエクスポートしない場合に役立ちます。

スペースをオプトアウト リストに追加するには、POST リクエストを <base-url>/rest/datapipeline/1.0/config/optout に行って、次のようにスペース キーを渡します。

{ 
 "type": "SPACE", 
 "keys": ["HR","TEST"] 
}

これらのスペースは、今後すべてのエクスポートから除外されます。

スペースをオプトアウト リストから削除する方法を含む完全な詳細については「データ パイプライン REST API のリファレンス」をご参照ください。 

自動データ エクスポート キャンセル

データ エクスポートを実行しているノードをシャット ダウンすると、エクスポートはキャンセルされます。ただし、クラッシュまたはハードウェア レベルの障害が発生した後で JVM に通知されなかった場合、エクスポート プロセスはロックされることがあります。この場合は、エクスポートをキャンセル済みとして手動でマークする必要があります (UI を使用するか、REST API で DELETE リクエストを作成します)。これによって、プロセスのロックが解除されて別のデータ エクスポートを実行できるようになります。

データ エクスポートの設定

次のシステム プロパティを使用して、エクスポート データの形式を設定できます。

既定値説明
plugin.data.pipeline.embedded.line.break.preserve
false

埋め込まれた改行を出力ファイルに保持するかどうかを指定します。Hadoop などのツールでは、改行が問題になる場合があります。

このプロパティはデフォルトで False に設定されています。つまり、改行はエスケープされます。

plugin.data.pipeline.embedded.line.break.escape.char
\\n

埋め込まれた改行の文字をエスケープします。デフォルトでは、\n を埋め込まれた改行ごとに出力します。

plugin.data.pipeline.minimum.usable.disk.space.after.export
5 GB

ディスク領域が不足するのを防ぐため、データ パイプラインはエクスポートの前と最中に 5GB 以上の空きディスク領域があるかどうかを確認します。

制限を増減するには、このプロパティを GB 単位で設定します。このチェックを無効にするには、このプロパティを -1 に設定します (非推奨)。

データ パイプライン REST API を使用する

データ パイプライン REST API を使用してデータをエクスポートできます。

データ パイプラインをエクスポートし始めるには、<base-url>/rest/datapipeline/latest/export に対する POST リクエストを実行します。

認証に 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

また、API を使用して、ステータスを確認、エクスポート場所を変更、エクスポートをスケジュール設定またはキャンセルできます。 

詳細については「データ パイプライン REST API のリファレンス」をご参照ください。 

出力ファイル

データ エクスポートを実行するたびに、数値ジョブ ID をタスクに割り当てます (最初のデータ エクスポートに対して 1 から開始)。このジョブ ID は、エクスポートされたデータを含むファイルのファイル名と場所で使用されます。 

エクスポートされたファイルの場所

エクスポートされたデータは個別の CSV ファイルとして保存されます。ファイルは次のディレクトリに保存されます。

  • Confluence をクラスタで実行している場合は <shared-home>/data-pipeline/export/<job-id>
  • <local-home>/data-pipeline/export/<job-id> クラスタ化されていない Confluence を使用している

<job-id> ディレクトリ内には次のファイルが表示されます。

  • users_job<job_id>_<schema_version>_<timestamp>.csv 

  • spaces_job<job_id>_<schema_version>_<timestamp>.csv

  • pages_job<job_id>_<schema_version>_<timestamp>.csv

  • comments_job<job_id>_<schema_version>_<timestamp>.csv

  • analytics_events_job<job_id>_<schema_version>_<timestamp>.csv

これらのファイルでデータをロードして変換するには、そのスキーマを理解する必要があります。「データ パイプライン エクスポート スキーマ」をご参照ください。

カスタム エクスポート パスを設定する

デフォルトでは、データ パイプラインはファイルをホーム ディレクトリにエクスポートしますが、REST API を使用するとカスタム エクスポート パスを設定できます。

ルート エクスポート パスを変更するには、<base-url>/rest/datapipeline/1.0/config/export-pathPUT リクエストを実行します。

リクエストの本文で、優先するディレクトリに対する絶対パスを渡します。 

既定のパスに戻す方法を含む詳細については「データ パイプライン REST API のリファレンス」をご参照ください。 

Spark と Hadoop のインポート設定の例

既存の Spark インスタンスまたは Hadoop インスタンスがある場合は、次の参照を使用してさらに変換するためにデータをインポートする方法を設定します。


Spark / Databricks...

%python
# File location
file_location = "/FileStore/**/export_2020_09_24T03_32_18Z.csv" 

# Automatically set data type for columns
infer_schema = "true"
# Skip first row as it's a header
first_row_is_header = "true"
# Ignore multiline within double quotes
multiline_support = "true"

# The applied options are for CSV files. For other file types, these will be ignored. Note escape & quote options for RFC-4801 compliant files
df = spark.read.format("csv") \
  .option("inferSchema", infer_schema) \
  .option("header", first_row_is_header) \
  .option("multiLine", multiline_support) \
  .option("quote", "\"") \
  .option("escape", "\"") \
  .option("encoding", "UTF-8").load(file_location)

display(df)

Hadoop...

CREATE EXTERNAL TABLE IF NOT EXISTS some_db.datapipeline_export (
  `page_id` string,
  `instance_url` string,
  `space_key` string,
  `page_url` string,
  `page_type` string,
  `page_title` string,
  `page_status` string,
  `page_content` string,
  `page_parent_id` string,
  `labels` string,
  `page_version` string,
  `creator_id` string,
  `last_modifier_id` string,
  `created_date` string,
  `updated_date` string,
  `last_update_description` string
)
ROW FORMAT SERDE 'org.apache.hadoop.hive.serde2.OpenCSVSerde'
WITH SERDEPROPERTIES (
  "escapeChar" = "\\",
  'quoteChar' = '"',
  'separatorChar' = ','
) LOCATION 's3://my-data-pipeline-bucket/test-exports/'
TBLPROPERTIES ('has_encrypted_data'='false');

データ エクスポートに関する課題のトラブルシューティング

検索インデックスが最新でない場合など、さまざまな理由でエクスポートが失敗することがあります。一般的な障害に関するガイダンスとその解決方法については、ナレッジ ベースの「データ パイプラインのトラブルシューティング」をご参照ください。 

最終更新日 2024 年 4 月 2 日

この内容はお役に立ちましたか?

はい
いいえ
この記事についてのフィードバックを送信する
Powered by Confluence and Scroll Viewport.