Knowledge Catalog (舊稱 Dataplex Universal Catalog) 可讓您使用中繼資料匯出工作，匯出中繼資料，以便在外部系統中使用。接著，您可以使用 BigQuery 等工具分析這項中繼資料、以程式輔助方式處理大量資料，或與自訂應用程式整合。
本文假設您已熟悉 Knowledge Catalog 中繼資料概念，包括項目群組、項目類型和切面類型。
工作範圍
工作範圍會定義要匯出的中繼資料。您必須為每項中繼資料匯出工作提供下列其中一項工作範圍：
- 組織：匯出組織的中繼資料。
- 專案：匯出屬於指定專案的中繼資料。
- 項目群組：匯出屬於指定項目群組的中繼資料。
您可以指定要納入工作的項目類型或切面類型，進一步限制範圍。工作只會匯出屬於這些項目類型和切面類型的項目和切面。
VPC Service Controls
Knowledge Catalog 使用 VPC Service Controls，為中繼資料匯出工作提供額外安全防護。工作所屬的專案會決定 VPC Service Controls perimeter，如下所示：
- 如果將工作範圍設為組織層級，會發生下列情況：
- 匯出範圍是工作所屬的組織。
- 只有 VPC Service Controls 範圍內的項目會匯出。
- 系統會排除位於工作組織內，但超出 VPC Service Controls 範圍的所有專案。
- 如果將工作範圍設為專案或項目群組，這些專案或項目群組必須與工作位於相同的 VPC Service Controls 範圍。如果任何專案或項目群組違反 VPC Service Controls 規則，工作就會失敗。
事前準備
匯出中繼資料前，請先完成本節的工作。
使用者必要角色
如要取得管理中繼資料匯出工作的權限，請要求管理員授予您下列 IAM 角色：
-
建立中繼資料匯出工作：
- 在要匯出的組織、專案或項目群組，具備 Dataplex 項目群組匯出者 (
roles/dataplex.entryGroupExporter) 角色 - 在執行中繼資料工作的專案中，具備Dataplex 工作中繼資料擁有者 (
roles/dataplex.metadataJobOwner) 角色
- 在要匯出的組織、專案或項目群組，具備 Dataplex 項目群組匯出者 (
-
存取匯出的結果：專案或 bucket 的「Storage Object Viewer」(Storage 物件檢視者) (
roles/storage.objectViewer) -
查看中繼資料工作：專案的 Dataplex 中繼資料工作檢視者 (
roles/dataplex.metadataJobViewer)
如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。
這些預先定義的角色具備管理中繼資料匯出工作所需的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：
所需權限
必須具備下列權限，才能管理中繼資料匯出工作：
-
匯出中繼資料：
-
dataplex.metadataJobs.create -
dataplex.entryGroups.export -
dataplex.entryGroups.get -
resourcemanager.projects.get -
resourcemanager.projects.list
-
-
存取匯出的結果：
storage.objects.get
Knowledge Catalog 服務帳戶的必要角色
為確保 Knowledge Catalog 服務帳戶具備存取 Cloud Storage bucket 的必要權限，請要求管理員授予該服務帳戶下列 bucket 權限：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 範圍。
執行中繼資料匯出工作
以下各節說明如何匯出不同工作範圍的中繼資料。
匯出組織的中繼資料
如要從組織匯出中繼資料，請使用 metadataJobs.create 方法，並將 organizationLevel 布林值設為 true。
使用任何要求資料之前，請先修改下列項目的值：
JOB_PROJECT：執行中繼資料工作的 Google Cloud專案。提供專案編號或專案 ID。LOCATION_ID： Google Cloud 位置，例如us-central1。METADATA_JOB_ID：選用。中繼資料工作 ID。BUCKET：要將中繼資料匯出至的 Cloud Storage bucket。您也可以在 bucket 名稱後方加上自訂前置字串，格式為
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,
},
}
}
請展開以下其中一個選項，以傳送要求：
回應會指出長時間執行的作業。匯出的中繼資料會儲存至 Cloud Storage bucket。
匯出特定專案的中繼資料
如要從一或多個專案匯出中繼資料，請使用 metadataJobs.create 方法，並提供專案清單。
使用任何要求資料之前，請先修改下列項目的值：
JOB_PROJECT：執行中繼資料工作的 Google Cloud專案。提供專案編號或專案 ID。LOCATION_ID： Google Cloud 位置，例如us-central1。METADATA_JOB_ID：選用。中繼資料工作 ID。BUCKET：要將中繼資料匯出至的 Cloud Storage bucket。您也可以在 bucket 名稱後方加上自訂前置字串，格式為
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
],
},
}
}
請展開以下其中一個選項，以傳送要求：
回應會指出長時間執行的作業。匯出的中繼資料會儲存至 Cloud Storage bucket。
匯出特定項目群組的中繼資料
如要從特定項目群組匯出中繼資料，請使用 metadataJobs.create 方法，並提供項目群組清單。
使用任何要求資料之前，請先修改下列項目的值：
JOB_PROJECT：執行中繼資料工作的 Google Cloud專案。提供專案編號或專案 ID。LOCATION_ID： Google Cloud 位置，例如us-central1。METADATA_JOB_ID：選用。中繼資料工作 ID。BUCKET：要將中繼資料匯出至的 Cloud Storage bucket。您也可以在 bucket 名稱後方加上自訂前置字串，格式為
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
],
},
}
}
請展開以下其中一個選項，以傳送要求：
回應會指出長時間執行的作業。匯出的中繼資料會儲存至 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
]
},
}
}
請展開以下其中一個選項，以傳送要求：
回應會指出長時間執行的作業。匯出的中繼資料會儲存至 Cloud Storage bucket。
取得中繼資料工作的詳細資料
如要取得中繼資料工作的相關資訊，例如工作狀態和匯出的項目數量，請使用 metadataJobs.get 方法。
中繼資料匯出結果
中繼資料匯出工作會匯出中繼資料工作建立時，Knowledge Catalog 中繼資料的快照。
匯出檔案內容
輸出檔案的內容格式與中繼資料匯入工作使用的中繼資料匯入檔案相同。您可以直接將輸出檔案做為中繼資料匯入工作的輸入內容。
匯出檔案位置
Knowledge 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/entrygroup=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 bucket 選取檔案：提供 Cloud Storage 資料夾的路徑，其中包含匯出的中繼資料檔案。如要納入 bucket 中的所有檔案，請使用星號 (
*) 萬用字元。例如：gs://export-bucket/example-folder/*。 - 檔案格式：選取「JSONL (Newline delimited JSON)」。
- 勾選「Source data partitioning」(來源資料分區) 核取方塊，然後在「Select Source URI Prefix」(選取來源 URI 前置字串) 中，提供 BigQuery 資料表的 Cloud Storage URI 前置字串，以定義分區。例如：
gs://export-bucket/example-folder/。 - 「Partition inference mode」(分區推論模式)：選取「Automatically infer types」(自動推論類型) 選項。
- 資料表類型：選取「外部資料表」選項。
「Schema」(結構定義)：按一下「Edit as text」(以文字形式編輯) 切換鈕，然後輸入下列匯出檔案的結構定義：
[ { "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 bucket 選取檔案：提供 Cloud Storage 資料夾的路徑，其中包含匯出的中繼資料檔案。如要納入 bucket 中的所有檔案，請使用星號 (
BigQuery 會建立外部資料表，其中包含匯出的中繼資料。資料表的結構定義包含 entry 結構定義資料欄，其中每一列代表一個項目。如要進一步瞭解項目的欄位，請參閱 ImportItem。資料表的結構定義也包含匯出檔案分區，如本文「匯出檔案位置」一節所述。
建立外部資料表後，您可以使用 GoogleSQL 語法查詢資料表。例如，如要查詢匯出的項目類型，請使用下列陳述式：
SELECT entry.entryType FROM `example-project.example-dataset.example-table` LIMIT 1000
後續步驟
- 瞭解如何使用 GoogleSQL 語法查詢 BigQuery 資料表。
- 使用代管連線管道，將中繼資料匯入 Knowledge Catalog。