メタデータ エクスポート ジョブを実行すると、外部システムで使用するために Dataplex Universal Catalog からメタデータをエクスポートできます。
メタデータをエクスポートする必要があるのは、次のようなシナリオです。
- BigQuery またはその他のデータ分析ツールを使用してメタデータをクエリして分析する
- 大量のメタデータをプログラムで処理し、後で Dataplex Universal Catalog にインポートする。
- メタデータをカスタム アプリケーションまたはサードパーティ製ツールに統合する
メタデータ エクスポート ジョブは、Dataplex Universal Catalog メタデータのスナップショットをエクスポートします。Dataplex Universal Catalog メタデータは、エントリとそのアスペクトで構成されます。このページの手順は、エントリ グループ、エントリタイプ、アスペクト タイプなど、Dataplex Universal Catalog のコンセプトを理解していることを前提としています。
ジョブスコープ
ジョブスコープでは、エクスポートするメタデータを定義します。メタデータ エクスポート ジョブごとに、次のいずれかのジョブスコープを指定する必要があります。
- 組織: 組織に属するメタデータをエクスポートします。
- プロジェクト: 指定したプロジェクトに属するメタデータをエクスポートします。
- エントリ グループ: 指定されたエントリ グループに属するメタデータをエクスポートします。
ジョブに含めるエントリタイプまたはアスペクト タイプを指定することで、スコープをさらに制限できます。ジョブは、これらのエントリタイプとアスペクト タイプに属するエントリとアスペクトのみをエクスポートします。
VPC Service Controls
Dataplex Universal Catalog は、VPC Service Controls を使用して、メタデータ エクスポート ジョブのセキュリティを強化します。ジョブが属するプロジェクトによって、VPC Service Controls の境界が決まります。
- ジョブスコープを組織レベルに設定すると、次の処理が行われます。
- エクスポート スコープはジョブが属する組織です。
- VPC Service Controls の境界内にあるエントリのみがエクスポートされます。
- ジョブの組織内にあっても VPC Service Controls の境界外のプロジェクトは除外されます。
- ジョブスコープをプロジェクトまたはエントリ グループに設定する場合、プロジェクトまたはエントリ グループはジョブと同じ VPC Service Controls 境界内に存在する必要があります。いずれかのプロジェクトまたはエントリ グループが VPC Service Controls のルールに違反している場合、ジョブは失敗します。
始める前に
メタデータをエクスポートする前に、このセクションのタスクを完了します。
エンドユーザーに必要なロール
メタデータ エクスポート ジョブの管理に必要な権限を取得するため、次の IAM ロールを付与するように管理者に依頼してください。
-
メタデータ エクスポート ジョブを作成する:
-
エクスポートする組織、プロジェクト、エントリ グループに対する Dataplex エントリ グループ エクスポータ(
roles/dataplex.entryGroupExporter
) -
メタデータ ジョブを実行するプロジェクトに対する Dataplex メタデータ ジョブ オーナー (
roles/dataplex.metadataJobOwner
)
-
エクスポートする組織、プロジェクト、エントリ グループに対する Dataplex エントリ グループ エクスポータ(
-
エクスポートされた結果にアクセスする: プロジェクトまたはバケットに対するストレージ オブジェクト閲覧者 (
roles/storage.objectViewer
) - メタデータ ジョブを表示する: プロジェクトに対する Dataplex メタデータ ジョブ閲覧者(
roles/dataplex.metadataJobViewer
)
ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。
これらの事前定義ロールには、メタデータ エクスポート ジョブの管理に必要な権限が含まれています。必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。
必要な権限
メタデータ エクスポート ジョブを管理するには、次の権限が必要です。
- メタデータをエクスポートする:
-
dataplex.metadataJobs.create
-
dataplex.entryGroups.export
-
dataplex.entryGroups.get
-
resourcemanager.projects.get
-
resourcemanager.projects.list
-
-
エクスポートされた結果にアクセスする:
storage.objects.get
カスタムロールや他の事前定義ロールを使用して、これらの権限を取得することもできます。
Dataplex Universal Catalog サービス アカウントに必要なロール
Dataplex Universal Catalog サービス アカウントに Cloud Storage バケットへのアクセスに必要な権限が付与されるようにするには、Dataplex Universal Catalog サービス アカウントにバケットに対する storage.buckets.get
、storage.objects.get
、storage.objects.create
の権限を付与するよう管理者に依頼してください。
Google Cloud リソースを構成する
After installing the Google Cloud CLI, initialize it by running the following command:
gcloud init
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
エクスポートされた結果を保存する Cloud Storage バケットを作成します。
バケットは、メタデータ ジョブと同じロケーションで、VPC Service Controls の境界内に存在する必要があります。
メタデータ エクスポート ジョブを実行する
以降のセクションでは、異なるジョブスコープでメタデータをエクスポートする方法について説明します。
組織からメタデータをエクスポートする
組織からメタデータをエクスポートするには、metadataJobs.create
メソッドを使用して、organizationLevel
ブール値を true
に設定します。
リクエストのデータを使用する前に、次のように置き換えます。
JOB_PROJECT
: メタデータ ジョブを実行する Google Cloudプロジェクト。プロジェクト番号またはプロジェクト ID を指定します。LOCATION_ID
: Google Cloud ロケーション(us-central1
など)。METADATA_JOB_ID
: 省略可。メタデータ ジョブ ID。BUCKET
: メタデータをエクスポートする Cloud Storage バケット。必要に応じて、バケット名の後にカスタム接頭辞を
gs://BUCKET/PREFIX/
の形式で含めることができます。カスタム接頭辞の最大長は 128 文字です。
HTTP メソッドと URL:
POST https://dataplex.googleapis.com/v1/projects/JOB_PROJECT/locations/LOCATION_ID/metadataJobs?metadataJobId=METADATA_JOB_ID
リクエストの本文(JSON):
{ "type": EXPORT, "export_spec": { "output_path": "gs://BUCKET/", "scope": { "organizationLevel": true, }, } }
リクエストを送信するには、次のいずれかのオプションを展開します。
レスポンスで長時間実行オペレーションを識別できます。エクスポートされたメタデータは Cloud Storage バケットに保存されます。
特定のプロジェクトからメタデータをエクスポートする
1 つ以上のプロジェクトからメタデータをエクスポートするには、metadataJobs.create
メソッドを使用してプロジェクトのリストを指定します。
リクエストのデータを使用する前に、次のように置き換えます。
JOB_PROJECT
: メタデータ ジョブを実行する Google Cloudプロジェクト。プロジェクト番号またはプロジェクト ID を指定します。LOCATION_ID
: Google Cloud ロケーション(us-central1
など)。METADATA_JOB_ID
: 省略可。メタデータ ジョブ ID。BUCKET
: メタデータをエクスポートする Cloud Storage バケット。必要に応じて、バケット名の後にカスタム接頭辞を
gs://BUCKET/PREFIX/
の形式で含めることができます。カスタム接頭辞の最大長は 128 文字です。METADATA_SOURCE_PROJECT
: メタデータをエクスポートするプロジェクト。プロジェクト番号またはプロジェクト ID を指定します。 プロジェクトは、メタデータ ジョブと同じ組織で、VPC Service Controls の境界内に存在する必要があります。
HTTP メソッドと URL:
POST https://dataplex.googleapis.com/v1/projects/JOB_PROJECT/locations/LOCATION_ID/metadataJobs?metadataJobId=METADATA_JOB_ID
リクエストの本文(JSON):
{ "type": EXPORT, "export_spec": { "output_path": "gs://BUCKET/", "scope": { "projects": [ "projects/METADATA_SOURCE_PROJECT", # Additional projects ], }, } }
リクエストを送信するには、次のいずれかのオプションを展開します。
レスポンスで長時間実行オペレーションを識別できます。エクスポートされたメタデータは Cloud Storage バケットに保存されます。
特定のエントリ グループのメタデータをエクスポートする
特定のエントリ グループからメタデータをエクスポートするには、metadataJobs.create
メソッドを使用してエントリ グループのリストを指定します。
リクエストのデータを使用する前に、次のように置き換えます。
JOB_PROJECT
: メタデータ ジョブを実行する Google Cloudプロジェクト。プロジェクト番号またはプロジェクト ID を指定します。LOCATION_ID
: Google Cloud ロケーション(us-central1
など)。METADATA_JOB_ID
: 省略可。メタデータ ジョブ ID。BUCKET
: メタデータをエクスポートする Cloud Storage バケット。必要に応じて、バケット名の後にカスタム接頭辞を
gs://BUCKET/PREFIX/
の形式で含めることができます。カスタム接頭辞の最大長は 128 文字です。ENTRY_GROUP
: ジョブのスコープ内にあるエントリ グループの相対的なリソース名(projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/entryGroups/ENTRY_GROUP_ID
形式)。エントリ グループは、メタデータ ジョブと同じプロジェクトに存在する必要があります。
HTTP メソッドと URL:
POST https://dataplex.googleapis.com/v1/projects/JOB_PROJECT/locations/LOCATION_ID/metadataJobs?metadataJobId=METADATA_JOB_ID
リクエストの本文(JSON):
{ "type": EXPORT, "export_spec": { "output_path": "gs://BUCKET/", "scope": { "entryGroups": [ "ENTRY_GROUP", # Additional entry groups ], }, } }
リクエストを送信するには、次のいずれかのオプションを展開します。
レスポンスで長時間実行オペレーションを識別できます。エクスポートされたメタデータは Cloud Storage バケットに保存されます。
特定のエントリタイプまたはアスペクト タイプからメタデータをエクスポートする
特定のエントリタイプまたはアスペクト タイプからメタデータをエクスポートするには、次の例に示すように、プライマリ ジョブ スコープを組織レベルなどに設定します。次に、エントリタイプ、アスペクト タイプ、またはその両方のリストを指定します。
リクエストのデータを使用する前に、次のように置き換えます。
ENTRY_TYPE
: 省略可。ジョブのスコープ内にあるエントリタイプの相対的なリソース名(projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/entryTypes/ENTRY_TYPE_ID
形式)。ASPECT_TYPE
: 省略可。ジョブのスコープ内にあるアスペクト タイプの相対的なリソース名(projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/aspectTypes/ASPECT_TYPE_ID
形式)。
HTTP メソッドと URL:
POST https://dataplex.googleapis.com/v1/projects/JOB_PROJECT/locations/LOCATION_ID/metadataJobs?metadataJobId=METADATA_JOB_ID
リクエストの本文(JSON):
{ "type": EXPORT, "export_spec": { "output_path": "gs://BUCKET/", "scope": { "organizationLevel": true, "entry_types": [ "ENTRY_TYPE", # Additional entry types ], "aspect_types": [ "ASPECT_TYPE", # Additional aspect types ] }, } }
リクエストを送信するには、次のいずれかのオプションを展開します。
レスポンスで長時間実行オペレーションを識別できます。エクスポートされたメタデータは Cloud Storage バケットに保存されます。
メタデータ ジョブの詳細情報を取得する
メタデータ ジョブに関する情報(ジョブのステータス、エクスポートされたエントリの数など)を取得するには、metadataJobs.get
メソッドを使用します。
メタデータのエクスポート結果
メタデータ エクスポート ジョブは、メタデータ ジョブの作成時の Dataplex Universal Catalog メタデータのスナップショットをエクスポートします。
ファイル コンテンツをエクスポートする
出力ファイルの内容は、メタデータ インポート ジョブに使用されるメタデータ インポート ファイルと同じ形式になります。出力ファイルは、メタデータ インポート ジョブの入力として直接使用できます。
エクスポート ファイルの場所
Dataplex Universal Catalog は、エクスポート結果ファイルをオブジェクトとして Cloud Storage バケットに保存します。
各出力ファイルのオブジェクト パスは、エクスポート ジョブで指定したバケット名とカスタム接頭辞を使用して作成され、その後にシステム生成パスが続きます。システム生成パスは、BigQuery との統合用に設計されています。オブジェクト パスの形式は次のとおりです。
gs://BUCKET/PREFIX/year=YYYY/month=MM/day=DD/consumer_project=JOB_PROJECT/job=METADATA_JOB_ID/project=METADATA_SOURCE_PROJECT/entry_group=ENTRY_GROUP/FILE_NUMBER.jsonl
次の点にご注意ください。
- システム生成パスは、エクスポート ジョブの作成日付の標準 Hive パーティション形式で始まります。この形式は BigQuery でサポートされています。詳細については、外部パーティション分割データの読み込みをご覧ください。
consumer_project
パラメータは、メタデータ エクスポート ジョブを実行するプロジェクトです。project
パラメータは、エクスポートするメタデータを含むプロジェクトです。- 以前のジョブが削除されている場合は、メタデータ ジョブ ID を再利用できます。ただし、ジョブを削除しても、そのジョブによってエクスポートされたファイルは削除されません。つまり、削除されたジョブ ID を再利用すると、出力ファイルパスに重複するジョブ ID が表示される可能性があります。
各出力ファイルには、
1
から始まる整数のファイル番号が付けられます。メタデータ エクスポート ジョブに大量のエントリが含まれている場合、ジョブは結果を複数のファイルに分割して、各出力ファイルのサイズを制限します。各出力ファイル内のエントリの最大数は 1,000,000 です。
出力ファイルの例
複数のプロジェクトを含むメタデータ エクスポート ジョブの出力ファイルの例を次に示します。
gs://export-bucket/example-folder/year=2025/month=04/day=13/consumer_project=admin-project/job=example-job/project=metadata-project-1/entrygroup=entry-group-1/1.jsonl gs://export-bucket/example-folder/year=2025/month=04/day=13/consumer_project=admin-project/job=example-job/project=metadata-project-2/entrygroup=entry-group-1/1.jsonl gs://export-bucket/example-folder/year=2025/month=04/day=13/consumer_project=admin-project/job=example-job/project=metadata-project-3/entrygroup=entry-group-2/1.jsonl
大規模なエントリ グループを含むメタデータ エクスポート ジョブの出力ファイルの例を次に示します。エントリ グループの結果が複数のファイルに分割されました。
gs://export-bucket/example-folder/year=2025/month=04/day=13/consumer_project=admin-project/job=another-example-job/project=example-metadata-project/entrygroup=big-entry-group/1.jsonl gs://export-bucket/example-folder/year=2025/month=04/day=13/consumer_project=admin-project/job=another-example-job/project=example-metadata-project/entrygroup=big-entry-group/2.jsonl
エクスポートされたメタデータを BigQuery で分析する
エクスポートされたメタデータを BigQuery で分析する場合は、エクスポートされたメタデータの外部テーブルを作成できます。外部テーブルを作成すると、追加のデータの読み込みや変換を行わずに、エクスポートされたデータをクエリできます。たとえば、エントリ グループごとのエントリ数をカウントしたり、特定の要素を含むエントリを見つけたり、BigQuery で追加の分析を実行できます。
手順は次のとおりです。
Hive パーティション分割データ用の外部テーブルを作成します。次の情報を提供します。
- Cloud Storage バケットからファイルを選択: エクスポートされたメタデータ ファイルを含む Cloud Storage フォルダのパスを提供します。バケット内のすべてのファイルを含めるには、ワイルドカードとしてアスタリスク(
*
)を使用します。例:gs://export-bucket/example-folder/*
。 - ファイル形式: [JSONL(改行区切り JSON)] を選択します。
- [ソースデータ パーティショニング] チェックボックスをオンにして、[ソース URI の接頭辞を選択] で、パーティションを定義する BigQuery テーブルの Cloud Storage URI 接頭辞を指定します。例:
gs://export-bucket/example-folder/
- パーティション推論モード: [種類を自動的に推測します] オプションを選択します。
- テーブルタイプ: [外部テーブル] オプションを選択します。
スキーマ: [テキストとして編集] をクリックし、エクスポート ファイルの次のスキーマ定義を入力します。
[ { "name": "entry", "type": "RECORD", "mode": "NULLABLE", "fields": [ { "mode": "NULLABLE", "name": "name", "type": "STRING" }, { "mode": "NULLABLE", "name": "entryType", "type": "STRING" }, { "mode": "NULLABLE", "name": "createTime", "type": "STRING" }, { "mode": "NULLABLE", "name": "updateTime", "type": "STRING" }, { "mode": "NULLABLE", "name": "aspects", "type": "JSON" }, { "mode": "NULLABLE", "name": "parentEntry", "type": "STRING" }, { "mode": "NULLABLE", "name": "fullyQualifiedName", "type": "STRING" }, { "mode": "NULLABLE", "name": "entrySource", "type": "RECORD", "fields": [ { "mode": "NULLABLE", "name": "resource", "type": "STRING" }, { "mode": "NULLABLE", "name": "system", "type": "STRING" }, { "mode": "NULLABLE", "name": "platform", "type": "STRING" }, { "mode": "NULLABLE", "name": "displayName", "type": "STRING" }, { "mode": "NULLABLE", "name": "description", "type": "STRING" }, { "mode": "NULLABLE", "name": "labels", "type": "JSON" }, { "mode": "REPEATED", "name": "ancestors", "type": "RECORD", "fields": [ { "mode": "NULLABLE", "name": "name", "type": "STRING" }, { "mode": "NULLABLE", "name": "type", "type": "STRING" } ] }, { "mode": "NULLABLE", "name": "createTime", "type": "STRING" }, { "mode": "NULLABLE", "name": "updateTime", "type": "STRING" }, { "mode": "NULLABLE", "name": "location", "type": "STRING" } ] } ] } ]
- Cloud Storage バケットからファイルを選択: エクスポートされたメタデータ ファイルを含む Cloud Storage フォルダのパスを提供します。バケット内のすべてのファイルを含めるには、ワイルドカードとしてアスタリスク(
BigQuery は、エクスポートされたメタデータを含む外部テーブルを作成します。テーブルのスキーマには entry
スキーマ列が含まれます。各行は 1 つのエントリを表します。エントリのフィールドの詳細については、ImportItem
をご覧ください。このドキュメントのエクスポート ファイルの場所のセクションで説明されているように、テーブルのスキーマにはエクスポート ファイル パーティションも含まれています。
外部テーブルを作成したら、GoogleSQL 構文を使用してテーブルをクエリできます。たとえば、エクスポートされたエントリタイプをクエリするには、次のステートメントを使用します。
SELECT entry.entryType FROM `example-project.example-dataset.example-table` LIMIT 1000
次のステップ
- GoogleSQL 構文を使用して BigQuery テーブルをクエリする方法を確認する。
- マネージド接続パイプラインを使用して、メタデータを Dataplex Universal Catalog にインポートする。