Cómo buscar el linaje multirregión con la automatización del servidor

En este documento, se describe cómo buscar el linaje de datos multirregional y de varios niveles con la API de searchLineageStreaming.

La API de searchLineageStreaming realiza una búsqueda en amplitud en una dirección especificada (ascendente o descendente) a partir de un conjunto definido de entidades raíz y devuelve un gráfico de linaje unificado como una respuesta de transmisión en tiempo real.

Para obtener más información, consulta Acerca de la búsqueda de linaje en varias regiones.

Funciones clave

La API de searchLineageStreaming incluye las siguientes capacidades:

  • Búsqueda en amplitud: Recorre el gráfico de linaje capa por capa y calcula con precisión la profundidad de cada recurso conectado.

  • Respuesta de transmisión: Devuelve subgrafos y vínculos de linaje a medida que los descubre el sistema de backend. Esto es muy eficiente para los gráficos de linaje amplios o detallados, y evita los tiempos de espera de las solicitudes.

  • Recorrido por varias ubicaciones y varios proyectos: Aunque solo especifiques un proyecto de facturación en la ruta de la solicitud, la API descubre y recorre automáticamente los vínculos de linaje en varios proyectos de Google Cloud y ubicaciones geográficas, siempre que tengas los permisos necesarios.

  • Linaje detallado a nivel de columna: Admite la búsqueda de dependencias a nivel de columna entre recursos.

  • Búsquedas con comodines: Te permite recuperar todo el linaje a nivel de la columna para una entidad específica agregando el sufijo * al nombre completamente calificado (FQN).

  • Estadísticas de la canalización: Recupera de forma opcional metadatos sobre las canalizaciones de transformación (procesos) que crearon los vínculos de linaje.

Antes de comenzar

Antes de realizar solicitudes a la API, asegúrate de cumplir con los siguientes requisitos previos de seguridad y entorno:

Roles obligatorios

Para obtener los permisos que necesitas para buscar vínculos de linaje de datos, pídele a tu administrador que te otorgue el rol de IAM de Visualizador de linaje de datos (roles/datalineage.viewer) en los proyectos en los que se almacenan los vínculos y los procesos de linaje. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Este rol predefinido contiene los permisos necesarios para buscar vínculos de linaje de datos. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

Permisos necesarios

Se requieren los siguientes permisos para buscar vínculos de linaje de datos:

  • Buscar el linaje a nivel de la entidad: datalineage.events.get en el proyecto en el que se almacena la vinculación
  • Buscar el linaje a nivel de la columna: datalineage.events.getFields en el proyecto en el que se almacena la vinculación
  • Recupera los detalles completos del proceso de canalización: datalineage.processes.get en el proyecto en el que se almacena el proceso

También puedes obtener estos permisos con roles personalizados o con otros roles predefinidos.

Delimitación de recursos

Cuando configures tu solicitud a la API, debes distinguir entre el recurso que se usa para la facturación administrativa y las ubicaciones reales que analiza la API:

  • Ruta principal de facturación: La ruta parent en la solicitud de URL debe usar el formato projects/project/locations/location. Este par específico de proyecto y ubicación se usa exclusivamente para evaluar las cuotas de facturación y los límites de frecuencia de la API.

  • Ubicaciones objetivo: Define de forma explícita las regiones que deseas que el backend analice en el array locations dentro del cuerpo de la solicitud.

Configuración de la autenticación

Inicializa una variable de entorno con un token de acceso de Google Cloud para autenticar tus comandos de curl:

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

Ejemplos de uso

En los siguientes ejemplos, se usa el extremo datalineage.googleapis.com.

Busca linaje de varios niveles y proyectos

Para ejecutar una búsqueda de linaje detallada que atraviese varias profundidades del gráfico y analice distintos proyectos de Google Cloud , define las siguientes variables:

  • Establece limits.maxDepth en la profundidad de la búsqueda objetivo (acepta valores de 1 a 100).

  • Completa el array locations con las regiones objetivo con las que deseas que el backend compare datos mediante referencia cruzada (por ejemplo, ["us", "us-east1"]).

Por ejemplo:

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

Cómo buscar varias ubicaciones geográficas

Puedes limitar o expandir el análisis de tu gráfico de linaje modificando las regiones geográficas que se pasan dentro del campo de array repetido locations.

Por ejemplo:

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

De forma predeterminada, la API omite la información del proceso (maxProcessPerLink se establece de forma predeterminada en 0). Para recuperar los nombres de recursos de las canalizaciones que crearon tus vinculaciones de datos, configura limits.maxProcessPerLink en un número entero positivo distinto de cero.

Por ejemplo:

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

Comportamiento de la respuesta: El flujo resultante completa el campo links[].processes con mensajes de proceso que solo contienen su nombre de recurso del sistema absoluto (como projects/my-project/locations/us/processes/my-process).

Cómo recuperar detalles completos del proceso con un FieldMask

Si necesitas metadatos estructurales completos sobre una canalización (como su displayName, su attributes del sistema o su origin de ejecución) en lugar de solo su nombre de recurso, debes usar una API FieldMask:

  1. Proporciona un valor distinto de cero para limits.maxProcessPerLink.

  2. Agrega un parámetro de búsqueda fields a la ruta de URL y especifica links.processes.process junto con otros campos obligatorios.

Por ejemplo:

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

Buscar linaje a nivel de la tabla y de la columna

Puedes buscar el linaje a nivel de la tabla (nivel del activo) y a nivel de la columna (nivel del campo) en una sola solicitud si proporcionas varias entidades en la lista rootCriteria.entities.entities:

  • Para el linaje a nivel de la tabla, omite el array field.

  • Para el linaje a nivel de la columna, especifica una sola columna en el array field.

Por ejemplo:

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

Usa comodines para el linaje a nivel de la columna

Para buscar todo el linaje disponible a nivel de la columna de una tabla específica sin enumerar cada columna de forma individual, usa el carácter comodín * como el único valor en el array field.

Por ejemplo:

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

Cómo filtrar los resultados del linaje

Puedes definir mejor los resultados de la búsqueda de linaje con el bloque filters en el cuerpo de la solicitud.

Filtrar por tipo de dependencia

Para restringir los resultados a tipos de dependencia específicos, como copias directas (EXACT_COPY) o transformaciones como el filtrado y la agrupación (OTHER), usa el filtro dependencyTypes.

Por ejemplo:

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

Restringe el linaje solo a la tabla

Para asegurarte de que la búsqueda solo muestre el linaje a nivel de la tabla y excluya por completo el linaje a nivel de la columna, establece el filtro entitySet en ENTITIES.

Por ejemplo:

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

Cómo filtrar por período

Puedes restringir los resultados de la búsqueda de linaje a un intervalo de tiempo específico.

Por ejemplo, para buscar datos de linaje creados después de una marca de tiempo específica, usa la siguiente solicitud:

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

Cómo controlar ubicaciones inaccesibles (resultados parciales)

Dado que la API de transmisión analiza simultáneamente un conjunto distribuido de proyectos y ubicaciones, es posible que algunas regiones remotas no estén disponibles temporalmente, no se comuniquen o estén mal configuradas durante la ejecución.

Para proteger la integridad de los datos, la transmisión searchLineageStreamingResponse contiene un campo de diagnóstico dedicado llamado unreachable:

  • Nombre del campo: unreachable (representado como una cadena repetida)

  • Formato del valor: projects/PROJECT_NUMBER/locations/LOCATION (por ejemplo, projects/123456789/locations/us-east1)

¿Qué sigue?