クラウド
Data Center 8.19
バージョン

データ パイプライン

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

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

Small data set

  • 27 million commits

  • 250,000 pull requests

  • 1.5 million pull request activity records

  • 6,500 repositories

  • 2,000 ユーザー

10 時間

Large data set

  • 207 million commits

  • 1 million pull requests

  • 6.8 million pull request activity records

  • 52,000 repositories

  • 25,000 ユーザー

35 時間

Test performance vs production

The data presented here is based on our own internal testing. The actual duration and impact of a data export on your own environment will likely differ depending on:

  • インフラストラクチャ、構成、負荷
  • amount of pull request activity to be exported.

Our tests were conducted on Data Center instances in AWS:

  • Small - EC2 instance type m5d.4xlarge and RDS instance type db.m4.4xlarge
  • Large - EC2 instance type c5.2xlarge and RDS instance type db.m5.large

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

To access the data pipeline select  > Data pipeline.

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

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

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

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

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

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

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

エクスポート スキーマ

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

これらのプロジェクトは、今後すべてのエクスポートから除外されます。オプトアウトの機能はデータ パイプラインのバージョン 2.3.0 以降で導入されたことにご注意ください。

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

データ エクスポートを設定する

You can configure the format of the export data through the following configuration properties.

既定値説明
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 に設定します (非推奨)。

The following additional properties only apply to Bitbucket. 
既定値説明
plugin.data.pipeline.bitbucket.export.personal.forked.repository.commits
false

Specifies whether commits from forked repositories in personal projects should be exported. Set this property to True to include commits from forked repositories in personal projects.

plugin.data.pipeline.bitbucket.export.build.statuses
false

Specifies whether build statuses should be included in the export. Exporting build statuses can take a significant amount of time if you have a lot of builds. 

Set this property to true to export build statuses. 

plugin.data.pipeline.bitbucket.commit.queue.polling.timeout.seconds
20

Time, in seconds, it takes to receive the first commit from git process.

You should only need to change this if you see a CommitStreamingException (this error is usually caused by another underlying problem).

plugin.data.pipeline.bitbucket.commit.git.execution.timeout.seconds
3600

Sets the idle and execution timeout for the git ref-list command. You should only need to change this if you see "an error occurred while executing an external process: process timed out" error.

plugin.data.pipeline.bitbucket.export.pull.request.activities
true

Specifies whether historical data about pull request activity data should be included in the export. Exporting activity data will significantly increase your export duration. 

Set this property to false to exclude pull request activity from your export.

データ パイプライン 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 ファイルとして保存されます。ファイルは次のディレクトリに保存されます。

  • <shared-home>/data-pipeline/export/<job-id> if you run Bitbucket in a cluster

  • <local-home>/shared/data-pipeline/export/<job-id> you are using non-clustered Bitbucket.

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

  • build_statuses_<job_id>_<schema_version>_<timestamp>.csv 
  • commits_<job_id>_<schema_version>_<timestamp>.csv
  • pull_request_activities_<job_id>_<schema_version>_<timestamp>.csv
  • pull_requests_<job_id>_<schema_version>_<timestamp>.csv
  • repositories_<job_id>_<schema_version>_<timestamp>.csv
  • users_<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 (
  `repository_id` string, 
  `instance_url` string,
  `url` string,
  `repository_name` string,
  `description` string,
  `hierarchy_id` string,
  `origin` string,
  `project_id` string,
  `project_key` string,
  `project_name` string,
  `project_type` string,
  `forkable` string,
  `fork` string,
  `public` 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');

失敗したエクスポートのトラブルシューティング

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

Last modified on Mar 22, 2024

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

はい
いいえ
この記事についてのフィードバックを送信する

このセクションの項目

関連コンテンツ

  • 関連コンテンツがありません
Powered by Confluence and Scroll Viewport.