データ パイプライン

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

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

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

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

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

  • Jira 8.14 以降
  • Confluence 7.12 以降

このページの内容

要件

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

考慮事項

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

セキュリティ

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

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

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

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

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

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

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

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

数値おおよそのエクスポート時間
ユーザー100,0008 分
スペース15,00012 分
ページ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');

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

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

最終更新日 2021 年 9 月 14 日

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

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