使用伺服器端自動化功能搜尋多區域沿襲

本文說明如何使用 searchLineageStreaming API 查詢多層級跨區域資料沿襲。

searchLineageStreaming API 會從一組已定義的根實體開始，在指定方向 (上游或下游) 執行廣度優先搜尋，並以即時串流回應的形式傳回統一的沿襲圖。

詳情請參閱「關於多區域沿襲搜尋」。

主要功能

searchLineageStreaming API 包含下列功能：

  • 廣度優先搜尋：逐層遍歷沿襲圖，準確計算每個連結資產的深度。

  • 串流回應：在後端系統探索到子圖和沿襲連結時，就會傳回這些項目。這項功能非常適合廣泛或深入的沿襲圖，可避免要求逾時。

  • 多個位置和多個專案的遍歷：雖然您只在要求路徑中指定一個帳單專案，但只要您具備必要權限，API 就會自動探索並遍歷多個 Google Cloud 專案和地理位置的歷程連結。

  • 精細的資料欄層級歷程：支援搜尋資產間的資料欄層級依附元件。

  • 萬用字元查詢：在完整名稱 (FQN) 後方加上 *，即可擷取特定實體的所有欄位層級沿襲。

  • 管道洞察：選擇性擷取有關建立沿襲連結的轉換管道 (程序) 的中繼資料。

事前準備

向 API 發出要求前，請先確認您符合下列安全性和環境先決條件：

必要的角色

如要取得搜尋資料歷程連結所需的權限，請要求系統管理員在儲存歷程連結和程序的專案中，授予您「資料歷程檢視者 」(roles/datalineage.viewer) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

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

所需權限

如要搜尋資料沿襲連結，必須具備下列權限：

  • 搜尋實體層級的沿襲： datalineage.events.get 在儲存連結的專案中
  • 搜尋資料欄層級的沿革： datalineage.events.getFields 在儲存連結的專案中
  • 擷取完整管道程序詳細資料： datalineage.processes.get 在儲存程序的專案中

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

資源範圍

設定 API 要求時，您必須區分用於管理結帳的資源，以及 API 掃描的實際位置：

  • 帳單上層路徑：網址要求中的 parent 路徑必須使用 projects/project/locations/location 格式。這個特定專案/位置組合專門用於評估帳單配額和 API 速率限制。

  • 目標位置：在要求主體內的 locations 陣列中，明確定義要讓後端掃描的區域。

設定驗證

使用 Google Cloud 存取權杖初始化環境變數，驗證 curl 指令：

export ACCESS_TOKEN=$(gcloud auth print-access-token)

使用範例

下列範例使用 datalineage.googleapis.com 端點。

搜尋多層級、多專案沿襲

如要執行深度沿襲搜尋，跨越多個圖表深度，並掃描不同專案，請定義下列變數： Google Cloud

  • 將 limits.maxDepth 設為目標遍歷深度 (接受 1 到 100 之間的值)。

  • 在 locations 陣列中填入後端要交叉比對的目標區域 (例如 ["us", "us-east1"])。

例如：

curl -H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-X POST https://datalineage.googleapis.com/v1/projects/my-billing-project/locations/us:searchLineageStreaming \
--data '{
  "parent": "projects/my-billing-project/locations/us",
  "locations": ["us", "us-east1", "us-central1"],
  "rootCriteria": {
    "entities": {
      "entities": [{
        "fullyQualifiedName": "bigquery:project-prod.dataset.source_table"
      }]
    }
  },
  "direction": "DOWNSTREAM",
  "limits": {
    "maxDepth": 10,
    "maxResults": 5000
  }
}'

搜尋多個地理位置

您可以修改 locations 重複陣列欄位中傳遞的地理區域，限制或擴大譜系圖掃描範圍。

例如：

curl -H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-X POST https://datalineage.googleapis.com/v1/projects/my-billing-project/locations/us:searchLineageStreaming \
--data '{
  "parent": "projects/my-billing-project/locations/us",
  "locations": ["us", "europe-west1", "asia-south2"],
  "rootCriteria": {
    "entities": {
      "entities": [{
        "fullyQualifiedName": "bigquery:my-project.dataset.global_table"
      }]
    }
  },
  "direction": "DOWNSTREAM"
}'

根據預設，API 會省略程序資訊 (maxProcessPerLink預設為 0)。如要擷取建立資料連結的管道資源名稱，請將 limits.maxProcessPerLink 設為非零的正整數。

例如：

curl -H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-X POST https://datalineage.googleapis.com/v1/projects/my-billing-project/locations/us:searchLineageStreaming \
--data '{
  "parent": "projects/my-billing-project/locations/us",
  "locations": ["us"],
  "rootCriteria": {
    "entities": {
      "entities": [{
        "fullyQualifiedName": "bigquery:my-project.dataset.target_table"
      }]
    }
  },
  "direction": "UPSTREAM",
  "limits": {
    "maxProcessPerLink": 5
  }
}'

回應行為：產生的串流會在 links[].processes 欄位中填入程序訊息，其中只包含絕對系統資源名稱 (例如 projects/my-project/locations/us/processes/my-process)。

使用 FieldMask 擷取完整程序詳細資料

如果您需要管道的完整結構中繼資料 (例如 displayName、系統 attributes 或執行 origin)，而不只是資源名稱，則必須使用 API FieldMask：

  1. 為 limits.maxProcessPerLink 提供非零值。

  2. 在網址路徑中附加 fields 查詢參數，並指定 links.processes.process 和其他必填欄位。

例如：

curl -H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-X POST "https://datalineage.googleapis.com/v1/projects/my-billing-project/locations/us:searchLineageStreaming?fields=links.processes.process,links.source,links.target,links.depth" \
--data '{
  "parent": "projects/my-billing-project/locations/us",
  "locations": ["us"],
  "rootCriteria": {
    "entities": {
      "entities": [{
        "fullyQualifiedName": "bigquery:my-project.dataset.target_table"
      }]
    }
  },
  "direction": "UPSTREAM",
  "limits": {
    "maxProcessPerLink": 5
  }
}'

搜尋資料表和資料欄層級的歷程

您可以在單一要求中搜尋資料表層級 (資產層級) 和資料欄層級 (欄位層級) 的沿革，方法是在 rootCriteria.entities.entities 清單中提供多個實體：

  • 如要取得資料表層級的沿襲資訊，請省略 field 陣列。

  • 如要取得資料欄層級的沿襲資訊，請在 field 陣列中指定單一資料欄。

例如：

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -X POST https://datalineage.googleapis.com/v1/projects/my-billing-project/locations/us:searchLineageStreaming \
     --data '{
       "parent": "projects/my-billing-project/locations/us",
       "locations": ["us"],
       "rootCriteria": {
         "entities": {
           "entities": [
             {
               "fullyQualifiedName": "bigquery:my-project.dataset.table_a"
             },
             {
               "fullyQualifiedName": "bigquery:my-project.dataset.table_b",
               "field": ["email"]
             }
           ]
         }
       },
       "direction": "DOWNSTREAM"
     }'

使用萬用字元取得資料欄層級歷程

如要搜尋特定資料表的所有可用資料欄層級沿襲，而不需個別列出每個資料欄，請在 field 陣列中使用萬用字元 * 做為單一值。

例如：

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -X POST https://datalineage.googleapis.com/v1/projects/my-billing-project/locations/us:searchLineageStreaming \
     --data '{
       "parent": "projects/my-billing-project/locations/us",
       "locations": ["us"],
       "rootCriteria": {
         "entities": {
           "entities": [{
             "fullyQualifiedName": "bigquery:my-project.dataset.my_table",
             "field": ["*"]
           }]
         }
       },
       "direction": "DOWNSTREAM"
     }'

篩選沿襲結果

您可以在要求主體中使用 filters 區塊，縮小沿革搜尋結果範圍。

依附屬項目類型篩選

如要將結果限制為特定依附元件類型，例如直接副本 (EXACT_COPY) 或篩選和分組等轉換 (OTHER)，請使用 dependencyTypes 篩選器。

例如：

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -X POST https://datalineage.googleapis.com/v1/projects/my-billing-project/locations/us:searchLineageStreaming \
     --data '{
       "parent": "projects/my-billing-project/locations/us",
       "locations": ["us"],
       "rootCriteria": {
         "entities": {
           "entities": [{
             "fullyQualifiedName": "bigquery:my-project.dataset.my_table"
           }]
         }
       },
       "direction": "DOWNSTREAM",
       "filters": {
         "dependencyTypes": ["EXACT_COPY"]
       }
     }'

僅限資料表歷程

如要確保搜尋結果只會傳回資料表層級的沿襲，並完全排除資料欄層級的沿襲，請將 entitySet 篩選器設為 ENTITIES。

例如：

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -X POST https://datalineage.googleapis.com/v1/projects/my-billing-project/locations/us:searchLineageStreaming \
     --data '{
       "parent": "projects/my-billing-project/locations/us",
       "locations": ["us"],
       "rootCriteria": {
         "entities": {
           "entities": [{
             "fullyQualifiedName": "bigquery:my-project.dataset.my_table"
           }]
         }
       },
       "direction": "DOWNSTREAM",
       "filters": {
         "entitySet": "ENTITIES"
       }
     }'

依時間範圍篩選

您可以將沿襲搜尋結果限制在特定時間間隔內。

舉例來說，如要搜尋在特定時間戳記之後建立的歷程資料，請使用下列要求：

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -X POST https://datalineage.googleapis.com/v1/projects/my-billing-project/locations/us:searchLineageStreaming \
     --data '{
       "parent": "projects/my-billing-project/locations/us",
       "locations": ["us"],
       "rootCriteria": {
         "entities": {
           "entities": [{
             "fullyQualifiedName": "bigquery:my-project.dataset.my_table"
           }]
         }
       },
       "direction": "DOWNSTREAM",
       "filters": {
         "timeRange": {
           "startTime": "2026-01-01T00:00:00Z"
         }
       }
     }'

處理無法連上的位置 (部分結果)

由於串流 API 會同時掃描一組分散的專案和位置，因此在執行期間，部分遠端區域可能會暫時停止運作、無法通訊或設定錯誤。

為保護資料完整性，searchLineageStreamingResponse 串流包含專屬的診斷欄位，稱為 unreachable：

  • 欄位名稱：unreachable (以重複字串表示)

  • 值格式：projects/PROJECT_NUMBER/locations/LOCATION (例如 projects/123456789/locations/us-east1)

後續步驟