使用 Knowledge Catalog 管理 Dataform 的中繼資料和資料歷程

Knowledge Catalog 可讓您儲存及管理中繼資料。Dataform 存放區預設可在 Knowledge Catalog 中使用，不需額外設定。Knowledge Catalog 會自動從 Dataform 存放區擷取下列中繼資料：

• 資料資產名稱

• 資料資產父項

• 資料資產位置

• 資料資產類型

• 對應的 Google Cloud 專案

• 第三方存放區來源

• 服務帳戶

事前準備

1. 在 Google Cloud 控制台的專案選取器頁面中，選取或建立 Google Cloud 專案。

   選取或建立專案所需的角色

   • 選取專案：選取專案時，不需具備特定 IAM 角色，只要您在專案中獲派角色，即可選取該專案。
   • 建立專案：如要建立專案，您必須具備專案建立者角色 (roles/resourcemanager.projectCreator)，其中包含 resourcemanager.projects.create 權限。瞭解如何授予角色。

   前往專案選取器

2. 啟用 Dataplex API 和 Data Lineage API (如果尚未啟用)。

   啟用 API 所需的角色

   如要啟用 API，您必須具備 serviceusage.services.enable 權限。如果您建立了專案，可能已透過擁有者角色 (roles/owner) 取得這項權限。否則，您可以透過 Service Usage 管理員角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。

   啟用 API

3. 確認您具備必要的 Identity and Access Management (IAM) 權限。

必要的角色

如要管理 Dataform 存放區，並在 Knowledge Catalog 中查看資料歷程，您必須具備預先定義的 Dataform 角色，才能存取 Dataform 資源，以及必要的 Knowledge Catalog 角色。

下表列出各主體記錄及查看 Dataform 資料歷程所需的角色：

資料歷程事件產生者角色具備 datalineage.locations.processOpenLineageMessage 權限，可記錄歷程。

在 Knowledge Catalog 管理中繼資料

Knowledge Catalog 會將 Dataform 存放區記錄為項目，並包含下列項目值：

系統項目群組

Dataform 存放區的系統項目群組為 @dataform。如要查看 Knowledge Catalog 中存放區項目的詳細資料，請查看 dataform 系統項目群組。如要瞭解如何查看項目群組中所有項目的清單，請參閱 Knowledge Catalog 說明文件中的「查看項目群組的詳細資料」。

系統項目類型

Dataform 存放區的系統項目類型為 dataform-repository。如要查看 Dataform 存放區的詳細資料，您必須查看 dataform-repository 系統項目類型。如要瞭解如何查看所選項目類型的詳細資料，請參閱 Knowledge Catalog 說明文件中的「查看項目類型的詳細資料」。如要瞭解如何查看所選項目的詳細資料，請參閱 Knowledge Catalog 說明文件中的「查看項目詳細資料」。

搜尋資產

如要瞭解如何在 Knowledge Catalog 搜尋資料資產，請參閱 Knowledge Catalog 說明文件中的「在 Knowledge Catalog 搜尋資料資產」。

為存放區加上註解

如要為 Knowledge Catalog 中的 Dataform 存放區提供額外背景資訊，您可以使用切面為 Dataform 項目加上註解。

Dataform 存放區的系統切面類型為 dataform-repository。

如要瞭解如何使用切面為項目加上註解，請參閱 Knowledge Catalog 說明文件中的「管理切面並充實中繼資料」。

在 Knowledge Catalog 追蹤資料歷程

Dataform 會針對在 Dataform 工作流程和 BigQuery 管道中執行的動作，向 Knowledge Catalog 回報資料歷程。針對每項執行的動作，Knowledge Catalog 和 BigQuery 中的歷程圖會顯示動作讀取的資料表與寫入的資料表之間的 Dataform 程序。您不需要變更 SQLX 檔案，即可回報歷程。

您可以使用 Dataform 資料歷程執行下列工作：

• 影響分析：在變更資料表前，找出所有下游動作和資料表。

• 根本原因分析：追蹤不正確的資料，找出寫入該資料的操作和工作流程叫用。

• 治理：顯示資料在專案之間的流動方式，以及移動資料的管道。

• 端對端歷程：在單一圖表中查看 Dataform 歷程，以及 BigQuery、Managed Service for Apache Airflow、Managed Service for Apache Spark 和 Dataflow 的歷程。

資料歷程的運作方式

動作開始時，Dataform 會將 OpenLineage START 事件傳送至 Data Lineage API。動作結束時，Dataform 會傳送 COMPLETE、FAIL 或 ABORT 事件。每項 Dataform 動作都會在 Knowledge Catalog 中顯示為來源類型為 BIGQUERY_PIPELINES 的程序，而每次執行動作都會顯示為該程序的執行作業。

下表說明哪些 Dataform 動作類型會回報歷程：

回報歷程絕不會導致工作流程叫用失敗。如果 Data Lineage API 已停用、缺少權限或超出配額，Dataform 會略過歷程報告，並繼續叫用工作流程，不會進行任何變更。

Dataform 會將歷程寫入各項動作的 BigQuery 處理位置區域端點。如果區域端點無法使用，Dataform 會將歷程寫入全域端點。

Dataform 工作流程如何對應至資料歷程

下表說明 Dataform 執行實體如何對應至 Knowledge Catalog 資料歷程資訊模型：

設定資料歷程

如要設定 Dataform 回報報表資料歷程，請按照下列步驟操作：

1. 在包含 Dataform 存放區的專案，以及使用者查看歷程的專案中，啟用 Data Lineage API (datalineage.googleapis.com)。

2. 在包含存放區的專案中，將資料歷程事件產生者角色 (roles/datalineage.producer) 授予執行工作流程的身分：

   • 如果存放區、版本設定或工作流程設定使用自訂服務帳戶，請將角色授予自訂服務帳戶。

   • 如未設定自訂服務帳戶，請將角色授予 Dataform 服務代理 (service-PROJECT_NUMBER@gcp-sa-dataform.iam.gserviceaccount.com)。

使用 Google 帳戶的使用者憑證執行的工作流程叫用，不會回報歷程。

啟用或停用資料歷程

在初步推出期間，資料歷程報表功能為選擇加入。

如要控管存放區或 BigQuery 管道的資料歷程報告，請在 workflow_settings.yaml 檔案中設定 lineage.enabled 屬性：

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

   前往 Dataform

2. 選取存放區，然後選取開發工作區。

3. 在「檔案」窗格中，開啟 workflow_settings.yaml 檔案。

4. 如要啟用資料歷程報表，請新增下列 lineage 區塊：

   lineage:
     enabled: true
   

   如要在預設啟用歷程後，選擇不讓存放區產生資料歷程報表，請將 enabled 設為 false：

   lineage:
     enabled: false
   

5. 修訂並推送變更至存放區。

如要停止整個專案的資料歷程回報功能，請在專案中停用 Data Lineage API。停用 API 也會停止專案中其他服務的資料歷程報告。

查看資料歷程

如要查看 Dataform 動作產生的資料表歷程，請按照下列步驟操作：

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

   前往「BigQuery」

2. 在「Explorer」窗格中展開專案和資料集，然後選取 Dataform 動作產生的資料表。

3. 點選「歷程」分頁標籤。

4. 如要查看動作、存放區和執行作業，請選取 Dataform 程序節點。

5. 如要在 Dataform 中開啟存放區，請按一下「Open in Dataform」(在 Dataform 中開啟)。

如要進一步瞭解如何瀏覽歷程圖，請參閱「在 Knowledge Catalog 中查看資料歷程」。

透過 Dataform CLI 回報資料歷程

如要從本機或 CI 執行的 Dataform CLI 回報資料歷程，請在 workflow_settings.yaml 中設定 lineage.enabled: true，或執行下列指令：

dataform run --emit-lineage

--emit-lineage 和 --no-emit-lineage 旗標會覆寫單次執行的 lineage.enabled 設定。

Dataform CLI 會使用應用程式預設憑證，並在每個輸出資料表的專案中記錄歷程。在這些專案中，啟用 Data Lineage API，並將 Data Lineage 事件產生者角色 (roles/datalineage.producer) 授予憑證。CLI 會將歷程訊息寫入 stderr，並加上 [lineage] 前置字串。

如要進一步瞭解如何透過 CLI 回報歷程，請參閱 GitHub 上的 Dataform CLI 參考資料。

排解資料歷程問題

下表說明常見的資料歷程問題和修正方式：

在工作流程叫用中，發生第一個權限或 API 錯誤後，Dataform 會停止回報該工作流程叫用其餘部分的歷程。下次叫用工作流程時，系統會再次嘗試回報歷程。

向支援團隊回報資料歷程問題時，請提供工作流程叫用 ID、專案 ID 和區域。

查看工作流程叫用的歷程記錄

在 Cloud Logging 中，Dataform 會將歷程記錄項目寫入 dataform.googleapis.com/lineage_emission 記錄。每個項目都包含 workflowInvocationId、actionTarget 和 eventType 欄位。

如要查看工作流程叫用的歷程記錄，請按照下列步驟操作：

1. 在 Google Cloud 控制台中，開啟工作流程叫用的詳細資料頁面。

2. 按一下「查看記錄」。

   「Logging」隨即開啟，並顯示依 jsonPayload.workflowInvocationId 篩選的工作流程叫用記錄。

每個歷程記錄項目的 outcome 欄位會包含下列其中一個值：

• SUCCEEDED：Data Lineage API 已接受事件。這些項目的嚴重程度為 DEBUG，eventType 則為 START、COMPLETE、FAIL 或 ABORT。

• SKIPPED：Dataform 略過歷程報告。這些項目的嚴重性為 INFO，且在工作流程叫用中，每個原因都會記錄一次。skipReason 欄位為 API_DISABLED、PERMISSION_DENIED、EUC_UNSUPPORTED 或 AUTHORITY_UNAVAILABLE，且 errorMessage 欄位包含修復步驟。

• FAILED：重試後仍無法回報歷程。這些項目的嚴重程度為 WARNING，並包含 errorCode 和 errorMessage 欄位。

如要在 Logs Explorer 中篩選略過或失敗的歷程報告，請執行下列查詢：

log_id("dataform.googleapis.com/lineage_emission")
jsonPayload.outcome=("SKIPPED" OR "FAILED")

Dataform CLI 的資料歷程訊息

Dataform CLI 會將下列歷程訊息寫入 stderr：

• skip_reason=workflow_opt_out：lineage.enabled 設為 false。

• skip_reason=invocation_override：使用 --no-emit-lineage 或 --emit-lineage=false 執行這項作業時，歷程記錄回報功能已關閉。

• skip_reason=dry_run：模擬測試不會回報歷程。

• skip_reason=api_disabled：未啟用 Data Lineage API。CLI 在這次執行作業中不會再傳送譜系要求。

• skip_reason=permission_denied：憑證不具備資料歷程事件產生者角色 (roles/datalineage.producer)。CLI 在這次執行作業中不會傳送更多歷程要求。

• Failed to emit lineage for action ...：一項動作的歷程記錄回報失敗。其他動作的歷程記錄報表會繼續執行。

限制

在 Knowledge Catalog 中管理 Dataform 存放區及追蹤資料歷程時，須遵守下列限制：

• Knowledge Catalog 僅提供存放區層級和工作流程層級的項目。Dataform 中的個別檔案層級程式碼資產 (例如 SQLX 定義檔案) 不會編目為獨立項目。

• Dataform 只會回報資料表層級歷程。不會回報資料欄層級歷程。

• 宣告、筆記本和 SQL 單元測試不會回報歷程。宣告只會做為其他動作的輸入內容。不含 hasOutput: true 的作業只會回報程序和執行作業，不會提供資料表之間的歷程連結。

• 使用 Google 帳戶的使用者憑證執行的工作流程叫用不會回報歷程。如要回報歷程，請使用自訂服務帳戶。

• 資料歷程報表受限於 Data Lineage API 配額，每個專案、身分和區域都有寫入次數限制。標準級別的配額約為每分鐘 1,000 次動作。

位置

您可以使用 Knowledge Catalog，管理所有 Dataform 位置的 Dataform 存放區。

配額

在 Knowledge Catalog 中管理 Dataform 存放區時，須遵守 Knowledge Catalog 配額和限制。

定價

在 Knowledge Catalog 中管理 Dataform 存放區，須遵守 Knowledge Catalog 定價。

資料歷程擷取作業會依 Knowledge Catalog Premium Processing SKU 計費，且只有寫入資料表對資料表歷程連結的事件才會計費。資料歷程儲存空間費用會依中繼資料儲存空間 SKU 計費。如要控管資料歷程費用，請在 workflow_settings.yaml 中停用工作流程，或停用 Data Lineage API。

後續步驟

• 如要進一步瞭解 Knowledge Catalog，請參閱 Knowledge Catalog 說明文件中的「Knowledge Catalog 總覽」。