本文說明如何使用 searchLineageStreaming API 查詢多層級的跨區域資料沿襲。
searchLineageStreaming API 會從一組已定義的根實體開始，在指定方向 (上游或下游) 執行廣度優先搜尋，並以即時串流回應的形式傳回統一的歷程圖。
與標準沿襲查詢 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陣列中，明確定義要讓後端掃描的區域。
設定驗證
使用存取權杖初始化環境變數，驗證 curl 指令： Google Cloud
export ACCESS_TOKEN=$(gcloud auth print-access-token)
使用範例
下列範例使用 datalineage.googleapis.com 端點。
搜尋多層級、多專案沿襲
如要執行深入歷程搜尋，跨越多個圖表深度，並掃描不同專案，請定義下列變數： Google Cloud
將
limits.maxDepth設為目標遍歷深度 (接受1到100之間的值)。在
locations陣列中填入後端要交叉比對的目標區域 (例如["us", "us-east1"])。
C#
C#
在試用這個範例之前，請先按照「使用用戶端程式庫的 Data Lineage 快速入門導覽課程」中的 C# 設定說明操作。詳情請參閱 Data Lineage C# API 參考文件。
如要向 Data Lineage 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
Java
Java
在試用這個範例之前，請先按照「使用用戶端程式庫的 Data Lineage 快速入門導覽課程」中的 Java 設定說明操作。詳情請參閱 Data Lineage Java API 參考文件。
如要向 Data Lineage 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
Node.js
Node.js
在試用這個範例之前，請先按照「使用用戶端程式庫的 Data Lineage 快速入門導覽課程」中的 Node.js 設定說明操作。詳情請參閱 Data Lineage Node.js API 參考文件。
如要向 Data Lineage 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
Python
Python
在試用這個範例之前，請先按照「使用用戶端程式庫的 Data Lineage 快速入門導覽課程」中的 Python 設定說明操作。詳情請參閱 Data Lineage Python API 參考文件。
如要向 Data Lineage 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
Ruby
Ruby
在試用這個範例之前，請先按照「使用用戶端程式庫的 Data Lineage 快速入門導覽課程」中的 Ruby 設定說明操作。詳情請參閱 Data Lineage Ruby API 參考文件。
如要向 Data Lineage 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
REST
如要搜尋資料歷程，請使用 searchLineageStreaming 方法。
使用任何要求資料之前，請先修改下列項目的值：
PROJECT_ID：用於管理帳單和評估配額的 Google Cloud 專案 ID。LOCATION_ID： Google Cloud 位置，例如us-central1。SOURCE_PROJECT_ID：來源資料表所在的 Google Cloud 專案 ID。DATASET_ID：BigQuery 資料集 ID。TABLE_ID：BigQuery 資料表 ID。
HTTP 方法和網址：
POST https://datalineage.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID:searchLineageStreaming
JSON 要求主體：
{
"parent": "projects/PROJECT_ID/locations/LOCATION_ID",
"locations": [
"LOCATION_ID",
"us-east1",
"us-central1"
],
"rootCriteria": {
"entities": {
"entities": [
{
"fullyQualifiedName": "bigquery:SOURCE_PROJECT_ID.DATASET_ID.TABLE_ID"
}
]
}
},
"direction": "DOWNSTREAM",
"limits": {
"maxDepth": 10,
"maxResults": 5000
}
}
請展開以下其中一個選項，以傳送要求：
您應該會收到如下的 JSON 回覆：
{
"links": [
{
"source": {
"fullyQualifiedName": "bigquery:project-prod.dataset.source_table"
},
"target": {
"fullyQualifiedName": "bigquery:project-prod.dataset.target_table"
},
"depth": 1,
"location": "us"
}
]
}
搜尋多個地理位置
如要限制或擴大歷程圖掃描範圍，請修改 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 設為非零的正整數。
例如：
Java
Java
在試用這個範例之前，請先按照「使用用戶端程式庫的 Data Lineage 快速入門導覽課程」中的 Java 設定說明操作。詳情請參閱 Data Lineage Java API 參考文件。
如要向 Data Lineage 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
REST
使用任何要求資料之前，請先修改下列項目的值：
BILLING_PROJECT_ID：用於管理帳單和配額評估的專案。 Google Cloud提供專案編號或專案 ID。LOCATION_ID：執行沿襲搜尋的 Google Cloud 位置。FULLY_QUALIFIED_NAME：目標實體的完整名稱 (FQN)，格式為bigquery:PROJECT_ID.DATASET_ID.TABLE_ID。
HTTP 方法和網址：
POST https://datalineage.googleapis.com/v1/projects/BILLING_PROJECT_ID/locations/LOCATION_ID:searchLineageStreaming
JSON 要求主體：
{
"parent": "projects/BILLING_PROJECT_ID/locations/LOCATION_ID",
"locations": [
"LOCATION_ID"
],
"rootCriteria": {
"entities": {
"entities": [
{
"fullyQualifiedName": "FULLY_QUALIFIED_NAME"
}
]
}
},
"direction": "UPSTREAM",
"limits": {
"maxProcessPerLink": 5
}
}
請展開以下其中一個選項，以傳送要求：
回應行為：產生的串流會在 links[].processes 欄位中填入程序訊息，其中只包含絕對系統資源名稱 (例如 projects/my-project/locations/us/processes/my-process)。
使用 FieldMask 擷取完整程序詳細資料
如需管道的完整結構中繼資料 (例如 displayName、系統 attributes 或執行 origin)，而不只是資源名稱，請使用 API FieldMask：
為
limits.maxProcessPerLink提供非零值。在網址路徑中附加
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串流會使用projects/PROJECT_NUMBER/locations/LOCATION格式，在專屬的unreachable欄位 (重複字串) 中填入有問題的位置 (例如projects/123456789/locations/us-east1)。最佳做法：請務必建構用戶端應用程式，檢查
unreachable欄位，確認資料完整性，再處理圖表。