本文档介绍了如何使用 searchLineageStreaming API 查找多级跨区域数据沿袭。
searchLineageStreaming
API 从一组定义的根实体开始,在指定方向(上游或
下游)执行广度优先搜索,并以实时流式传输响应的形式返回统一的
沿袭图。
如需了解详情,请参阅 多区域沿袭搜索简介。
主要功能
searchLineageStreaming API 具有以下功能:
广度优先搜索:逐层遍历沿袭图, 准确计算每个连接资产的深度。
流式传输响应:返回后端系统 发现的子图和沿袭链接。对于广泛或深入的沿袭图,这种方式非常高效,并且可以防止请求超时。
多位置和多项目遍历:虽然您在请求路径中仅指定一个 结算项目,但只要您拥有所需的权限,API 就会自动发现并 遍历多个 Google Cloud 项目和地理 位置的沿袭链接。
精细的列级沿袭:支持搜索资产之间的列级 依赖项。
通配符查找:让您可以通过在完全限定名称 (FQN) 后添加
*来检索 特定实体的所有列级沿袭。流水线洞见:可以选择检索有关创建沿袭链接的转换 流水线(进程)的元数据。
准备工作
在向 API 发出请求之前,请确保您已满足以下安全和环境前提条件:
所需的角色
如需获得搜索数据沿袭链接所需的权限,请让您的管理员为您授予存储沿袭链接和进程的项目中的Data Lineage Viewer (roles/datalineage.viewer) IAM 角色。如需详细了解如何授予角色,请参阅管理对项目、文件夹和组织的访问权限。
此预定义角色包含 搜索数据沿袭链接所需的权限。如需查看所需的确切权限,请展开所需权限部分:
所需权限
您必须拥有以下权限才能搜索数据沿袭链接:
-
搜索实体级沿袭:
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"])。
C#
C#
试用此示例之前,请按照 C# 设置说明进行操作。请按照 Knowledge Catalog 快速入门:使用 客户端库中的说明进行操作。 如需了解详情,请参阅 Knowledge Catalog C# API 参考文档。
如需向 Knowledge Catalog 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅 为本地开发环境设置身份验证。
Java
Java
试用此示例之前,请按照 Java 设置说明进行操作,具体请参阅 Knowledge Catalog 快速入门:使用 客户端库。 如需了解详情,请参阅 Knowledge Catalog Java API 参考文档。
如需向 Knowledge Catalog 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅 为本地开发环境设置身份验证。
Node.js
Java
试用此示例之前,请按照 Java 设置说明进行操作。请按照 Knowledge Catalog 快速入门:使用 客户端库中的说明进行操作。
如需向 Knowledge Catalog 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅 为本地开发环境设置身份验证。
Python
Python
试用此示例之前,请按照 Python 设置说明进行操作,具体请参阅 Knowledge Catalog 快速入门:使用 使用客户端库。 如需了解详情,请参阅 Knowledge Catalog Python API 参考文档。
如需向 Knowledge Catalog 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅 为本地开发环境设置身份验证。
Ruby
Ruby
试用此示例之前,请按照 Ruby 设置说明进行操作。请参阅 Knowledge Catalog 快速入门:使用客户端库。如需了解详情,请参阅 Knowledge Catalog Ruby API 参考文档。
如需向 Knowledge Catalog 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅 为本地开发环境设置身份验证。
REST
如需搜索数据沿袭,请使用
searchLineageStreaming 方法。
在使用任何请求数据之前, 请先进行以下替换:
PROJECT_ID:用于管理结算和配额评估的项目 ID。 Google CloudLOCATION_ID:位置,例如us-central1。 Google CloudSOURCE_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 配置为非零正
整数。
例如:
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
}
}'
响应行为:生成的流会使用仅包含其绝对系统资源名称(例如 projects/my-project/locations/us/processes/my-process)的进程消息填充 links[].processes 字段。
使用 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 流包含一个名为 unreachable 的专用诊断字段:
字段名称:
unreachable(表示为重复字符串)值格式:
projects/PROJECT_NUMBER/locations/LOCATION(例如projects/123456789/locations/us-east1)