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

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

在 Google Cloud 系統中使用資料系譜

查看資料歷程，瞭解專案資源與建立這些資源的程序之間的關係。這些關係會顯示資料資產 (例如資料表和資料集) 如何透過查詢和管道等程序轉換。本指南說明如何在 Knowledge Catalog (舊稱 Dataplex Universal Catalog)、BigQuery 和 Vertex AI 中存取沿襲圖。

您可以在 Google Cloud 控制台中查看資料歷程詳細資料，也可以使用 Data Lineage API 擷取這些資料。

角色和權限

啟用 Data Lineage API 後，資料歷程就會自動追蹤歷程資訊。您不需要任何管理員或編輯者角色，即可擷取資料資產的沿革。

如要查看資料沿襲，您需要具備特定的 Identity and Access Management (IAM) 權限。系統會擷取多個專案的沿襲資訊，因此您需要多個專案的權限。

在 Knowledge Catalog、BigQuery 或 Vertex AI 中查看沿襲時，您必須具備在查看沿襲資訊的專案中查看沿襲資訊的權限。
查看其他專案中記錄的沿襲時：您需要有權限，才能查看記錄沿襲資訊的專案。

如要取得查看資料歷程所需的權限，請要求系統管理員授予您下列 IAM 角色：

資料歷程檢視者 (roles/datalineage.viewer) 在記錄歷程的專案和查看歷程的專案中
查看 BigQuery 資料表詳細資料：資料表儲存專案的 BigQuery 資料檢視者 (roles/bigquery.dataViewer)
查看 BigQuery 工作詳細資料：工作運算專案的 BigQuery 資源檢視器 (roles/bigquery.resourceViewer)
查看其他編目資產的詳細資料： Dataplex Catalog 檢視者 (roles/dataplex.catalogViewer) 在儲存目錄項目的專案中

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

這些預先定義的角色具備查看資料沿襲所需的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：

所需權限

如要查看資料沿襲，必須具備下列權限：

查看 BigQuery 資料表詳細資料： bigquery.tables.get - 資料表的儲存空間專案
查看 BigQuery 工作詳細資料： bigquery.jobs.get - 工作的運算專案

您或許還可透過自訂角色或其他預先定義的角色取得這些權限。

啟用 Data Lineage API 後，資料歷程就會自動追蹤歷程資訊。您不需要任何管理員或編輯者角色，即可擷取資料資產的沿革。

資料歷程檢視畫面類型

您可以透過圖表或清單查看沿革資訊。根據預設，歷程圖會顯示資料表層級的歷程。對於 BigQuery 和 Managed Service for Apache Spark 工作，您可以在圖表和清單檢視畫面中查看資料欄層級的沿襲。

可用的檢視畫面類型如下：

圖表檢視畫面：以互動式圖表顯示歷程，展開節點即可探索資料資產和資料欄之間的關係。
清單檢視畫面：以表格格式顯示歷程，提供資料表和資料欄層級歷程的簡化和詳細表示方式。您可以在這個檢視畫面中自訂欄，並匯出沿襲資料。

圖中的主要元素說明如下：

節點：代表資料實體。在資料表層級的檢視畫面中，節點會顯示資料表名稱和資料欄。在資料欄層級的檢視畫面中，每個節點代表特定資料表及其具有沿襲的資料欄。
邊緣：連接節點的線條，代表節點間發生的程序。邊緣可以顯示圖示或標籤，提供轉換的更多資訊：
- Icons：在表格層級檢視畫面中，邊緣會顯示圖示，代表轉換程序。手動探索圖表時，邊緣上的圖示代表程序的來源系統 (例如 BigQuery 或 Vertex AI)。如果涉及多個程序，系統會顯示「多個程序」圖示。如果流程來源系統不明，則會使用齒輪圖示。套用篩選器後，所有程序都會使用齒輪圖示。
- 標籤：在資料欄層級檢視畫面中，邊緣會加上標籤，說明資料欄之間的依附元件類型，例如 Exact copy 或 Other。

啟用資料歷程

啟用資料歷程，即可開始自動追蹤支援系統的歷程資訊。根據預設，啟用 API 後，系統會為大多數支援的服務啟動歷程追蹤功能。如要控管 Managed Service for Apache Spark 沿襲資料的擷取作業，請參閱「控管服務的沿襲資料擷取作業」。

您必須在查看歷程的專案和記錄歷程的專案中，啟用 Data Lineage API。詳情請參閱「專案類型」。

如要擷取沿襲資訊，請完成下列步驟：
1. 在 Google Cloud 控制台的「專案選取器」頁面中，選取要記錄歷程的專案。
  
  前往專案選取器
2. 啟用 Data Lineage API。
  
  啟用 Data Lineage API
3. 針對要記錄沿襲的每個專案，重複上述步驟。
在您查看歷程的專案中，啟用 Data Lineage API 和 Dataplex API。

啟用 API

控管服務的沿襲資料擷取作業

啟用 Data Lineage API 後，這項服務會開始自動追蹤大多數支援服務的沿革。然後在專案、資料夾或機構層級，選擇性啟用或停用特定整合的沿襲資料擷取功能。在預先發布期間，這項功能僅支援設定 Managed Service for Apache Spark 的擷取作業。

設定為階層式。系統會優先採用最明確的設定。舉例來說，專案層級的設定會覆寫資料夾層級的設定。如未設定任何項目，系統會使用服務的預設行為。如果是 Managed Service for Apache Spark，預設為「已啟用」。

設定變更最多可能需要 24 小時才會傳播，但通常會在兩小時內生效。

如果是 Managed Service for Apache Spark，只有在啟用沿襲時，系統才會傳送沿襲資料。詳情請參閱「使用 Spark 資料沿襲」和「搭配使用資料沿襲與 Managed Service for Apache Spark」。

如要進一步瞭解如何控管沿襲資料的擷取作業，包括如何以階層方式套用設定，請參閱「控管沿襲資料的擷取作業」。

必要條件

如要控管歷程擷取作業，必須使用 Data Lineage API。請確認您已為用戶端專案設定計費和配額，因為 Data Lineage API 是以用戶端為基礎的 API。

在用戶端專案中啟用 datalineage.googleapis.com API。詳情請參閱「啟用資料沿襲」。
設定用戶端專案。在下列範例中，請使用 X-Goog-User-Project 標頭。詳情請參閱「系統參數」。

取得目前設定

如要查看目前的沿襲設定，請使用 projects.locations.config.get 方法。您可以擷取專案、資料夾或機構的設定。

以下範例說明如何取得專案的設定：

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -H "X-Goog-User-Project: CLIENT_PROJECT_ID" \
     -X GET \
     "https://datalineage.googleapis.com/v1/projects/PROJECT_ID/locations/global/config"

替換下列值：

CLIENT_PROJECT_ID：用於帳單或配額的用戶端專案 ID。
PROJECT_ID：您要查看設定的專案 ID。

如要取得資料夾或機構的設定，請將 projects/PROJECT_ID 替換為 folders/FOLDER_ID 或 organizations/ORGANIZATION_ID。

指令會傳回下列其中一個輸出內容：

如果未設定任何項目，輸出內容會包含空白的 ingestion 物件：
```
  {
    "name": "projects/123456789012/locations/global/config",
    "ingestion": {}
  }
  
```
在本例中，Managed Service for Apache Spark 沿襲資料擷取作業會使用預設設定 enabled。

如果明確啟用 Managed Service for Apache Spark 沿襲資料擷取功能，您會看到下列輸出內容：

  {
    "name": "projects/123456789012/locations/global/config",
    "ingestion": {
      "rules": [
        {
          "integrationSelector": {
            "integration": "DATAPROC"
          },
          "lineageEnablement": {
            "enabled": true
          }
        }
      ]
    },
    "etag": "Wb35wDxTTLd6Z+QAL+Yd4g=="
  }

如果停用 Managed Service for Apache Spark 沿襲資料擷取功能，您會看到下列輸出內容：

  {
    "name": "projects/123456789012/locations/global/config",
    "ingestion": {
      "rules": [
        {
          "integrationSelector": {
            "integration": "DATAPROC"
          },
          "lineageEnablement": {
            "enabled": false
          }
        }
      ]
    },
    "etag": "Wb35wDxTTLd6Z+QAL+Yd4g=="
  }

回應中的 etag 欄位是伺服器根據目前設定值產生的核對和。使用 patch 方法更新設定時，您可以在要求主體中加入最近 get 要求傳回的 etag 值。如果您提供 etag，Knowledge Catalog 會使用該值驗證設定是否與上次讀取要求時相同。如果兩者不符，更新要求就會失敗。這樣一來，您就不會在讀取-修改-寫入情境中，意外覆寫其他使用者所做的設定。如果您未在 patch 要求中提供 etag，Knowledge Catalog 會無條件覆寫設定。

停用服務的沿襲資料擷取功能

如要為特定服務停用沿襲資料擷取功能，請使用 projects.locations.config.patch 方法，並搭配將特定 integration 的 lineageEnablement.enabled 設為 false 的擷取規則。

為避免在讀取/修改/寫入情境中，意外覆寫其他使用者所做的設定，您可以在要求主體中加入 etag 欄位。詳情請參閱「取得目前設定」。

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -H "X-Goog-User-Project: CLIENT_PROJECT_ID" \
     -X PATCH \
     "https://datalineage.googleapis.com/v1/projects/PROJECT_ID/locations/global/config" \
     --data-binary @- << EOF
{
  "ingestion": {
    "rules": [{
      "integrationSelector": {
        "integration": "DATAPROC"
      },
      "lineageEnablement": {
        "enabled": false
      }
    }]
  },
  "etag": "ETAG"
}
EOF

更改下列內容：

CLIENT_PROJECT_ID：用於帳單或配額的用戶端專案 ID。
PROJECT_ID：要更新設定的專案 ID。
ETAG：最近 get 要求傳回的 etag 值。

如要為資料夾或機構停用服務的沿襲資料擷取功能，請將 projects/PROJECT_ID 替換為 folders/FOLDER_ID 或 organizations/ORGANIZATION_ID。

為服務啟用歷程資料擷取功能

如要為特定服務啟用沿襲資料擷取功能，請使用 projects.locations.config.patch 方法，並搭配將特定 integration 的 lineageEnablement.enabled 設為 true 的擷取規則。

為避免在讀取/修改/寫入情境中，意外覆寫其他使用者所做的設定，您可以在要求主體中加入 etag 欄位。詳情請參閱「取得目前設定」。

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -H "X-Goog-User-Project: CLIENT_PROJECT_ID" \
     -X PATCH \
     "https://datalineage.googleapis.com/v1/projects/PROJECT_ID/locations/global/config" \
     --data-binary @- << EOF
{
  "ingestion": {
    "rules": [{
      "integrationSelector": {
        "integration": "DATAPROC"
      },
      "lineageEnablement": {
        "enabled": true
      }
    }]
  },
  "etag": "ETAG"
}
EOF

更改下列內容：

CLIENT_PROJECT_ID：用於帳單或配額的用戶端專案 ID。
PROJECT_ID：要更新設定的專案 ID。
ETAG：最近 get 要求傳回的 etag 值。

如要為資料夾或機構啟用服務的沿襲資料擷取功能，請將 projects/PROJECT_ID 替換為 folders/FOLDER_ID 或 organizations/ORGANIZATION_ID。

在 Knowledge Catalog 中查看歷程

您可以在 Knowledge Catalog 網頁介面中查看資料歷程資訊。

如要查看沿襲，請按照下列操作說明進行：

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

前往「Search」(搜尋) 頁面
選取「Knowledge Catalog」做為搜尋模式。
搜尋並點選要查看的項目。詳情請參閱「在 Knowledge Catalog 中搜尋資源」。
按一下「歷程」分頁標籤。

系統會開啟預設的「圖表」檢視畫面，顯示跨系統和區域的表格層級歷程。詳情請參閱「沿襲圖表檢視畫面」。
如要手動探索沿襲圖，請按一下節點旁邊的「展開」，一次載入五個節點。

詳情請參閱「手動探索沿襲圖」。
在「圖表」檢視畫面中，點選節點。

「詳細資料」面板隨即開啟，顯示資產資訊，例如完整名稱和類型。詳情請參閱「節點詳細資料」。
在「圖表」檢視畫面中，按一下含有程序圖示的邊緣。

「查詢」面板隨即開啟。詳情請參閱「檢查轉換邏輯」和「稽核及執行記錄」。
- 如要檢查轉換邏輯，請按一下「詳細資料」分頁標籤。
- 如要查看稽核記錄和執行記錄，請按一下「執行」分頁標籤。
在「沿襲關係探索器」面板中，選取篩選條件 (例如「方向」、「依附元件類型」或「時間範圍」)，然後按一下「套用」。

這會在特定區域中開啟焦點檢視畫面 (預覽)。這個檢視畫面會自動展開圖表，最多顯示三層節點。詳情請參閱「套用篩選器，取得焦點式沿襲檢視畫面」。
在聚焦的「圖表」檢視畫面中選取節點，然後在節點的詳細資料面板中，按一下「顯示路徑」，即可顯示從所選節點返回根項目的歷程路徑 (僅限聚焦檢視畫面)。

詳情請參閱「沿襲路徑視覺化」。
如要查看資料欄層級的沿襲 (僅適用於 BigQuery 和 Managed Service for Apache Spark 工作)，請執行下列其中一項操作：
- 在聚焦的「圖表」檢視畫面中，按一下表格中的欄圖示。
  
  欄圖示
- 在「歷程探索工具」面板中，依資料欄名稱篩選，然後按一下「套用」。
詳情請參閱資料欄層級歷程。
按一下「重設」。

這項操作會移除所有已套用的篩選器，並將您帶往圖表檢視畫面的開頭。
按一下「清單」即可切換至清單檢視畫面。

「清單」檢視畫面會以簡化和詳細的表格形式呈現資料表和資料欄層級的歷程，並與「圖表」檢視畫面同步。根據預設，系統會顯示簡易清單檢視畫面，您可以切換至詳細清單檢視畫面，分析個別來源與目標之間的關係。您可以設定要顯示哪些資料欄，以及匯出沿襲資料。詳情請參閱「沿革清單檢視畫面」。

調整歷程圖表

如要調整沿襲關係圖，可以使用沿襲關係探索器中的醒目顯示和篩選選項：

如要搜尋特定專案、資料集或實體名稱，請使用「篩選器」面板。

套用篩選器後，符合篩選條件的沿襲節點會視為相符節點。您可以調整相符和不相符節點的顯示方式。
在沿襲圖的右上角，按一下「更多動作」圖示 (位於「清除篩選器」按鈕旁)，即可查看顯示選項。
選取下列其中一個選項，或同時選取兩者：

你可以同時選取這兩個選項。如果同時選取這兩個選項，系統會隱藏未經過濾的節點，並在經過濾的圖表檢視中醒目顯示相符的節點。

在 BigQuery 中查看沿襲

您可以在 BigQuery 網頁介面中查看資料歷程資訊。