從 Snowflake Horizon 匯入中繼資料

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

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

下表列出 Snowflake Horizon 連接器擷取的中繼資料：

類別	擷取的中繼資料
技術	Metastore (Snowflake 帳戶) 目錄 (資料庫) 結構定義 資料表 (包括暫時、外部、動態、互動式、混合和 Apache Iceberg 資料表) 和資料欄 檢視表 (標準、具體化和安全) 暫存區 (內部和外部)，匯入為檔案集 user-defined function (UDF) 和預存程序
可使用	用量指標 (30 天和 90 天內的檢視、讀取和寫入次數；30 天內經常使用的使用者和經常彙整的資料表) 主鍵和外鍵
業務	標記 (物件、資料欄和語意檢視成員標記) 資料品質 (資料指標函式預期、異常偵測和自動資料品質監控結果) 資料剖析 (資料指標函式測量結果和資料分類結果) 彙整和關係 (從查詢記錄推論、在語意檢視中宣告，以及檢視表與資料表之間的依附關係) 擁有者 (擁有角色)、建立時間和上次修改時間
語義	語意檢視表 (邏輯資料表、維度、事實、指標、關係、同義詞、範例值和自訂操作說明) 語意檢視表擁有者 語意檢視表使用情形 (30 天和 90 天內的檢視和讀取次數；30 天內經常使用的使用者和經常彙整的資料表)

限制

Snowflake Horizon 連接器有下列限制：

• 不支援歷程。
• 連接器會匯入 Iceberg 資料表的中繼資料，但不會自動將這些中繼資料連結至 Iceberg REST Catalog (IRC) 中的基礎實體資料表。
• 標記、資料品質和剖析結果、分類結果、查詢記錄彙整，以及讀取 ACCESS_HISTORY 的用量深入分析 (常用使用者和常用彙整資料表)，都需要 Snowflake Enterprise 版本以上。

事前準備

從 Snowflake Horizon 匯入中繼資料前，請先完成下列工作：

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

IAM 角色和權限

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

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

• 如要建立及管理項目群組，請在專案中具備 Dataplex Catalog 管理員 (roles/dataplex.catalogAdmin)、Dataplex Catalog 編輯者 (roles/dataplex.catalogEditor) 或 Dataplex 項目群組擁有者 (roles/dataplex.entryGroupOwner) 角色。
• 如要查看 Snowflake Horizon 中繼資料，請在專案中啟用 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

Snowflake Horizon 必要條件

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

連接器會以 Snowflake 使用者的身分登入 Snowflake，並使用金鑰組驗證，從 SNOWFLAKE.ACCOUNT_USAGE 結構定義讀取中繼資料。不支援密碼驗證。Snowflake 管理員 (例如具備 ACCOUNTADMIN 角色的使用者) 必須完成下列步驟：

1. 為連接器建立角色，並授予 ACCOUNT_USAGE 的存取權，以及執行中繼資料查詢的倉儲存取權：

   CREATE ROLE IF NOT EXISTS DATAPLEX_CATALOG_READER;
   GRANT IMPORTED PRIVILEGES ON DATABASE SNOWFLAKE
     TO ROLE DATAPLEX_CATALOG_READER;
   GRANT USAGE ON WAREHOUSE WAREHOUSE_NAME
     TO ROLE DATAPLEX_CATALOG_READER;
   

   將 WAREHOUSE_NAME 替換為執行中繼資料查詢的 Snowflake 倉儲名稱。

2. 為連接器建立服務使用者，或使用現有使用者，並授予角色：

   CREATE USER IF NOT EXISTS USERNAME
     TYPE = SERVICE
     DEFAULT_ROLE = DATAPLEX_CATALOG_READER
     DEFAULT_WAREHOUSE = WAREHOUSE_NAME;
   GRANT ROLE DATAPLEX_CATALOG_READER TO USER USERNAME;
   

   將 USERNAME 替換為連接器的 Snowflake 使用者名稱。

3. 產生 RSA 金鑰組，並將私密金鑰設為 PKCS#8 格式：

   openssl genrsa 2048 | openssl pkcs8 -topk8 -inform PEM -out rsa_key.p8 -nocrypt
   openssl rsa -in rsa_key.p8 -pubout -out rsa_key.pub
   

   如要加密私密金鑰，請將 -nocrypt 替換為 -v2 aes-256-cbc，並在設定連接器時提供密碼。設定連接器時需要提供私密金鑰檔案 (rsa_key.p8)，因此請妥善保管。

4. 將公開金鑰指派給 Snowflake 使用者：

   ALTER USER USERNAME SET RSA_PUBLIC_KEY='PUBLIC_KEY';
   

   將 PUBLIC_KEY 替換為 rsa_key.pub 的內容，但不包括 -----BEGIN PUBLIC KEY----- 和 -----END PUBLIC KEY----- 行。

5. 選用：如要匯入其他中繼資料，請授予連接器角色下列權限：

   • 資料剖析和資料品質結果：授予 SNOWFLAKE.DATA_QUALITY_MONITORING_VIEWER 應用程式角色：

     GRANT APPLICATION ROLE SNOWFLAKE.DATA_QUALITY_MONITORING_VIEWER
       TO ROLE DATAPLEX_CATALOG_READER;
     

     系統只會匯入該角色可查看的檢查資料品質結果，這需要資料庫和結構定義的 USAGE、資料表的 SELECT，以及自訂資料指標函式的 USAGE。

   • 主鍵和外鍵：授予資料庫和結構定義的 USAGE 權限，以及資料表的 SELECT 或 REFERENCES 權限。

   • 語意檢視表的範例值和自訂指令：授予語意檢視表的 REFERENCES。

如要找出設定連接器時輸入的帳戶 ID，請在 Snowflake 中執行下列查詢：

SELECT CURRENT_ORGANIZATION_NAME() || '-' || CURRENT_ACCOUNT_NAME();

注意： 連接器會從 ACCOUNT_USAGE 檢視畫面讀取中繼資料，延遲時間最多 3 小時，部分檢視畫面則最多 24 小時。您建立或變更的物件可能要到下次執行時才會顯示。

網路事前準備

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

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

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

設定 Snowflake Horizon 連接器

使用Google Cloud 控制台或 REST API 設定 Snowflake Horizon 連接器。

控制台

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

   前往 Knowledge Catalog

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

3. 在「連接器」清單中，選取「Snowflake Horizon」資訊卡。

4. 在「Data source details」(資料來源詳細資料) 部分，提供 Snowflake 帳戶的連線詳細資料：

   • 在「Network attachment」(網路連結) 部分，視需要選取現有的網路連結，或建立一個。
   • 在「Account Identifier」(帳戶 ID) 中，輸入不含 .snowflakecomputing.com 的 Snowflake 帳戶 ID (例如 myorg-myaccount)。您也可以輸入帳戶定位器，例如 xy12345.us-east-2.aws。
   • 在「Username」(使用者名稱) 部分，輸入您為金鑰組驗證設定的 Snowflake 使用者。
   • 在「Private Key」(私密金鑰) 中，輸入使用者的 PKCS#8 私密金鑰，例如 rsa_key.p8 檔案的內容。
   • 選用：如果私密金鑰已加密，請在「Private Key Passphrase」(私密金鑰通關密語) 中輸入通關密語。
   • 選用：在「Warehouse」(倉儲) 中，輸入執行中繼資料查詢的倉儲。如未指定，連接器會使用使用者的預設倉儲。
   • 選用：在「Role」(角色) 部分，輸入連接器使用的角色，例如 DATAPLEX_CATALOG_READER。如未指定角色，連接器會使用使用者的預設角色。

   • 在「Snowflake objects to transfer」(要移轉的 Snowflake 物件)，點選「Browse」(瀏覽)，選取要匯入的資料庫、結構定義或個別物件 (資料表、檢視表、語意檢視表、階段、函式和程序)。選取資料庫或結構定義，即可匯入其中的所有物件。函式和程序會與引數類型一併列出，例如 CALC(NUMBER, VARCHAR)。

     您也可以手動輸入物件，格式為 TYPE:ACCOUNT/DATABASE[/SCHEMA[/OBJECT]]，其中 TYPE 為 CATALOG (或 DATABASE)、SCHEMA、TABLE、VIEW、SEMANTIC-MODEL、FILESET、FUNCTION 或 PROCEDURE (例如 SCHEMA:myorg-myaccount/SALES/PUBLIC)。請以「瀏覽」中顯示的小寫 ORG_NAME-ACCOUNT_NAME 格式輸入 ACCOUNT。資料庫、結構定義和物件名稱會區分大小寫。不支援名稱模式。

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 欄位設為 "snowflake_horizon"。
• 在 metadataDestination 欄位中，填入 dataplexConfiguration.entryGroup目標 Knowledge Catalog 項目群組的資源路徑： projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID。
• 在「params」欄位中，設定下列參數：
  • connector.accountIdentifier (必要)：不含 .snowflakecomputing.com 的 Snowflake 帳戶 ID (例如 myorg-myaccount)，或帳戶定位器 (例如 xy12345.us-east-2.aws)。
  • connector.authentication.username (必要)：Snowflake 使用者。
  • connector.authentication.privateKey (必要)：使用者的私密金鑰，採用 PKCS#8 PEM 格式。
  • connector.authentication.privateKeyPassphrase (選用)：私密金鑰的通關密語 (如果金鑰已加密)。
  • connector.warehouse (選用)：執行中繼資料查詢的倉儲。如果省略這個參數，連接器會使用使用者的預設倉儲。
  • connector.role (選用)：連接器使用的角色。如果省略這個參數，連接器會使用使用者的預設角色。
  • connector.networkAttachment (選用)：網路連結，格式為 projects/PROJECT_ID/regions/REGION/networkAttachments/NETWORK_ATTACHMENT_ID。
  • assets (必要)：要匯入的 Snowflake 物件清單，格式為 TYPE:ACCOUNT/DATABASE[/SCHEMA[/OBJECT]]，例如 ["SCHEMA:myorg-myaccount/SALES/PUBLIC"]。
• 選用：如要將私密金鑰排除在移轉設定之外，請將金鑰儲存在 Secret Manager：
  1. 將 connector.authentication.privateKey (和 connector.authentication.privateKeyPassphrase，如有使用) 設為密鑰版本資源名稱，格式為 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": "snowflake-metadata-import",
  "dataSourceId": "snowflake_horizon",
  "schedule": "every 24 hours",
  "params": {
    "connector.accountIdentifier": "myorg-myaccount",
    "connector.authentication.username": "USERNAME",
    "connector.authentication.privateKey": "PRIVATE_KEY",
    "connector.warehouse": "WAREHOUSE_NAME",
    "connector.role": "DATAPLEX_CATALOG_READER",
    "assets": [
      "SCHEMA:myorg-myaccount/SALES/PUBLIC"
    ]
  },
  "metadataDestination": {
    "dataplexConfiguration": {
      "entryGroup": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID"
    }
  }
}

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

監控 Snowflake Horizon 連接器工作

使用Google Cloud 控制台或 REST API 監控 Snowflake Horizon 連接器工作。

控制台

1. 在 Google Cloud 控制台的「Connectors」(連接器) 頁面中，按一下 Snowflake Horizon 移轉工作的「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 狀態，例如某個項目的其中一個面向過大而遭拒。查看中繼資料匯入工作的狀態和記錄，確認所有項目都已匯入。

搜尋及查看 Snowflake Horizon 中繼資料

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

   前往「Search」(搜尋) 頁面

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

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

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

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

後續步驟

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