自 2026 年 4 月 10 日起，Dataplex Universal Catalog 將更名為 Knowledge Catalog。API、用戶端程式庫、CLI 和 IAM 名稱維持不變。詳情請參閱「隆重推出 Google Cloud Knowledge Catalog」。

Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

從 dbt Core 匯入中繼資料

Knowledge Catalog (舊稱 Dataplex Universal Catalog) 可讓您使用 Google Cloud CLI 和 dbt 構件檔案，從 dbt Core、dbt Cloud 和 MetricFlow 匯入作業、語意和歷程中繼資料。您可以集中管理轉換中繼資料，而不是將其留在 dbt 生態系統中，協助資料工程師、數據分析工程師和資料監管人員探索及管理企業資料。

匯入的中繼資料和用途

dbt Core 是轉換引擎，而非 Oracle 或 PostgreSQL 等儲存系統，因此匯入中繼資料可支援不同的用途。您可以匯入 Oracle 或 PostgreSQL 中繼資料，回答「我們有哪些原始資料？」這個問題，並匯入 dbt Core 中繼資料，回答「我們的資料如何轉換、是否可靠，以及對業務有何意義？」這個問題。

執行 dbt 整合時，您會擷取下列中繼資料：

技術中繼資料：探索重要資源 (來源、種子、模型) 及其技術屬性 (資料欄名稱、資料類型、資料列數)，發掘企業資料。
業務和語意中繼資料：探索由 dbt MetricFlow 支援的業務定義和邏輯 (例如語意模型、指標和已儲存的查詢)，為 BI 工具和 AI 代理提供背景資訊。
作業和資料品質中繼資料：探索執行中繼資料 (例如時間、成功或失敗狀態、資料更新間隔和測試結果)，監控管道健康狀態及排解資料問題。
歷程和關係中繼資料：探索轉換圖 (DAG) 和 dbt 資源之間的依附元件、追蹤及連結實體轉換區塊的實體歷程、彙整鍵和動態彙整，以及父項與子項關係，藉此執行下游影響分析和根本原因追蹤。
消耗中繼資料：探索曝光中擷取的中繼資料，對應資料在 dbt 以外的使用方式，排解下游應用程式消耗轉換資料的問題。

限制

支援 dbt Core v1 (已針對 1.11 和 1.12 版進行驗證)、dbt Core v2 和 dbt Fusion。
gcloud CLI 586.0.0 以上版本支援 dbt 和 BigQuery 整合。如要安裝或更新 CLI，請參閱「安裝 Google Cloud CLI」。
無法直接連線至 dbt Cloud。如要從 dbt Cloud 工作匯入中繼資料，請先取得工作的構件。請參閱「從 dbt Cloud 執行作業匯入中繼資料」。
系統會截斷過大或深度巢狀的結構定義：單一面向不得超過每個面向的大小上限，因此深度巢狀結構定義可能會遺失結尾欄位。
--aspects-only可以新增及重新整理中繼資料，但無法移除。如要刪除 dbt 資源，必須完整執行。
這項整合功能僅支援 Data Lineage API 和圖表中 BigQuery 資源的 dbt 歷程事件。外部第三方來源的 dbt 項目 (來源、種子、模型) 不會擷取至資料歷程。
- 如要在 Data Lineage API 中擷取所有 dbt 歷程事件，請使用 OpenLineage dbt 整合功能。接著，將 OpenLineage 與 Knowledge Catalog 整合，匯入並以圖表呈現 dbt 的資料歷程。

事前準備

從 dbt Core 和 MetricFlow 匯入中繼資料前，請先完成下列工作：

授予必要的角色和權限。
啟用 Knowledge Catalog API。
符合 dbt 必要條件。
如果目的地項目群組不存在，請先建立。
瞭解 Cloud Storage 角色。

IAM 角色和權限

如要建立及管理 Knowledge Catalog 連接器工作，您必須具備可授予 Knowledge Catalog 和 Cloud Storage 權限的 Identity and Access Management (IAM) 角色。

如要取得設定 dbt 連接器所需的權限，請要求管理員授予您下列 IAM 角色：

如要建立及管理項目群組和項目連結，請在專案中具備下列角色： Dataplex Catalog 管理員 (roles/dataplex.catalogAdmin)、Dataplex Catalog 編輯者 (roles/dataplex.catalogEditor) 或 Dataplex 項目群組擁有者 (roles/dataplex.entryGroupOwner)。
如要執行 dbt gcloud 指令並建立中繼資料匯入工作，請遵循最小權限原則，並授予下列角色：
- 專案的 Dataplex 工作中繼資料擁有者 (roles/dataplex.metadataJobOwner)。
- 目標項目群組或專案的 Dataplex 項目群組匯入者 (roles/dataplex.entryGroupImporter)。如果您也匯入項目連結，請改為授予專案的 Dataplex 項目群組擁有者 (roles/dataplex.entryGroupOwner) 角色。此外，針對存放 dbt 模型寫入的 BigQuery 資料表的每個專案，也請授予Dataplex 項目擁有者 (roles/dataplex.entryOwner) 角色。如果是自訂角色，項目連結權限為 dataplex.entryGroups.useReferenceEntryLink、dataplex.entryGroups.useSchemaJoinEntryLink 和 dataplex.entryLinks.reference。
或者，您也可以在專案中授予 Dataplex Catalog 管理員 (roles/dataplex.catalogAdmin) 角色和 Dataplex 中繼資料工作擁有者 (roles/dataplex.metadataJobOwner) 角色。
如要將轉換後的中繼資料上傳至輸出暫存 bucket (--storage-uri)，請在暫存 bucket 上具備Storage 物件建立者 (roles/storage.objectCreator) 或 Storage 物件管理員 (roles/storage.objectAdmin) 角色。
如要從輸入 Cloud Storage bucket (--artifacts-path，如果使用 Cloud Storage) 讀取 dbt 構件：輸入構件 bucket 的 Storage 物件檢視者 (roles/storage.objectViewer) 或 Storage 物件管理員 (roles/storage.objectAdmin)。如果您具備 Storage 物件管理員角色，則不需要 Storage 物件檢視者角色。
如要查看 dbt 中繼資料：專案的 Dataplex Catalog 檢視者 (roles/dataplex.catalogViewer)。
如要在 Cloud Logging 查看記錄，請在專案中具備記錄檢視者 (roles/logging.viewer) 角色。

如果您具備必要權限，可以管理專案中的 IAM 存取權，則可執行下列 gcloud 指令，將這些角色授予自己的使用者帳戶：

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="user:USER_EMAIL" \
    --role="roles/dataplex.metadataJobOwner"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="user:USER_EMAIL" \
    --role="roles/dataplex.entryGroupOwner"

gcloud storage buckets add-iam-policy-binding gs://STAGING_BUCKET \
    --member="user:USER_EMAIL" \
    --role="roles/storage.objectCreator"

如果您使用服務帳戶執行匯入作業 (例如在自動化 CI/CD 管道中)，可以執行下列 gcloud 指令，將這些角色授予服務帳戶：

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/dataplex.metadataJobOwner"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/dataplex.entryGroupOwner"

gcloud storage buckets add-iam-policy-binding gs://STAGING_BUCKET \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/storage.objectCreator"

此外，您必須將輸出暫存 Cloud Storage bucket (--storage-uri) 的 Storage 物件檢視者 (roles/storage.objectViewer) 角色授予 Knowledge Catalog 服務代理 (service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com)，匯入工作才能讀取暫存的中繼資料檔案：

gcloud storage buckets add-iam-policy-binding gs://STAGING_BUCKET \
    --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com" \
    --role="roles/storage.objectViewer"

更改下列內容：

PROJECT_ID：您的 Google Cloud 專案 ID。
USER_EMAIL：您的使用者帳戶電子郵件地址。
SERVICE_ACCOUNT_EMAIL：服務帳戶電子郵件地址。
STAGING_BUCKET：輸出內容暫存 Cloud Storage bucket 的名稱 (--storage-uri)。
PROJECT_NUMBER：您的 Google Cloud 專案編號。

如要進一步瞭解如何授予角色，請參閱「管理存取權」。

啟用 API

啟用 Knowledge Catalog API。

啟用 API

dbt 必要條件

如要匯入整組 dbt 中繼資料，建議您產生全部四個 dbt JSON 構件檔案。只有 manifest.json 是必要項目，其他項目則可豐富匯入內容，即使沒有這些項目，轉換作業也能順利降級：

manifest.json (必要)：核心專案結構和執行圖。此外，也包含 MetricFlow 語意模型、指標和已儲存的查詢。
catalog.json：資料欄名稱和資料類型。如果沒有 catalog.json，系統會匯入結構定義切面，但資料欄不含類型。
run_results.json：測試結果和執行中繼資料。
sources.json：來源資料更新頻率。

在本機終端機、Cloud Shell 或已安裝 dbt 的自動化 CI/CD 環境中，前往 dbt 專案根目錄，並依序對單一設定檔和目標執行下列 dbt 指令，產生一整組 dbt 中繼資料構件 JSON 檔案：

dbt Core 2.x 和 dbt Fusion：
1. dbt source freshness
2. dbt build
3. dbt parse --write-catalog
  
  警告： 請勿在 dbt Core 2.x 或 dbt Fusion 上使用 dbt docs generate。不會寫入 catalog.json，且會覆寫 run_results.json，不含任何測試結果。dbt build --write-catalog 也不會寫入目錄，因此請使用獨立的 dbt parse --write-catalog 步驟。
dbt Core 1.x (dbt parse 不會寫入目錄)：
1. dbt source freshness
2. dbt build
3. dbt docs generate --no-compile
  
  警告： 如果沒有 --no-compile，dbt docs generate 會將 run_results.json 覆寫為每個節點的 success 狀態。系統會遺失先前 dbt build 的測試結果，且目錄會將每項資料品質測試回報為通過。

瞭解 Cloud Storage 角色

匯入 dbt 中繼資料時，會涉及兩個不同的 Cloud Storage 位置，其用途不同，不應混淆：

輸入 (dbt 來源構件)：產生的 dbt JSON 檔案所在位置。這可以是機器或 CI 執行器的本機目錄路徑 (例如 ./target/ 或 .)，也可以是輸入 Cloud Storage bucket URI 前置字串 (例如 gs://my-dbt-artifacts-bucket/target/)。您可以使用 --artifacts-path 旗標提供這個路徑。gcloud 指令會在工作準備期間讀取這些輸入檔案。如果使用 Cloud Storage，執行 gcloud 指令的呼叫端需要具備讀取權限 (roles/storage.objectViewer 或 roles/storage.objectAdmin)。Knowledge Catalog 服務代理不需要存取輸入構件 bucket。
輸出 (Knowledge Catalog 匯入暫存 bucket)：Cloud Storage bucket URI 前置字串 (例如 gs://my-staging-bucket/dbt-imports/)，gcloud 指令會將轉換後的中繼資料匯入檔案 (dbt_metadata.jsonl) 上傳至該位置，Knowledge Catalog 匯入工作則會在擷取期間從該位置讀取。您可以使用 --storage-uri 旗標提供這個 URI。執行 gcloud 指令的呼叫端需要寫入權限 (roles/storage.objectCreator 或 roles/storage.objectAdmin) 才能上傳檔案，而 Knowledge Catalog 服務代理程式則需要讀取權限 (roles/storage.objectViewer) 才能匯入檔案。

從 dbt Cloud 執行作業匯入中繼資料

Knowledge Catalog 不會直接連線至 dbt Cloud。dbt Cloud 工作產生的構件檔案與 dbt Core 相同，因此您可以將這些構件檔案擷取至本機目錄或輸入 Cloud Storage bucket，然後執行 gcloud 指令，從 dbt Cloud 匯入中繼資料。

擷取構件前，請先設定 dbt Cloud 工作，產生完整的構件組合。接著，您可以使用下列其中一種方法，從 dbt Cloud 工作執行作業擷取構件檔案：

從 dbt Cloud 控制台下載構件：從 dbt Cloud 使用者介面的工作執行詳細資料頁面，手動下載構件檔案，以便一次性匯入或進行初始測試。
使用 dbt 平台 CLI 下載構件：在本機終端機上執行 dbt Cloud 的 dbt 指令，在開發期間自動將生成的構件儲存至本機專案目錄。
使用 dbt Administrative API 下載構件：透過 HTTP 以程式輔助方式，從已完成的執行作業中擷取構件，用於自動化排程管道。

設定 dbt Cloud 工作

在 dbt Google Cloud 控制台中，調整工作設定，產生完整的中繼資料構件：

在「Execution settings」(執行設定) 部分，選取「Run source freshness」(執行來源更新程度)。dbt Cloud 會在工作指令前執行 dbt source freshness，產生 sources.json。
在「Commands」部分中，新增 dbt build。
新增指令，根據發布群組產生 catalog.json：
- dbt Core 2.x 和 dbt Fusion 發布群組：新增 dbt parse --write-catalog 做為工作指令。
- dbt Core 1.x 發布群組：請新增 dbt docs generate --no-compile 做為工作指令，而非選取「Generate docs on run」(執行時產生文件) 選項。勾選「Generate docs on run」(執行時產生文件) 核取方塊會執行 dbt docs generate，但不執行 --no-compile，這會覆寫 dbt build 的測試結果，詳情請參閱「dbt 必要條件」。請注意，如果指令步驟失敗，工作也會失敗，但核取方塊步驟不會導致工作失敗。

如果 dbt build 失敗 (例如測試失敗)，dbt Cloud 會略過後續指令，且執行作業不會有 catalog.json。如要一律產生，請在 dbt build 前方新增目錄指令。接著，目錄會說明建構前的資料表。

詳情請參閱 dbt 說明文件中的工作指令和發布群組。

從 dbt Google Cloud 控制台下載構件

如要在 dbtGoogle Cloud 控制台中，手動下載已完成執行的構件，請按照下列步驟操作：

在 dbt Google Cloud 控制台中，開啟已完成的工作執行作業。
前往「Artifacts」分頁，查看生成的構件檔案。
將 manifest.json、catalog.json、run_results.json 和 sources.json 下載到本機目錄。
在本機終端機或 Cloud Shell 中，執行「設定 dbt 連線能力」一節所述的 gcloud 匯入指令，並將 --artifacts-path 設為包含下載檔案的目錄。

詳情請參閱 dbt 說明文件中的「執行作業瀏覽權限」。

使用 dbt 平台 CLI 下載構件

dbt 平台 CLI (舊稱 dbt Cloud CLI) 會從本機終端機在 dbt Cloud 平台執行 dbt 指令，並自動將產生的構件下載到本機 dbt 專案的 target/ 目錄。

在本機終端機中，前往 dbt 專案根目錄，然後執行「dbt 必要條件」中列出的三個指令。
執行「設定 dbt 連線」一節所述的 gcloud 匯入指令，並將 --artifacts-path 設為專案根目錄或 target/ 目錄。

CLI 會使用您的個人資料倉儲憑證，在開發環境中執行，因此產生的中繼資料會反映開發結構定義，而非排定工作建構的正式版資料表。請使用 CLI 進行測試或開發工作流程，並使用部署工作排定正式環境匯入作業。

詳情請參閱 dbt 說明文件中的「安裝 dbt 平台 CLI」。

使用 dbt Administrative API 下載構件

您可以使用 dbt Administrative API，以程式輔助方式從任何已完成的工作執行作業擷取構件。List Run Artifacts 端點會傳回執行作業產生的檔案路徑，Retrieve Run Artifact 端點則會從下列網址下載特定構件檔案：

https://ACCESS_URL/api/v2/accounts/ACCOUNT_ID/runs/RUN_ID/artifacts/FILE

ACCESS_URL 取決於託管 dbt Cloud 帳戶的區域。使用 dbt Cloud 服務權杖驗證要求。詳情請參閱 dbt 說明文件的下列頁面：

從本機終端機、Cloud Shell 或自動化工作流程環境，將 manifest.json、catalog.json、run_results.json 和 sources.json 下載至本機目錄或 Cloud Storage bucket，然後針對該路徑執行「設定 dbt 連線」一節所述的 gcloud 指令。

根據預設，除非您指定 step 查詢參數，否則構件端點會傳回執行作業最後一個步驟的構件。按照「設定 dbt Cloud 工作」一節所述設定工作時，最後一個步驟是 dbt parse --write-catalog 或 dbt docs generate --no-compile，這只會寫入 catalog.json，並在預設步驟中保留其他三個構件。

擷取執行作業 ID

如要下載特定執行的構件，您需要該執行的 ID。您可以從 dbt Google Cloud 控制台的執行網址複製執行 ID，也可以透過終端機或工作流程指令碼查詢 API，找出最近一次成功執行的工作：

GET https://ACCESS_URL/api/v2/accounts/ACCOUNT_ID/runs/?job_definition_id=JOB_ID&status=10&order_by=-finished_at&limit=1

在查詢參數中，status=10 會篩選狀態為 Success 的已完成執行作業。您可以排定時間輪詢這個端點，找出最近一次成功執行的作業、下載其構件，並執行 gcloud 匯入指令。

使用 Webhook 觸發匯入作業

您可以設定 dbt Cloud Webhook，在工作執行完畢時自動觸發中繼資料匯入作業，不必輪詢 API。Webhook 會將酬載傳送至您提供的 HTTP 端點：

在 dbt Google Cloud 控制台中，依序前往「Account settings」(帳戶設定) >「Webhooks」(Webhook)，然後點選「Create webhook」(建立 Webhook) (或「Create new webhook」(建立新的 Webhook))。設定 Webhook 訂閱項目：
- 事件：選取「Run completed」(執行完成) (job.run.completed)，只有在執行完成且可下載構件時，才會觸發這項事件。
- Jobs：選取要監控的 dbt Cloud 部署工作。
- 「Endpoint」(端點)：輸入您執行的服務 HTTPS 網址 (例如 Cloud Run 服務或 Cloud Run 函式)。
儲存 dbt Cloud 顯示的 Webhook 密鑰權杖。您的服務會使用這組密鑰驗證 Authorization 標頭，其中包含要求主體的 HMAC-SHA256 簽章。
在服務中，從 JSON 酬載讀取 data.runId，使用 Administrative API 下載執行的構件 (如前所述)，然後執行 gcloud alpha dataplex dbt metadata-jobs create 指令。

實作 Webhook 處理常式時，請考量下列事項：

dbt Cloud 最多會等待 10 秒，由於中繼資料匯入作業需要幾分鐘的時間，請先傳回 HTTP 回應，並在背景執行匯入作業 (例如做為 Cloud Run 工作，或使用 --async 旗標)。
job.run.completed 也會針對失敗的執行作業觸發，因此系統仍會匯入測試失敗的執行作業。請勿訂閱 job.run.errored，因為這可能會在執行作業的構件可用之前觸發。

如要進一步瞭解 Webhook 酬載和簽章驗證，請參閱 dbt 說明文件中的「Webhooks for your jobs」(工作的 Webhook)。

設定 dbt 連線能力

如要建立 dbt 連線，您必須先執行適當的 dbt 指令，產生中繼資料構件。JSON 檔案儲存完畢且可供存取後，匯入程序會執行下列動作：

讀取輸入構件：從輸入位置 (--artifacts-path 中指定的本機目錄或 Cloud Storage URI)，讀取 dbt Core 和 MetricFlow 產生的 JSON 構件。
轉換中繼資料：將內容轉換為 Knowledge Catalog 中繼資料匯入格式 (dbt_metadata.jsonl)。
上傳至暫存區：將轉換後的中繼資料匯入檔案，上傳至 --storage-uri 中指定的輸出暫存 Cloud Storage 位置。
觸發匯入工作：觸發 Knowledge Catalog 中繼資料匯入工作，指示 Knowledge Catalog 服務代理從 --storage-uri 讀取暫存中繼資料，並擷取至 Knowledge Catalog 資源。

控制台

前往 Google Cloud 控制台的「Knowledge Catalog」「Connectors」(連接器) 頁面。

前往「Connectors」(連接器) 頁面
按一下「新增連線」。
在「Connectors」(連接器) 清單中，選取「dbt Core and MetricFlow」資訊卡。

注意： 由於 dbt Core 中繼資料擷取作業需要先將用戶端 dbt 構件 JSON 檔案 (manifest.json、catalog.json、run_results.json、sources.json) 轉換為 Knowledge Catalog 匯入格式，才能擷取，因此選取這張資訊卡後，系統會將您導向 CLI 或 API 操作說明。
如要查看匯入的 dbt 資產，請前往「Search」(搜尋) 頁面，或查看目的地「Entry groups」(項目群組) 頁面。

gcloud

如要建立 dbt 中繼資料工作，請完成下列步驟：

確認 dbt 中繼資料構件檔案儲存在本機或輸入 Cloud Storage bucket。
請務必設定輸出暫存 Cloud Storage bucket，並為呼叫端和 Knowledge Catalog 服務代理授予適當權限。
從 Cloud Shell、本機終端機或自動化工作流程工具執行 gcloud 指令：
```
gcloud alpha dataplex dbt metadata-jobs create my-dbt-import \
    --project=my-project \
    --location=us-central1 \
    --artifacts-path=. \
    --entry-group=dbt-metadata-ingestion \
    --storage-uri=gs://my-bucket/dbt-imports/
```
必要旗標
- --storage-uri=STORAGE_URI：(輸出/暫存) Cloud Storage URI 前置字串 (gs://bucket/path/)，轉換後的 JSONL 會上傳至此，匯入工作也會在擷取期間從此讀取。呼叫端必須具備寫入權限 (roles/storage.objectCreator 或 roles/storage.objectAdmin)，Knowledge Catalog 服務代理則須具備讀取權限 (roles/storage.objectViewer)。
選用旗標
- --artifacts-path=ARTIFACTS_PATH：(輸入) 來源 dbt 構件的路徑。可以是本機目錄路徑 (例如 . 或 ./target)，也可以是 Cloud Storage URI 前置字串 (例如 gs://my-bucket/dbt-artifacts/)。可以指向 dbt 專案根目錄 (系統會自動偵測 target/ 子目錄)，或直接指向含有 manifest.json 的目錄。預設為 .。如果提供 Cloud Storage URI，呼叫端必須具備輸入 bucket 的讀取權限 (roles/storage.objectViewer 或 roles/storage.objectAdmin)。
- --async：立即返回，不等待執行中的作業完成。
- --entry-group=ENTRY_GROUP：接收 dbt 項目的項目群組短 ID。必須已存在於專案和位置 (預設為 dbt-metadata-ingestion)。
- --aspects-only：僅更新這項 dbt 執行作業觀測到的中繼資料，其餘項目群組則保持不變。不會建立、刪除或重新設定父項，也不會發出項目連結，而 dbt 構件未出現在本次執行的切面，則會保留先前執行時提供的值。這項功能適用於例行、重複的擷取作業。請參閱「重新執行擷取作業」。
- --include-entry-links：發出 dbt 關係的項目連結。這個選項預設為啟用。如要停用，請使用 --no-include-entry-links。這個指令會發出下列項目連結類型：
  - reference：一項資源依賴、描述或使用另一項資源。這包括節點之間的 dbt 依附元件、測試和測試的資源、語意模型或指標和建構的資源、節點和呼叫的專案巨集，以及節點和具體化的 BigQuery 資料表。
  - schema-join：由 dbt relationships 測試宣告的可彙整資料欄。
- --skip-bigquery-link：略過 reference 連結 (dbt 節點 → 實體 BigQuery 資料表)。根據預設，如果實體化 dbt 節點 (模型、種子、快照) 的 BigQuery 資料集位於匯入位置 (--location)，系統會為每個節點發出 reference 連結。dbt 來源不會收到 BigQuery 資料表的 reference 連結。項目連結只能參照同一區域中的 @bigquery 項目，因此系統會自動略過其他區域中的資料集。為判斷每個資料集的區域，指令會呼叫 BigQuery API，因此呼叫端需要具備這些資料集的 bigquery.datasets.get 權限。如果沒有這項權限，指令就無法略過其他區域的資料集，也無法解析這些資料集的連結。如果 BigQuery 資料表未編入 Knowledge Catalog，請使用 --skip-bigquery-link。
- --validate-only：建構並上傳 JSON，然後驗證中繼資料工作，但不要實際擷取。
確認您收到「Created」狀態。

REST

如要使用 REST API 匯入 dbt 中繼資料，請按照下列步驟操作：

生成 dbt 構件，並轉換為 Knowledge Catalog JSON 匯入檔案 (dbt_metadata.jsonl)。
將轉換後的檔案上傳至 Cloud Storage 暫存 bucket (gs://BUCKET_NAME/PATH/)。

呼叫 projects.locations.metadataJobs.create 方法：

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/metadataJobs?metadataJobId=JOB_ID \
    -d '{
      "type": "IMPORT",
      "importSpec": {
        "sourceStorageUri": "gs://BUCKET_NAME/PATH/",
        "entrySyncMode": "FULL",
        "aspectSyncMode": "INCREMENTAL",
        "scope": {
          "entryGroups": [
            "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP"
          ],
          "entryTypes": [
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-project",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-model",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-source",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-seed",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-snapshot",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-group",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-exposure",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-metric",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-macro",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-semantic-model",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-saved-query",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-test"
          ],
          "aspectTypes": [
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-node",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-project",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-model",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-source",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-seed",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-snapshot",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-group",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-exposure",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-metric",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-macro",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-semantic-model",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-saved-query",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-data-quality",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-model-contracts"
          ]
        }
      }
    }'

更改下列內容：

PROJECT_ID：項目群組所在的 Google Cloud 專案 ID。
LOCATION：項目群組的區域 (例如 us-central1)。
JOB_ID：中繼資料工作的專屬 ID。
BUCKET_NAME/PATH：上傳 dbt_metadata.jsonl 的 Cloud Storage URI 前置字元。
ENTRY_GROUP：目的地項目群組的簡短 ID。

如要追蹤匯入工作的狀態，請使用 projects.locations.metadataJobs.get 方法：

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/metadataJobs/JOB_ID

建立工作後，Knowledge Catalog 會根據您的設定排定首次執行時間，您也可以手動啟動。

重新執行擷取作業

初次匯入後，大多數執行作業只需重新整理現有資源的中繼資料。請使用 --aspects-only 執行這些作業。這項工作只會更新 dbt 執行作業觀察到的內容，並保留項目群組中的其他內容，因此可以安全地重複執行、按照任何排程執行，以及從多個工作執行。

當項目組合變更時，執行完整擷取 (省略 --aspects-only)：

首次擷取至項目群組。
新增、重新命名或刪除 dbt 資源。
項目的顯示名稱、說明或標籤有所變更。
項目階層會變更。
dbt 依附元件變更，例如新增或移除 ref()、source()、測試或巨集呼叫。--aspects-only 執行作業不會建立或更新項目連結。
變更 --include-entry-links 或 --skip-bigquery-link。

完整執行會從磁碟上的構件重寫每個項目的必要層面，因此請從管道可產生的完整構件集執行。

執行 --aspects-only 進行例行重新整理：

管道執行任何 dbt 指令後：dbt build、dbt test、dbt source freshness，或 --select 縮小範圍的重建作業。
新增、移除、重新輸入或重新描述資料欄。
模型 SQL 已變更，執行作業也寫入 catalog.json。
新測試結果或來源更新。

--aspects-only可以新增及重新整理中繼資料，但無法移除。

搜尋及查看 dbt 中繼資料

控制台

前往 Google Cloud 控制台的「Knowledge Catalog」「Search」(搜尋) 頁面。

前往「Search」(搜尋) 頁面
在「Filters」(篩選器) 面板中，篩選 dbt 資產：
- 在「System」(系統) 部分，選取「Imported Context」(匯入的情境)。
- 在隨即顯示的「Managed Connectors」子節中，選取「dbt」。
在搜尋欄位中，使用關鍵字或自然語言搜尋輸入查詢。舉例來說，如要使用關鍵字搜尋查看所有 dbt 資產，請輸入 system=DBT 或 system=DBT AND type=dbt-model。
在搜尋結果中，點選任一 dbt 資產，開啟其項目詳細資料頁面，查看結構定義、歷程和技術層面。

gcloud

如要在專案中搜尋 dbt 項目，請使用 gcloud dataplex entries search 指令：

gcloud dataplex entries search 'system=DBT' \
    --project=PROJECT_ID

如要依特定 dbt 項目類型 (例如模型或來源) 篩選：

gcloud dataplex entries search 'system=DBT AND type=dbt-model' \
    --project=PROJECT_ID

如要查看特定 dbt 項目的完整詳細資料和面向，請使用 gcloud dataplex entries lookup 指令：
```
gcloud dataplex entries lookup ENTRY_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --entry-group=ENTRY_GROUP \
    --view=FULL
```
更改下列內容：
- PROJECT_ID：您的 Google Cloud 專案 ID。
- LOCATION：項目群組的位置 (例如 us-central1)。
- ENTRY_GROUP：目的地項目群組的簡短 ID (例如 dbt-metadata-ingestion)。
- ENTRY_ID：dbt 項目的簡短 ID 或相對資源名稱。

REST

如要搜尋 dbt 項目，請呼叫 projects.locations:searchEntries 方法：

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/global:searchEntries \
    -d '{
      "query": "system=DBT"
    }'

如要依特定 dbt 資源類型篩選：

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/global:searchEntries \
    -d '{
      "query": "system=DBT AND type=dbt-model"
    }'

如要擷取特定項目的完整中繼資料詳細資料和切面，請呼叫 projects.locations.entryGroups.entries.get 方法：

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP/entries/ENTRY_ID?view=FULL

如要擷取特定 dbt 資源的 LLM 情境，請使用 projects.locations:lookupContext API：

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:lookupContext \
    -d '{
      "resources": [
        "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP/entries/ENTRY_ID"
      ]
    }'

更改下列內容：

PROJECT_ID：您的 Google Cloud 專案 ID。
LOCATION：項目群組的位置 (例如 us-central1)。
ENTRY_GROUP：目的地項目群組的簡短 ID (例如 dbt-metadata-ingestion)。
ENTRY_ID：dbt 項目的簡短 ID 或相關資源名稱。

如要列出 dbt 項目的項目連結，請呼叫 projects.locations:lookupEntryLinks 方法。舉例來說，如要擷取 dbt 模型具體化的 BigQuery 資料表，請執行下列操作：

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:lookupEntryLinks?entry=ENTRY_NAME&entryMode=SOURCE&entryLinkTypes=projects/dataplex-types/locations/global/entryLinkTypes/reference"

ENTRY_NAME 是 dbt 項目的完整資源名稱。結果會分頁顯示，每頁最多 10 個連結。

如要進一步瞭解如何搜尋資源，請參閱「在 Knowledge Catalog 搜尋資源」。如要進一步瞭解查詢運算式和篩選器，請參閱「Knowledge Catalog 的搜尋語法」。

後續步驟

瞭解如何管理連接器工作。

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

匯入的中繼資料和用途

限制

事前準備

IAM 角色和權限

啟用 API

dbt 必要條件

瞭解 Cloud Storage 角色

從 dbt Cloud 執行作業匯入中繼資料

設定 dbt Cloud 工作

從 dbt Google Cloud 控制台下載構件

使用 dbt 平台 CLI 下載構件

使用 dbt Administrative API 下載構件

擷取執行作業 ID

使用 Webhook 觸發匯入作業

設定 dbt 連線能力

控制台

gcloud

必要旗標

選用旗標

REST

重新執行擷取作業

搜尋及查看 dbt 中繼資料

控制台

gcloud

REST

後續步驟

從 dbt Core 匯入中繼資料