ExportMetadata

メタデータ エクスポート ジョブを実行すると、外部システムで使用するために 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.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.getstorage.objects.getstorage.objects.create の権限を付与するよう管理者に依頼してください。

Google Cloud リソースを構成する

  1. 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.

  2. エクスポートされた結果を保存する 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"
                }
              ]
            }
          ]
        }
      ]
      

BigQuery は、エクスポートされたメタデータを含む外部テーブルを作成します。テーブルのスキーマには entry スキーマ列が含まれます。各行は 1 つのエントリを表します。エントリのフィールドの詳細については、ImportItem をご覧ください。このドキュメントのエクスポート ファイルの場所のセクションで説明されているように、テーブルのスキーマにはエクスポート ファイル パーティションも含まれています。

外部テーブルを作成したら、GoogleSQL 構文を使用してテーブルをクエリできます。たとえば、エクスポートされたエントリタイプをクエリするには、次のステートメントを使用します。

SELECT entry.entryType FROM `example-project.example-dataset.example-table` LIMIT 1000

次のステップ