Confluence サポート

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

データパイプラインを使用すると、Jira または Confluence サイトからデータをエクスポートして既存のデータプラットフォーム (Tableau や PowerBI など) に、簡単にフィードできるようになります。これによって次を行えます。

内容がより豊富なレポートを生成して、サイトアクティビティを視覚化する
チームがどのようにアプリケーションを使用しているかをより詳しく理解する
組織における Jira または Confluence の使用の最適化に関してより適切な決定を下す

REST API を使用して現在の状態データのデータエクスポートをトリガーし、アプリケーションの管理コンソールでエクスポートのステータスを表示できます。データは CSV 形式でエクスポートされます。データエクスポートの一括操作は一度に 1 つしか実行できません。

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

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

Jira 8.14 以降
Confluence 7.12 以降

On this page:

要件

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

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

Considerations

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

セキュリティ

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

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

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

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

データのエクスポートは、アプリケーションノード、データベース、インデックスに影響を与える、リソースを大量に消費するプロセスです。内部テストでは、エクスポートをアクティブに実行しているノードのすべての製品機能について、パフォーマンス低下が発生しました。

パフォーマンスの問題のリスクを最小限に抑えるため、次を強くお勧めします。

データのエクスポートは、アクティビティが少ない時間帯またはアクティビティのないノードで実行します。
fromDate パラメーターを使用してエクスポートするデータの量を制限します。日付が古過ぎるとより多くのデータがエクスポートされるため、データのエクスポート時間が長くなります。

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

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

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

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

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

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

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

データエクスポートの実行

現在の状態データをエクスポートするには、/export REST API エンドポイントを使用します。

https://<base-url>/rest/datapipeline/latest/export?
fromDate=<yyyy-MM-ddTHH:mmTZD>

fromDate パラメーターはエクスポートするデータの量を制限します。つまり fromDate 値の後に作成または更新されたエンティティのデータのみがエクスポートされます。

fromDate パラメーターなしでエクスポートをトリガーすると、直近の 365 日内のすべてのデータがエクスポートされます。

アプリケーションが、/jira や /confluence などのコンテキストパスを使用するように設定されている場合は、これを必ず <base-url> に含めます。

/export REST API エンドポイントには、次の 3 つのメソッドがあります。

POST メソッド...

POST メソッド

POST メソッドを使用する際は、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)

認証に 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リクエストには次の応答があります。

コード

説明

202

データエクスポートが開始されました。以下に例を示します。

{
  "startTime":"2021-03-03T12:08:24.045+11:00",
  "nodeId":"node1",
  "jobId":124,
  "status":"STARTED",
  "config":{
     "exportFrom":"2020-03-03T12:08:24.036+11:00",
     "forcedExport":false
  }
}

409

別のデータエクスポートがすでに実行されています。

{

  "startTime":"2021-03-03T12:08:24.045+11:00",
  "nodeId":"node1",
  "jobId":124,
  "status":"STARTED",
  "config":{
     "exportFrom":"2020-03-03T12:08:24.036+11:00",
     "forcedExport":false
  }
}

422

インデックスの整合性がないため、データのエクスポートに失敗しました:

{
  "startTime": "2021-01-13T09:01:01.917+11:00",
  "completedTime": "2021-01-13T09:01:01.986+11:00",
  "nodeId": "node2",
  "jobId": 56,
  "status": "FAILED",
  "config": {
    "exportFrom": "2020-07-17T08:00:00+10:00",
    "forcedExport": false
  },
  "errors": [
    {
      "key": "export.pre.validation.failed",
      "message": "Inconsistent index used for export job."
    }
  ]
}

この問題が発生した場合は、インデックスの再作成とデータのエクスポートの再試行が必要になる場合があります。

または、forceExport=true クエリパラメーターを使用して、データのエクスポートを強制できます。ただし、整合性のないインデックスでエクスポートを強制すると、データが不完全になる可能性があります。

データが不完全である可能性があることを警告するために、一貫性のないインデックスを強制的にエクスポートすると次の応答が返されます。

{
  "startTime": "2021-01-13T09:01:42.696+11:00",
  "nodeId": "node2",
  "jobId": 57,
  "status": "STARTED",
  "config": {
    "exportFrom": "2020-07-17T08:01:00+10:00",
    "forcedExport": true
  },
  "warnings": [
    {
      "key": "export.pre.validation.failed",
      "message": "Inconsistent index used for export job."
    }
  ]
}

GET メソッド...

GET メソッド

GET リクエストは 200 コードを返しますが、エクスポートがどのステージにあるかによって応答が異なります。

ステータス	応答の例
最初のエクスポートを開始する前	`{}`
エクスポート中	`{ "startTime": "2020-11-01T06-35-41-577+11", "nodeId": "node1", "jobId": 125, "status": "STARTED" "config":{ "exportFrom":"2020-03-03T12:08:24.036+11:00", "forcedExport":false } }`
エクスポートが成功した後	`{ "startTime":"2021-03-03T12:08:24.045+11:00", "completedTime":"2021-03-03T12:08:24.226+11:00", "nodeId":"node3", "jobId":125, "status":"COMPLETED", "config": { "exportFrom":"2020-03-03T12:08:24.036+11:00", "forcedExport":false }, "statistics" { "exportedEntities":23, "writtenRows":54 } }`
キャンセルリクエストのあと、ただし実際にエクスポートがキャンセルされる前	`{ "startTime":"2021-03-03T12:08:24.045+11:00", "completedTime":"2021-03-03T12:08:24.226+11:00", "nodeId":"Node1", "jobId":125, "status":"CANCELLATION_REQUESTED", "config": { "exportFrom":"2020-03-03T12:08:24.036+11:00", "forcedExport":false }, }`
エクスポートがキャンセルされた後	`{ "startTime": "2020-11-02T04-20-34-007+11", "cancelledTime": "2020-11-02T04-24-21-717+11", "completedTime": "2020-11-02T04-24-21-717+11", "nodeId":"node2", "jobId":125, "status":"CANCELLED", "config": { "exportFrom":"2020-03-03T12:08:24.036+11:00", "forcedExport":false }, "statistics" { "exportedEntities":23, "writtenRows":12 } }`

DELETE メソッド...

DELETE メソッド

DELETE リクエストには次の応答があります。

コード説明

200

キャンセルを受け付けました。

{
  "status": "OK",
  "message": "Cancellation request successfully received.
 Currently running export job will be stopped shortly."
}

409

進行中のエクスポートがないため、リクエストは破棄されました。

{
  "status": "WARNING",
  "message": "Cancellation request aborted. There is no
export job running to cancel."
}

自動キャンセル

データエクスポートを実行するノードが正常にシャットダウンされると、エクスポートは CANCELLED と自動でマークされます。

ただし、クラッシュまたはハードウェアレベルの障害が発生して JVM に通知されなかった場合、エクスポートプロセスはロックされることがあります。この場合、DELETE リクエストを通じてエクスポートを CANCELLED としてマークする必要があります。これによって、プロセスがロックから解放されて別のデータエクスポートを実行できます。

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

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

既定値	説明
plugin.data.pipeline.embedded.line.break.preserve
`false`	埋め込まれた改行を出力ファイルに保持するかどうかを指定します。Hadoop などのツールでは、改行が問題になる場合があります。このプロパティはデフォルトで `False` に設定されています。つまり、改行はエスケープされます。
plugin.data.pipeline.embedded.line.break.escape.char
`\\n`	埋め込まれた改行の文字をエスケープします。デフォルトでは、`\n` を埋め込まれた改行ごとに出力します。

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

アプリケーションの管理コンソールから、エクスポートのステータスを表示して最後にエクスポートを実行した日時を確認できます。データエクスポートのステータスを表示するには、 > [一般設定] > [データパイプライン] の順に移動します。

エクスポートステータスは多数あります。

開始前 - エクスポートは現在実行されていません
開始 - エクスポートは現在実行中です
完了 - エクスポートが完了しました
リクエストをキャンセル - キャンセルリクエストが送信されました
キャンセル - エクスポートがキャンセルされました
失敗 - エクスポートに失敗しました。

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

出力ファイル

データエクスポートを実行するたびに、数値ジョブ 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>_<timestamp>.csv
spaces_job<job_id>_<timestamp>.csv
pages_job<job_id>_<timestamp>.csv
comments_job<job_id>_<timestamp>.csv
analytics_events_job<job_id>_<timestamp>.csv

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

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');

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

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

Confluence サポート

ナレッジベース

製品

Jira Software

Jira Service Management

Jira Work Management

Confluence

Bitbucket

リソース

関連ドキュメント

コミュニティ

提案とバグ

Marketplace

請求とライセンス情報

データパイプライン

Confluence データ管理

このページの内容

このセクションの項目

お困りですか?

要件

Considerations

セキュリティ

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

データエクスポートの実行

POST メソッド

GET メソッド

DELETE メソッド

自動キャンセル

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

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

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

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

出力ファイル

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

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

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

このセクションの項目

ページ

Viewport

Confluence

バージョン

データ パイプライン

Confluence データ管理

このページの内容

このセクションの項目

関連コンテンツ

お困りですか?

要件

Considerations

セキュリティ

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

データ エクスポートの実行

POST メソッド

GET メソッド

DELETE メソッド

自動キャンセル

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

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

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

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

出力ファイル

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

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

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

このセクションの項目

関連コンテンツ

データパイプライン

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

データエクスポートの実行

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

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