使用服务器端自动化搜索多区域沿袭

本文档介绍了如何使用 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"]）。

例如：

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
  }
}'

响应行为：生成的流会使用仅包含绝对系统资源名称（例如 projects/my-project/locations/us/processes/my-process）的进程消息填充 links[].processes 字段。

使用 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）

后续步骤