Usa el linaje de datos con sistemas de Google Cloud

Consulta el linaje de datos para comprender las relaciones entre los recursos de tu proyecto y los procesos que los crearon. Estas relaciones muestran cómo los procesos, como las consultas y las canalizaciones, transforman los recursos de datos, como las tablas y los conjuntos de datos. En esta guía, se describe cómo acceder a los gráficos de linaje en el catálogo universal de Dataplex, BigQuery y Vertex AI.

Puedes ver los detalles del linaje de datos en la consola de Google Cloud o recuperarlos con la API de Data Lineage.

Roles y permisos

El linaje de datos hace un seguimiento automático de la información de linaje cuando habilitas la API de Data Lineage. No necesitas ningún rol de administrador o editor para capturar el linaje de tus activos de datos.

Para ver el linaje de datos, necesitas permisos específicos de Identity and Access Management (IAM). La información del linaje se captura en todos los proyectos, por lo que necesitas permisos en varios proyectos.

Cuando ves el linaje en Dataplex Universal Catalog, BigQuery o Vertex AI, necesitas permisos para ver la información del linaje en el proyecto en el que lo ves.
Cuando ves el linaje que se registró en otros proyectos, necesitas permisos para ver la información del linaje en los proyectos en los que se registró.

Para obtener los permisos que necesitas para ver el linaje de datos, pídele a tu administrador que te otorgue los siguientes roles de IAM:

Visualizador de linaje de datos (roles/datalineage.viewer) en el proyecto en el que se registra el linaje y en el que se visualiza
Consulta los detalles de la tabla de BigQuery: Visualizador de datos de BigQuery (roles/bigquery.dataViewer) en el proyecto de almacenamiento de la tabla
Visualiza los detalles del trabajo de BigQuery: Visualizador de recursos de BigQuery (roles/bigquery.resourceViewer) en el proyecto de procesamiento del trabajo
Ver detalles de otros activos catalogados: Visualizador de Dataplex Catalog (roles/dataplex.catalogViewer) en el proyecto en el que se almacenan las entradas del catálogo

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Estos roles predefinidos contienen los permisos necesarios para ver el 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 ver el linaje de datos:

Consulta los detalles de la tabla de BigQuery: bigquery.tables.get: Proyecto de almacenamiento de la tabla
Visualiza los detalles del trabajo de BigQuery: bigquery.jobs.get: Es el proyecto de procesamiento del trabajo.

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

Tipos de vistas de linaje de datos

Puedes ver la información del linaje como un gráfico o una lista. De forma predeterminada, el gráfico de linaje muestra el linaje a nivel de la tabla. En el caso de los trabajos de BigQuery, puedes ver el linaje a nivel de la columna en las vistas de gráfico y de lista.

Los siguientes tipos de vistas están disponibles:

Vista de gráfico: Muestra el linaje como un gráfico interactivo, lo que te permite explorar las relaciones entre los recursos y las columnas de datos expandiendo los nodos.
Vista de lista: Muestra el linaje en formato tabular, lo que proporciona representaciones simplificadas y detalladas del linaje a nivel de la tabla y la columna. Puedes personalizar las columnas y exportar los datos de linaje desde esta vista.

Los elementos clave del gráfico se describen a continuación:

Nodos: Representan las entidades de datos. En la vista a nivel de la tabla, un nodo muestra el nombre de la tabla y sus columnas. En la vista a nivel de la columna, cada nodo representa una tabla específica y sus columnas que tienen linaje.
Aristas: Son las líneas que conectan los nodos y representan los procesos que ocurren entre ellos. Los bordes pueden incluir íconos o etiquetas para proporcionar más información sobre la transformación:
- Icons: En la vista a nivel de la tabla, los íconos aparecen en los bordes para representar el proceso de transformación. Cuando exploras el gráfico de forma manual, los íconos en los bordes representan el sistema fuente del proceso (por ejemplo, BigQuery o Vertex AI). Si hay varios procesos involucrados, se muestra un ícono de "varios procesos". Si se desconoce el sistema fuente del proceso, se usa un ícono de engranaje. Cuando aplicas filtros, se usa un ícono de ajustes para todos los procesos.
- Etiquetas: En la vista a nivel de la columna, las aristas se etiquetan para describir el tipo de dependencia entre las columnas, como Exact copy o Other.

Habilita el linaje de datos

Habilita el linaje de datos para comenzar a hacer un seguimiento automático de la información de linaje de los sistemas compatibles. De forma predeterminada, habilitar la API activa el seguimiento del linaje para la mayoría de los servicios compatibles. Para controlar la transferencia de metadatos de linaje de Dataproc, consulta Cómo controlar la transferencia de metadatos de linaje para un servicio.

Debes habilitar la API de Data Lineage tanto en el proyecto en el que ves el linaje como en los proyectos en los que se registra el linaje. Para obtener más información, consulta Tipos de proyectos.

Para capturar información del linaje, completa los siguientes pasos:
1. En la consola de Google Cloud , en la página del selector de proyectos, selecciona el proyecto en el que deseas registrar el linaje.
  
  Ve al selector de proyectos
2. Habilita la API de Data Lineage.
  
  Habilita la API de Data Lineage
3. Repite los pasos anteriores para cada proyecto en el que quieras registrar el linaje.
En el proyecto en el que ves el linaje, habilita la API de Data Lineage y la API de Dataplex.

Habilitar las API

Controla la transferencia de metadatos de linaje para un servicio

Después de habilitar la API de Data Lineage, el servicio comienza a hacer un seguimiento automático del linaje para la mayoría de los servicios compatibles. Luego, puedes habilitar o inhabilitar de forma selectiva la transferencia de metadatos de linaje para integraciones específicas a nivel del proyecto, la carpeta o la organización. Durante la versión preliminar, esta función solo admite la configuración de la transferencia para Dataproc. Si inhabilitas la transferencia de metadatos de linaje para Dataproc, también se inhabilitará para Dataproc Serverless for Apache Spark.

La configuración es jerárquica. La configuración más específica tiene prioridad. Por ejemplo, una configuración a nivel del proyecto anula una configuración a nivel de la carpeta. Si no se establece ninguna configuración, se usa el comportamiento predeterminado del servicio. En el caso de Dataproc, el valor predeterminado es Habilitado.

Los cambios en la configuración pueden tardar hasta 24 horas en propagarse, pero, por lo general, se aplican en un plazo de dos horas.

En el caso de Dataproc y Dataproc Serverless para Apache Spark, los datos de linaje solo se envían si el linaje también está habilitado en Dataproc. Para obtener más información, consulta Linaje de Spark de Dataproc y Linaje de datos de Dataproc Serverless para Apache Spark.

Para obtener más información sobre cómo controlar la transferencia de metadatos de linaje, incluido cómo se aplica la configuración de forma jerárquica, consulta Controla la transferencia de metadatos de linaje.

Requisitos previos

Para controlar la transferencia de metadatos de linaje, debes usar la API de Data Lineage. Asegúrate de tener un proyecto del cliente configurado para la facturación y la cuota, ya que la API de Data Lineage es una API basada en el cliente.

Habilita la API de datalineage.googleapis.com en tu proyecto cliente. Para obtener más información, consulta Habilita el linaje de datos.
Configura el proyecto del cliente. En los siguientes ejemplos, usa el encabezado X-Goog-User-Project. Para obtener más información, consulta Parámetros del sistema.

Obtén la configuración actual

Para ver la configuración actual del linaje, usa el método projects.locations.config.get. Puedes recuperar la configuración de un proyecto, una carpeta o una organización.

En el siguiente ejemplo, se muestra cómo obtener la configuración de un proyecto:

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -H "X-Goog-User-Project: CLIENT_PROJECT_ID" \
     -X GET \
     "https://datalineage.googleapis.com/v1/projects/PROJECT_ID/locations/global/config"

Reemplaza estos valores:

CLIENT_PROJECT_ID: Es el ID de tu proyecto de cliente que se usa para la facturación o las cuotas.
PROJECT_ID: Es el ID del proyecto cuya configuración deseas ver.

Para obtener la configuración de una carpeta o una organización, reemplaza projects/PROJECT_ID por folders/FOLDER_ID o organizations/ORGANIZATION_ID.

El comando devuelve uno de los siguientes resultados:

Si no se establece ninguna configuración, obtendrás un resultado con un objeto ingestion vacío:
```
  {
    "name": "projects/123456789012/locations/global/config",
    "ingestion": {}
  }
  
```
En este caso, la transferencia de metadatos de linaje de Dataproc usa el parámetro de configuración predeterminado, que es enabled.

Si la transferencia de metadatos de linaje de Dataproc está habilitada de forma explícita, obtendrás el siguiente resultado:

  {
    "name": "projects/123456789012/locations/global/config",
    "ingestion": {
      "rules": [
        {
          "integrationSelector": {
            "integration": "DATAPROC"
          },
          "lineageEnablement": {
            "enabled": true
          }
        }
      ]
    },
    "etag": "Wb35wDxTTLd6Z+QAL+Yd4g=="
  }

Si la transferencia de linaje de Dataproc está inhabilitada, obtendrás el siguiente resultado:

  {
    "name": "projects/123456789012/locations/global/config",
    "ingestion": {
      "rules": [
        {
          "integrationSelector": {
            "integration": "DATAPROC"
          },
          "lineageEnablement": {
            "enabled": false
          }
        }
      ]
    },
    "etag": "Wb35wDxTTLd6Z+QAL+Yd4g=="
  }

El campo etag de la respuesta es una suma de comprobación que genera el servidor en función del valor actual de la configuración. Cuando actualizas una configuración con el método patch, puedes incluir el valor etag que se devolvió de una solicitud get reciente en el cuerpo de la solicitud. Si proporcionas etag, Dataplex Universal Catalog lo usa para verificar que la configuración no haya cambiado desde tu última solicitud de lectura. Si hay una discrepancia, la solicitud de actualización falla. Esto evita que sobrescribas de forma accidental las configuraciones realizadas por otros usuarios en situaciones de lectura, modificación y escritura. Si no proporcionas un etag en tu solicitud de patch, Dataplex Universal Catalog anulará la configuración de forma incondicional.

Inhabilita la transferencia de datos de linaje para un servicio

Para inhabilitar la transferencia de metadatos de linaje para un servicio específico, usa el método projects.locations.config.patch con una regla de transferencia que establezca lineageEnablement.enabled en false para el integration específico.

Para evitar que se reemplacen de forma accidental las configuraciones realizadas por otros usuarios en situaciones de lectura-modificación-escritura, puedes incluir el campo etag en el cuerpo de la solicitud. Para obtener más información, consulta Cómo obtener la configuración actual.

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -H "X-Goog-User-Project: CLIENT_PROJECT_ID" \
     -X PATCH \
     "https://datalineage.googleapis.com/v1/projects/PROJECT_ID/locations/global/config" \
     --data-binary @- << EOF
{
  "ingestion": {
    "rules": [{
      "integrationSelector": {
        "integration": "DATAPROC"
      },
      "lineageEnablement": {
        "enabled": false
      }
    }]
  },
  "etag": "ETAG"
}
EOF

Reemplaza lo siguiente:

CLIENT_PROJECT_ID: Es el ID de tu proyecto de cliente que se usa para la facturación o las cuotas.
PROJECT_ID: Es el ID del proyecto cuya configuración deseas actualizar.
ETAG: Es el valor de etag que se devolvió de una solicitud get reciente.

Para inhabilitar la transferencia de metadatos de linaje de un servicio para una carpeta o una organización, reemplaza projects/PROJECT_ID por folders/FOLDER_ID o organizations/ORGANIZATION_ID.

Habilita la transferencia del linaje para un servicio

Para habilitar la transferencia de metadatos de linaje para un servicio específico, usa el método projects.locations.config.patch con una regla de transferencia que establezca lineageEnablement.enabled en true para el integration específico.

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -H "X-Goog-User-Project: CLIENT_PROJECT_ID" \
     -X PATCH \
     "https://datalineage.googleapis.com/v1/projects/PROJECT_ID/locations/global/config" \
     --data-binary @- << EOF
{
  "ingestion": {
    "rules": [{
      "integrationSelector": {
        "integration": "DATAPROC"
      },
      "lineageEnablement": {
        "enabled": true
      }
    }]
  },
  "etag": "ETAG"
}
EOF

Reemplaza lo siguiente:

CLIENT_PROJECT_ID: Es el ID de tu proyecto de cliente que se usa para la facturación o las cuotas.
PROJECT_ID: Es el ID del proyecto cuya configuración deseas actualizar.
ETAG: Es el valor de etag que se devolvió de una solicitud get reciente.

Para habilitar la transferencia de metadatos de linaje de un servicio para una carpeta o una organización, reemplaza projects/PROJECT_ID por folders/FOLDER_ID o organizations/ORGANIZATION_ID.

Consulta el linaje en Dataplex Universal Catalog

Puedes ver la información del linaje de datos en la interfaz web de Dataplex Universal Catalog.

Para ver el linaje, sigue estas instrucciones:

En la consola de Google Cloud , ve a la página Búsqueda de Dataplex Universal Catalog.

Ir a Búsqueda
Selecciona Dataplex Universal Catalog como el modo de búsqueda.
Busca la entrada que deseas ver y, luego, haz clic en ella. Para obtener más información, consulta Cómo buscar recursos en Dataplex Universal Catalog.
Haz clic en la pestaña Linaje.

Se abrirá la vista predeterminada Gráfico, que muestra el linaje a nivel de la tabla en todos los sistemas y regiones. Para obtener más información, consulta Vista del gráfico de linaje.
Para explorar el gráfico de linaje de forma manual, haz clic en Expandir junto a un nodo para cargar cinco nodos más a la vez.

Para obtener más información, consulta Cómo explorar manualmente el gráfico de linaje.
Haz clic en un nodo en la vista Graph.

Se abrirá el panel Detalles con información sobre el activo, como el nombre y el tipo completamente calificados. Para obtener más información, consulta Detalles del nodo.
Haz clic en una arista con un ícono de proceso en la vista Graph.

Se abrirá el panel Consulta. Para obtener más información, consulta Cómo inspeccionar la lógica de transformación y Auditoría y registro del historial de ejecuciones.
- Para inspeccionar la lógica de transformación, haz clic en la pestaña Detalles.
- Para ver la auditoría y el historial de las ejecuciones, haz clic en la pestaña Ejecuciones.
En el panel Explorador de linaje, selecciona los criterios de filtro (por ejemplo, Dirección, Tipo de dependencia o Intervalo de tiempo) y, luego, haz clic en Aplicar.

Se abrirá una vista enfocada dentro de una región específica (vista previa). En esta vista, el gráfico se expande automáticamente hasta tres niveles de nodos. Para obtener más información, consulta Cómo aplicar filtros para obtener una vista enfocada del linaje.
En la vista enfocada Gráfico, selecciona un nodo y, luego, en el panel de detalles del nodo, haz clic en Visualizar ruta para visualizar la ruta de linaje desde el nodo seleccionado hasta la entrada raíz (solo en la vista enfocada).

Para obtener más información, consulta Visualización de la ruta de linaje.
Para ver el linaje a nivel de la columna (solo para los trabajos de BigQuery), realiza una de las siguientes acciones:
- En una vista de gráfico enfocada, haz clic en el ícono de columna de una tabla.
  
  Ícono de columna
- En el panel Lineage Explorer, filtra por nombre de columna y haz clic en Aplicar.
Para obtener más información, consulta Linaje a nivel de la columna.
Haz clic en Restablecer.

Esta acción quita todos los filtros aplicados y te lleva al comienzo de la vista de gráfico.
Haz clic en Lista para cambiar a la vista de lista.

La vista de lista ofrece representaciones tabulares detalladas y simplificadas del linaje tanto a nivel de tabla como de columna, sincronizadas con la vista de gráfico. De forma predeterminada, se muestra la vista de lista simplificada, y puedes alternar a la vista de lista detallada para analizar las relaciones individuales entre la fuente y el destino. Puedes configurar las columnas que se muestran y exportar los datos de linaje. Para obtener más información, consulta Vista de lista de linaje.

Cómo ver el linaje en BigQuery

Puedes ver la información del linaje de datos en la interfaz web de BigQuery.