Confluence サポート

この機能は、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 を使用してデータのエクスポートをトリガーするには、次が必要です。

有効な Confluence Data Center ライセンス
システム管理者グローバル権限

Considerations

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

セキュリティ

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

エクスポートは必要な頻度で実行するようにスケジュールできます。複数の曜日にエクスポートすることを選択した場合、最初のエクスポートはスケジュールを保存した後の直近の曜日に行われます。上のスクリーンショットの例では、木曜日にスケジュールを設定した場合は最初のエクスポートは土曜日に、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-path に PUT リクエストを実行します。

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

既定のパスに戻す方法を含む詳細については「データパイプライン 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');

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

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

ページ

Viewport

Confluence

バージョン

データ パイプライン

Confluence データ管理

このページの内容

このセクションの項目

関連コンテンツ

お困りですか?

要件

Considerations

セキュリティ

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

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

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

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

エクスポート スキーマ

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

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

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

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

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

plugin.data.pipeline.embedded.line.break.preserve

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

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

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