從 Databricks Unity Catalog 匯入中繼資料

使用 Knowledge Catalog (原稱 Dataplex Universal Catalog) 連接器，直接將 Databricks Unity Catalog 的中繼資料匯入 Google Cloud，打破資料孤島，避免在工具之間切換。

這個連接器支援託管於Google Cloud、Microsoft Azure 或 Amazon Web Services (AWS) 的 Databricks Unity Catalog 執行個體。

下表列出 Databricks Unity Catalog 連接器擷取的中繼資料：

類別	擷取的中繼資料
技術	Metastore 目錄 結構定義 資料表 (代管 Delta、外部、串流、線上、特徵、Apache Iceberg REST 目錄 (IRC)) 檢視表 (標準、具體化) 磁碟區 函式和程序
可使用	用量指標 (30 天和 90 天內的檢視次數；30 天內的讀取次數、寫入次數、常用使用者和常用彙整資料表) 主鍵和外鍵
業務	標記 (物件、資料分類) 資料品質 (資料品質監控的異常偵測結果，以及 Lakehouse 監控的資料偏移和自訂指標) 資料剖析 (來自 Lakehouse Monitoring) 彙整和關係 資料表和檢視表的擁有者、建立時間和上次修改時間
語義	指標檢視畫面 (維度、測量指標、關係對應、認證) 指標檢視畫面擁有者 指標檢視畫面用量 (30 天和 90 天內的檢視次數；30 天內的讀取、寫入、頻繁使用者和經常彙整的資料表) 顯示名稱 (來自指標檢視畫面) 同義詞 (來自指標檢視畫面) Markdown 註解

限制

Databricks Unity Catalog 連接器有下列限制：

• 不支援歷程。
• 整合功能 (Genie API) 不支援語意標記和組織詞彙。
• 連接器會匯入 Iceberg 資料表的中繼資料，但不會自動將匯入的項目連結至對應的 Google Cloud Lakehouse Databricks Unity Catalog Iceberg REST Catalog (IRC) 項目。

事前準備

從 Databricks Unity Catalog 匯入中繼資料前，請先完成下列工作：

1. 授予必要的角色和權限。
2. 啟用 Dataplex API 和 BigQuery 資料移轉服務 API。
3. 符合 Databricks Unity Catalog 必要條件。
4. 符合網路必要條件。

IAM 角色和權限

如要建立及管理 Knowledge Catalog 連接器工作，您需要具備 Knowledge Catalog 和 BigQuery 資料移轉服務權限的 Identity and Access Management (IAM) 角色。

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

• 如要建立及管理項目群組，請在專案中具備 Dataplex Catalog 管理員 (roles/dataplex.catalogAdmin)、Dataplex Catalog 編輯者 (roles/dataplex.catalogEditor) 或 Dataplex 項目群組擁有者 (roles/dataplex.entryGroupOwner) 角色。
• 如要查看 Databricks Unity Catalog 中繼資料，請在專案中啟用 Dataplex Catalog 檢視者 (roles/dataplex.catalogViewer)。
• 如要建立及管理 BigQuery 資料移轉服務移轉工作，請在專案中指派 BigQuery 管理員 (roles/bigquery.admin) 角色。
• 如要在 Cloud Logging 查看記錄，請在專案中具備記錄檢視者 (roles/logging.viewer) 角色。

您也必須將下列兩項角色授予 BigQuery 資料移轉服務代理程式 ([e-mail])：

• Dataplex 項目群組匯入者 (roles/dataplex.entryGroupImporter)，適用於目的地項目群組或包含該群組的專案。這個角色可讓服務代理將中繼資料匯入項目群組 (dataplex.entryGroups.import)。

• Dataplex 項目和 EntryLink 擁有者 (roles/dataplex.entryOwner)，適用於包含目的地項目群組的專案。具備這個角色，服務代理就能匯入用量、業務和資料品質中繼資料，以及項目連結。包含下列權限：

  • dataplex.entryGroups.useDataProfileAspect
  • dataplex.entryGroups.useDataQualityScorecardAspect
  • dataplex.entryGroups.useManagedConnectorTypes
  • dataplex.entryGroups.useReferenceEntryLink
  • dataplex.entryGroups.useSchemaAspect
  • dataplex.entryGroups.useSchemaJoinAspect
  • dataplex.entryGroups.useSchemaJoinEntryLink
  • dataplex.entryGroups.useUsageAspect
  • dataplex.entryLinks.reference

  請在專案 (而非僅在項目群組) 授予這個角色，因為匯入作業會檢查專案的 dataplex.entryLinks.reference 權限。如果服務代理在專案中沒有這項權限，移轉作業就會失敗，並顯示 Permission 'dataplex.entryLinks.reference' denied 等錯誤，且不會匯入任何中繼資料。

您也可以不授予這兩個角色，改為在包含目的地項目群組的專案中，授予 Dataplex 項目群組擁有者 (roles/dataplex.entryGroupOwner) 角色。這個角色包含上述兩個角色的權限，並可讓服務代理建立、刪除及管理專案中所有項目群組的存取權。

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

啟用 API

啟用 Dataplex API 和 BigQuery 資料移轉服務 API。

啟用 API

Databricks Unity Catalog 必要條件

Databricks Unity Catalog 連接器使用的服務主體，必須在 Databricks Unity Catalog 中具備下列權限：

• 連接器使用的 Databricks SQL 倉儲具備 Can use 權限。
• 目標目錄的 BROWSE 權限，或目標目錄、結構定義和資料表或檢視表的 USE CATALOG、USE SCHEMA 和 SELECT。
• system 目錄上的 USE CATALOG，以及下列系統結構定義上的 USE SCHEMA 和 SELECT：
  • system.information_schema：必須具備這項權限，才能讀取目錄、結構定義、資料表、資料欄、磁碟區、常式、限制和標記。
  • system.access 和 system.query：選用，匯入用量指標、用量深入分析和查詢記錄彙整時必須提供。
  • system.data_quality_monitoring：選用，匯入異常偵測結果時必須提供。
• 選用：Lakehouse Monitoring 輸出資料表 (TABLE_NAME_profile_metrics 和 TABLE_NAME_drift_metrics) 的 USE CATALOG、USE SCHEMA 和 SELECT，用於匯入資料剖析和偏移指標。

如要對遠端 Databricks 目錄執行 SQL 查詢或 Spark 工作，請參閱「設定 Databricks Unity Catalog 的跨雲端連線」。

網路事前準備

如要讓 BigQuery 資料移轉服務透過私人網路中的私人 IP 位址，安全連線至外部資料庫或第三方雲端資料來源，請透過 Private Service Connect 設定網路連結。

如果您使用公開 IP 位址連線至地端部署環境或雲端託管執行個體，則不需要網路連結。

注意： 不支援具有網路連結的私人網域。

設定 Databricks Unity Catalog 連接器

使用 Google Cloud 控制台或 REST API 設定 Databricks Unity Catalog 連接器。

控制台

1. 前往 Google Cloud 控制台的「Knowledge Catalog」頁面。

   前往 Knowledge Catalog

2. 在導覽選單的「Manage」(管理) 部分，依序點選「Connectors」(連接器) 和「Add connection」(新增連線)。

3. 在「Connectors」(連接器) 清單中，選取「Databricks Unity Catalog」卡片。

4. 在「Data source details」(資料來源詳細資料) 部分，提供 Databricks Unity Catalog 執行個體的連線詳細資料：

   • 在「Network attachment」(網路連結) 部分，視需要選取現有的網路連結，或建立一個。
   • 輸入「Workspace Host」(工作區主機)、「SQL Warehouse HTTP Path」(SQL 倉儲 HTTP 路徑)、「Client Id」(用戶端 ID) 和「Client Secret」(用戶端密鑰)。

   • 在「Databricks objects to transfer」部分，點選「Browse」(瀏覽)，選取要匯入 Knowledge Catalog 的 metastore、目錄、結構定義或個別物件 (資料表、檢視表、磁碟區、函式和程序)。選取 metastore、目錄或結構定義，即可匯入當中的所有物件。

     您也可以手動輸入物件，格式為 TYPE:METASTORE[/CATALOG[/SCHEMA[/OBJECT]]]，其中 TYPE 為 METASTORE、CATALOG、SCHEMA、TABLE、VIEW、VOLUME、FUNCTION 或 PROCEDURE (例如 SCHEMA:my_metastore/main/sales)。不支援名稱模式。

5. 在「Destination settings」(目的地設定) 部分：

   • 按一下「Browse」(瀏覽)，然後選取現有的 Knowledge Catalog 項目群組來儲存匯入的中繼資料，或按一下「Create new entry group」(建立新的項目群組)。
   • 選擇要立即或稍後設定項目群組的權限。如要允許使用者查看匯入的中繼資料，請設定項目群組的權限。如果您未在專案層級將 Dataplex Entry Group Importer (roles/dataplex.entryGroupImporter) 角色或 dataplex.entryGroups.import 權限授予 BigQuery 資料移轉服務代理，請在這個項目群組授予該角色或權限。您仍須在專案層級授予 Dataplex 項目和 EntryLink 擁有者 (roles/dataplex.entryOwner) 角色，因為系統會在專案層級檢查 dataplex.entryLinks.reference 權限。詳情請參閱「IAM 角色和權限」。

6. 在「Transfer config name」(移轉設定名稱) 部分，「Display name」(顯示名稱) 請輸入中繼資料匯入工作的名稱。

7. 在「Schedule options」(排程選項) 部分，設定中繼資料匯入工作的頻率。如果選取「On-demand」(隨選)，則只有在您手動觸發時，工作才會執行。

8. 選用步驟：在「Notification options」(通知選項) 部分，設定工作失敗時的電子郵件或 Pub/Sub 通知。

9. (選用) 在「Advanced options」(進階選項) 部分，設定加密設定。如果選取客戶自行管理的加密金鑰 (CMEK)，系統會使用該金鑰，加密在 Knowledge Catalog 中繼資料匯入工作開始前，暫存的所有資料。金鑰不會加密目的地 Knowledge Catalog 項目群組中的中繼資料。

10. 按一下 [儲存]。

REST

請使用 projects.locations.transferConfigs.create 方法。在 TransferConfig 資源中，設定下列欄位：

• 將 dataSourceId 欄位設為 "databricks_unity"。
• 在 metadataDestination 欄位中，填入 dataplexConfiguration.entryGroup目標 Knowledge Catalog 項目群組的資源路徑： projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID。
• 在「params」欄位中，設定下列參數：
  • connector.host (必要)：Databricks 工作區主機名稱 (例如 dbc-a1b2345c-d6e7.cloud.databricks.com)。
  • connector.httpPath (必要)：Databricks SQL 倉儲的 HTTP 路徑 (例如 /sql/1.0/warehouses/a1b2345c67890def)。
  • connector.authentication.oauth.clientId (必要)：Databricks OAuth 用戶端 ID。
  • connector.authentication.oauth.clientSecret (必要)：Databricks OAuth 用戶端密鑰。
  • connector.networkAttachment (選用)：網路連結，格式為 projects/PROJECT_ID/regions/REGION/networkAttachments/NETWORK_ATTACHMENT_ID。
  • assets (必要)：要匯入的 Databricks Unity Catalog 物件清單，格式為 TYPE:METASTORE[/CATALOG[/SCHEMA[/OBJECT]]]，例如 ["SCHEMA:my_metastore/main/sales"]。
• 選用：如要將 OAuth 憑證排除在移轉設定之外，請將憑證儲存在 Secret Manager：
  1. 將 connector.authentication.oauth.clientSecret (和 connector.authentication.oauth.clientId，如有需要) 設為密鑰版本資源名稱，格式為 projects/SECRET_PROJECT_ID/secrets/SECRET_ID/versions/VERSION_ID，然後將這些參數名稱新增至 paramConfig.secretManagerManagedParams 欄位。
  2. 將各個 Secret 的 Secret Manager Secret 存取者 (roles/secretmanager.secretAccessor) 角色，授予包含移轉設定 ([e-mail]) 的專案 BigQuery 資料移轉服務代理。Secret 可以位於其他專案。如果服務代理無法讀取 Secret，執行作業就會在啟動前失敗，並顯示 Failed to retrieve secret ... Permission 'secretmanager.versions.access' denied 等錯誤。BigQuery 資料移轉服務會在每次執行開始時讀取密鑰，因此如果您將 VERSION_ID 設為 latest，則從下次執行開始，系統會使用輪替的密鑰。

以下範例顯示 TransferConfig 要求主體：

{
  "displayName": "databricks-unity-metadata-import",
  "dataSourceId": "databricks_unity",
  "schedule": "every 24 hours",
  "params": {
    "connector.host": "dbc-a1b2345c-d6e7.cloud.databricks.com",
    "connector.httpPath": "/sql/1.0/warehouses/a1b2345c67890def",
    "connector.authentication.oauth.clientId": "CLIENT_ID",
    "connector.authentication.oauth.clientSecret": "CLIENT_SECRET",
    "assets": [
      "SCHEMA:my_metastore/main/sales"
    ]
  },
  "metadataDestination": {
    "dataplexConfiguration": {
      "entryGroup": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID"
    }
  }
}

工作會根據您的排程自動執行，您也可以手動觸發。

監控 Databricks Unity Catalog 連接器工作

使用Google Cloud 控制台或 REST API 監控 Databricks Unity Catalog 連接器工作。

控制台

1. 在 Google Cloud 控制台的「Connectors」(連接器) 頁面，按一下 Databricks Unity Catalog 移轉工作的「Display name」(顯示名稱)。
2. 在「執行記錄」分頁中，按一下「查看詳細資料」即可查看記錄。
3. 如要查看建立的項目，請按一下「Details」(詳細資料) 分頁標籤，然後點選「Metadata destination」(中繼資料目的地) 項目群組連結。

REST

• 如要列出移轉設定的執行作業並查看其狀態，請使用 projects.locations.transferConfigs.runs.list 方法。

• 每次執行時，系統都會透過 ID 為 dts-run-RUN_ID 的中繼資料匯入工作，將收集到的中繼資料匯入 Knowledge Catalog。如要查看匯入結果 (例如建立的項目數量)，請使用下列查詢，在 Logging 中篩選工作記錄：

  logName="projects/PROJECT_ID/logs/dataplex.googleapis.com%2Fmetadata_job"
  AND resource.labels.metadata_job_id="dts-run-RUN_ID"
  

• 如要查看匯入結果，但不使用 Logging，請對 projects/PROJECT_ID/locations/LOCATION/metadataJobs/dts-run-RUN_ID 呼叫 projects.locations.metadataJobs.get 方法。importResult 欄位會顯示已建立、更新、未變更和刪除的項目和項目連結數量。

注意： 即使移轉作業的中繼資料匯入工作以 SUCCEEDED_WITH_ERRORS 狀態結束，移轉作業仍可能顯示 SUCCEEDED 狀態，例如某個項目的其中一個面向過大而遭拒。查看中繼資料匯入工作的狀態和記錄，確認所有項目都已匯入。

搜尋及查看 Databricks Unity Catalog 中繼資料

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

   前往「Search」(搜尋) 頁面

2. 在「篩選器」面板中，使用「專案」、「系統」和「類型別名」部分，篩選 Databricks Unity Catalog 資產。如要篩選所有 Databricks Unity Catalog 中繼資料，請在「Systems」(系統) 區段中選取「Imported Context」(匯入的內容)，然後在「Managed Connectors」(代管連接器) 子區段中選取「Databricks Unity」。

3. 在搜尋欄位中，輸入關鍵字或自然語言搜尋查詢。舉例來說，如要透過關鍵字搜尋查看所有 Databricks Unity Catalog 資產，請輸入 system=DATABRICKS。

   如要進一步瞭解如何搜尋資源，請參閱「在 Knowledge Catalog 中搜尋資源」。如要進一步瞭解可在搜尋欄位中使用的運算式，請參閱「Knowledge Catalog 的搜尋語法」。

您也可以使用 LookupContext API，擷取特定 Databricks Unity Catalog 資源的 LLM 情境。詳情請參閱「擷取資料資產的背景資訊」。

後續步驟

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