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

データ パイプライン

Bitbucket Data Center と Server の管理

このページの内容

このセクションの項目

関連コンテンツ

  • 関連コンテンツがありません

お困りですか?

アトラシアン コミュニティをご利用ください。

コミュニティに質問

この機能は、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 (個人情報) と制限されたコンテンツを含むすべてのデータが含まれます。これはできる限り多くのデータを提供するためであり、フィルターや変換を行ってインサイトを生成できます。

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

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

パフォーマンスの影響

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

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

  • データのエクスポートは、アクティビティが少ない時間帯またはアクティビティのないノードで実行します。
  • 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 performance 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

We intentionally export data quite slowly to keep any performance degradation under a 5% threshold. If you run Bitbucket in a cluster, you could use your load balancer to redirect traffic away from the node performing the export.

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

データをエクスポートするには、データ パイプライン REST API を使用します。

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

現在の状態データをエクスポートするには、<base-url>/rest/datapipeline/latest/export に POST リクエストを実行します。

エクスポートされるデータを fromDate 値の後に作成または更新されたエンティティだけに制限するには、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)

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

認証に 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
  }
  "rootExportPath":"/path/data-pipeline/export"
}

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
  }
  "rootExportPath":"/path/data-pipeline/export"
}

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."
    }
  ]
  "rootExportPath":"/path/data-pipeline/export"
}

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

または、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."
    }
  ]
  "rootExportPath":"/path/data-pipeline/export"
}

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

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

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

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

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 を埋め込まれた改行ごとに出力します。

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.

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

アプリケーションの管理コンソールからエクスポートのステータスを確認して、最後にエクスポートを実行した日時を確認できます。データ エクスポート ステータスを表示するには、次の手順に従います。

  1. Go to  > System. 
  2. [データ パイプライン] を選択します。

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

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

出力ファイル 

データ エクスポートを実行するたびに、数値ジョブ 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>_<timestamp>.csv 
  • commits_<job_id>_<timestamp>.csv
  • pull_request_activities_<job_id>_<timestamp>.csv
  • pull_requests_<job_id>_<timestamp>.csv
  • repositories_<job_id>_<timestamp>.csv
  • users_<job_id>_<timestamp>.csv

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

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

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

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

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

{
  "path": "/tmp/new/path"
}

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

応答の例
コー​​ド応答の例
200

パスが書き込み可能で承認された場合

{
"exportPath":"/tmp/new/path/data-pipeline/export",
"customPathSet":true
}


エクスポート パスを確認するには、<base-url>/rest/datapipeline/1.0/config/export-path に GET リクエストを実行します。

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

応答の例...
コー​​ド応答の例
200

カスタム パスが設定されている場合

{
"exportPath":"/tmp/example/pipeline",
"customPathSet":true
}
200

カスタム パスが未設定の際は、デフォルトの共有ホーム パスが返されます

{
"exportPath":"/shared/home/export/path",
"customPathSet":false
}

デフォルトのエクスポート パスに戻す

デフォルト パスに戻すには、<base-url>/rest/datapipeline/1.0/config/export-path に DELETE リクエストを実行します。  

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

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

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

最終更新日 2022 年 5 月 9 日

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

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

このセクションの項目

関連コンテンツ

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