本頁面由 Cloud Translation API 翻譯而成。

匯出中繼資料

您可以執行中繼資料匯出工作，將 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) 您在其中執行中繼資料工作的專案
存取匯出的結果：專案或 bucket 的「Storage 物件檢視者」 (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 資源

安裝 Google Cloud CLI。安裝完成後，執行下列指令初始化 Google Cloud CLI：
```
gcloud init
```
如果您使用外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。
建立 Cloud Storage bucket，儲存匯出的結果。

bucket 必須與中繼資料工作位於相同的位置和 VPC Service Controls 範圍。

執行中繼資料匯出工作

以下各節說明如何匯出不同工作範圍的中繼資料。

匯出機構的中繼資料

如要匯出貴機構的 Metadata，請使用 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 方法和網址：

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,
    },
  }
}

如要傳送要求，請展開以下其中一個選項：

curl (Linux、macOS 或 Cloud Shell)

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或使用 Cloud Shell，自動登入 gcloud CLI。您可以執行 gcloud auth list 查看目前有效的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://dataplex.googleapis.com/v1/projects/JOB_PROJECT/locations/LOCATION_ID/metadataJobs?metadataJobId=METADATA_JOB_ID"

PowerShell (Windows)

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list 查看目前有效的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://dataplex.googleapis.com/v1/projects/JOB_PROJECT/locations/LOCATION_ID/metadataJobs?metadataJobId=METADATA_JOB_ID" | Select-Object -Expand Content

回應會指出長時間執行的作業。匯出的中繼資料會儲存至 Cloud Storage bucket。

匯出特定專案的中繼資料

如要從一或多個專案匯出中繼資料，請使用 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 方法和網址：

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
      ],
    },
  }
}

如要傳送要求，請展開以下其中一個選項：

curl (Linux、macOS 或 Cloud Shell)

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://dataplex.googleapis.com/v1/projects/JOB_PROJECT/locations/LOCATION_ID/metadataJobs?metadataJobId=METADATA_JOB_ID"

PowerShell (Windows)

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list 查看目前有效的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://dataplex.googleapis.com/v1/projects/JOB_PROJECT/locations/LOCATION_ID/metadataJobs?metadataJobId=METADATA_JOB_ID" | Select-Object -Expand Content

回應會指出長時間執行的作業。匯出的中繼資料會儲存至 Cloud Storage bucket。

匯出特定項目群組的中繼資料

如要從特定項目群組匯出中繼資料，請使用 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 方法和網址：

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
      ],
    },
  }
}

如要傳送要求，請展開以下其中一個選項：

curl (Linux、macOS 或 Cloud Shell)

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://dataplex.googleapis.com/v1/projects/JOB_PROJECT/locations/LOCATION_ID/metadataJobs?metadataJobId=METADATA_JOB_ID"

PowerShell (Windows)

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list 查看目前有效的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://dataplex.googleapis.com/v1/projects/JOB_PROJECT/locations/LOCATION_ID/metadataJobs?metadataJobId=METADATA_JOB_ID" | Select-Object -Expand Content

回應會指出長時間執行的作業。匯出的中繼資料會儲存至 Cloud Storage bucket。

從特定項目類型或切面類型匯出中繼資料

如要從特定項目類型或切面類型匯出中繼資料，請設定主要工作範圍，例如機構層級，如下列範例所示。然後提供項目類型、切面類型或兩者的清單。

使用任何要求資料之前，請先替換以下項目：

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 方法和網址：

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
      ]
    },
  }
}

如要傳送要求，請展開以下其中一個選項：

curl (Linux、macOS 或 Cloud Shell)

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://dataplex.googleapis.com/v1/projects/JOB_PROJECT/locations/LOCATION_ID/metadataJobs?metadataJobId=METADATA_JOB_ID"

PowerShell (Windows)

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list 查看目前有效的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://dataplex.googleapis.com/v1/projects/JOB_PROJECT/locations/LOCATION_ID/metadataJobs?metadataJobId=METADATA_JOB_ID" | Select-Object -Expand Content

回應會指出長時間執行的作業。匯出的中繼資料會儲存至 Cloud Storage bucket。

取得中繼資料工作的詳細資料

如要取得中繼資料工作相關資訊，例如工作狀態和匯出的項目數量，請使用 metadataJobs.get 方法。

中繼資料匯出結果

中繼資料匯出工作會匯出中繼資料工作建立時的 Dataplex Universal Catalog 中繼資料快照。

匯出檔案內容

輸出檔案的內容格式與用於中繼資料匯入作業的中繼資料匯入檔案相同。您可以直接將輸出檔案做為中繼資料匯入作業的輸入內容。

匯出檔案位置

Dataplex Universal Catalog 會將匯出結果檔案儲存至 Cloud Storage bucket，做為物件。

每個輸出檔案的物件路徑都是使用您在匯出工作中指定的 bucket 名稱和自訂前置字串建構而成，後面接著系統產生的路徑。系統產生的路徑是為了與 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 結構定義資料欄，其中每一列代表一個項目。如要進一步瞭解項目的欄位，請參閱 ImportItem。如本文「匯出檔案位置」一節所述，資料表的結構定義也包含匯出檔案分割區。

建立外部資料表後，您就可以使用 GoogleSQL 語法查詢資料表。舉例來說，如要查詢匯出的項目類型，請使用下列陳述式：

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

後續步驟

瞭解如何使用 GoogleSQL 語法查詢 BigQuery 資料表。
使用受管理連線管道，將中繼資料匯入 Dataplex Universal Catalog。

匯出中繼資料 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

工作範圍

VPC Service Controls

事前準備

終端使用者必須具備的角色

所需權限

Dataplex Universal Catalog 服務帳戶的必要角色

設定 Google Cloud 資源

執行中繼資料匯出工作

匯出機構的中繼資料

curl (Linux、macOS 或 Cloud Shell)

PowerShell (Windows)

匯出特定專案的中繼資料

curl (Linux、macOS 或 Cloud Shell)

PowerShell (Windows)

匯出特定項目群組的中繼資料

curl (Linux、macOS 或 Cloud Shell)

PowerShell (Windows)

從特定項目類型或切面類型匯出中繼資料

curl (Linux、macOS 或 Cloud Shell)

PowerShell (Windows)

取得中繼資料工作的詳細資料

中繼資料匯出結果

匯出檔案內容

匯出檔案位置

輸出檔案範例

在 BigQuery 中分析匯出的中繼資料

後續步驟

匯出中繼資料