Configura la transferencia de metadatos de linaje de datos para un servicio

Puedes habilitar o inhabilitar de forma selectiva la transferencia de linaje para integraciones específicas a nivel de proyecto, carpeta u organización.

Para obtener más información sobre las integraciones y las situaciones de configuración compatibles, consulta Controla la transferencia del linaje de datos.

Requisitos previos

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

Roles y permisos

Para obtener los permisos que necesitas para configurar y controlar la transferencia del linaje de datos, pídele a tu administrador que te otorgue los siguientes roles de Identity and Access Management (IAM):

Para obtener los permisos que necesitas para configurar y controlar la transferencia del linaje de datos, pídele a tu administrador que te otorgue los siguientes roles de IAM en tu proyecto:

• Configura y administra el linaje de datos: Administrador de linaje de datos (roles/datalineage.admin)

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 configurar y controlar la transferencia del 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 configurar y controlar la transferencia del linaje de datos:

• Obtén y actualiza las configuraciones de linaje:
  • datalineage.configs.get
  • datalineage.configs.update

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

1. Habilita la API de datalineage.googleapis.com en tu proyecto de cliente. Para obtener más información, consulta Habilita el linaje de datos.

2. Configura el proyecto del cliente. Para 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 verificar si la transferencia de linaje está habilitada para un recurso o para obtener el valor etag antes de modificar la configuración, recupera la configuración actual.

C#

C#

Antes de probar este ejemplo, sigue las instrucciones de configuración para C# que encontrarás en la guía de inicio rápido de Knowledge Catalog sobre las bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de Knowledge Catalog para C#.

Para autenticarte en Knowledge Catalog, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.

using Google.Cloud.DataCatalog.Lineage.ConfigManagement.V1;

public sealed partial class GeneratedConfigManagementServiceClientSnippets
{
    /// <summary>Snippet for GetConfig</summary>
    /// <remarks>
    /// This snippet has been automatically generated and should be regarded as a code template only.
    /// It will require modifications to work:
    /// - It may require correct/in-range values for request initialization.
    /// - It may require specifying regional endpoints when creating the service client as shown in
    ///   https://cloud.google.com/dotnet/docs/reference/help/client-configuration#endpoint.
    /// </remarks>
    public void GetConfigRequestObject()
    {
        // Create client
        ConfigManagementServiceClient configManagementServiceClient = ConfigManagementServiceClient.Create();
        // Initialize request argument(s)
        GetConfigRequest request = new GetConfigRequest
        {
            ConfigName = ConfigName.FromProjectLocation("[PROJECT]", "[LOCATION]"),
        };
        // Make the request
        Config response = configManagementServiceClient.GetConfig(request);
    }
}

Go

Go

Antes de probar este ejemplo, sigue las instrucciones de configuración para Go que encontrarás en la guía de inicio rápido de Knowledge Catalog sobre las bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de Knowledge Catalog para Go.

Para autenticarte en Knowledge Catalog, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.

//go:build examples

package main

import (
	"context"

	configmanagement "cloud.google.com/go/datacatalog/lineage/configmanagement/apiv1"
	configmanagementpb "cloud.google.com/go/datacatalog/lineage/configmanagement/apiv1/configmanagementpb"
)

func main() {
	ctx := context.Background()
	// This snippet has been automatically generated and should be regarded as a code template only.
	// It will require modifications to work:
	// - It may require correct/in-range values for request initialization.
	// - It may require specifying regional endpoints when creating the service client as shown in:
	//   https://pkg.go.dev/cloud.google.com/go#hdr-Client_Options
	c, err := configmanagement.NewClient(ctx)
	if err != nil {
		// TODO: Handle error.
	}
	defer c.Close()

	req := &configmanagementpb.GetConfigRequest{
		// TODO: Fill request struct fields.
		// See https://pkg.go.dev/cloud.google.com/go/datacatalog/lineage/configmanagement/apiv1/configmanagementpb#GetConfigRequest.
	}
	resp, err := c.GetConfig(ctx, req)
	if err != nil {
		// TODO: Handle error.
	}
	// TODO: Use resp.
	_ = resp
}

Java

Java

Antes de probar este ejemplo, sigue las instrucciones de configuración para Java que encontrarás en la guía de inicio rápido de Knowledge Catalog sobre las bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de Knowledge Catalog para Java.

Para autenticarte en Knowledge Catalog, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.

import com.google.cloud.datacatalog.lineage.configmanagement.v1.Config;
import com.google.cloud.datacatalog.lineage.configmanagement.v1.ConfigManagementServiceClient;
import com.google.cloud.datacatalog.lineage.configmanagement.v1.ConfigName;
import com.google.cloud.datacatalog.lineage.configmanagement.v1.GetConfigRequest;

public class SyncGetConfig {

  public static void main(String[] args) throws Exception {
    syncGetConfig();
  }

  public static void syncGetConfig() throws Exception {
    // This snippet has been automatically generated and should be regarded as a code template only.
    // It will require modifications to work:
    // - It may require correct/in-range values for request initialization.
    // - It may require specifying regional endpoints when creating the service client as shown in
    // https://cloud.google.com/java/docs/setup#configure_endpoints_for_the_client_library
    try (ConfigManagementServiceClient configManagementServiceClient =
        ConfigManagementServiceClient.create()) {
      GetConfigRequest request =
          GetConfigRequest.newBuilder()
              .setName(ConfigName.ofProjectLocationName("[PROJECT]", "[LOCATION]").toString())
              .build();
      Config response = configManagementServiceClient.getConfig(request);
    }
  }
}

Python

Python

Antes de probar este ejemplo, sigue las instrucciones de configuración para Python que encontrarás en la guía de inicio rápido de Knowledge Catalog sobre las bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de Knowledge Catalog para Python.

Para autenticarte en Knowledge Catalog, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.

# This snippet has been automatically generated and should be regarded as a
# code template only.
# It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
#   client as shown in:
#   https://googleapis.dev/python/google-api-core/latest/client_options.html
from google.cloud import datacatalog_lineage_configmanagement_v1


def sample_get_config():
    # Create a client
    client = datacatalog_lineage_configmanagement_v1.ConfigManagementServiceClient()

    # Initialize request argument(s)
    request = datacatalog_lineage_configmanagement_v1.GetConfigRequest(
        name="name_value",
    )

    # Make the request
    response = client.get_config(request=request)

    # Handle the response
    print(response)

gcloud

Para ver la configuración de linaje actual, usa el comando gcloud datalineage config describe. Puedes recuperar la configuración de un proyecto, una organización o una carpeta.

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

gcloud datalineage config describe

Por ejemplo, para obtener la configuración de un proyecto específico, usa la marca --project:

gcloud datalineage config describe --project=PROJECT_ID

Reemplaza lo siguiente:

• PROJECT_ID: Es el ID del proyecto cuya configuración deseas ver.

Para ver la configuración actual de transferencia de linaje de un servicio para una carpeta u organización, reemplaza --project=PROJECT_ID por una de las siguientes opciones:

• --folder=FOLDER_ID si quieres ver la configuración de transferencia de datos de una carpeta.
• --organization=ORGANIZATION_ID si deseas ver la configuración de transferencia de datos de una organización.

REST

Para ver la configuración de linaje actual, 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:

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

• CLIENT_PROJECT_ID: Es el ID del 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.

Método HTTP y URL:

GET https://datalineage.googleapis.com/v1/projects/PROJECT_ID/locations/global/config

Para enviar tu solicitud, expande una de estas opciones:

curl (Linux, macOS o Cloud Shell)

Nota: Con el siguiente comando, se supone que accediste a gcloud CLI con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login , o a través del uso de Cloud Shell, que accede de forma automática a gcloud CLI . Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Ejecuta el siguiente comando:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: CLIENT_PROJECT_ID" \
     "https://datalineage.googleapis.com/v1/projects/PROJECT_ID/locations/global/config"

PowerShell (Windows)

Nota: El siguiente comando supone que accediste a gcloud CLI con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login . Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Ejecuta el siguiente comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "CLIENT_PROJECT_ID" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://datalineage.googleapis.com/v1/projects/PROJECT_ID/locations/global/config" | Select-Object -Expand Content

El comando devuelve uno de los siguientes resultados:

• Si no proporcionas ningún parámetro de configuración de transferencia de linaje, obtendrás un resultado con un objeto ingestion vacío:

  {
    "name": "projects/123456789012/locations/global/config",
    "ingestion": {}
  }
    

  Esto significa que el servicio usa el parámetro de configuración predeterminado de transferencia de linaje. En este ejemplo, el parámetro de configuración de transferencia de linaje para Managed Service para Apache Spark es enabled.

• Si habilitas la transferencia de linaje de forma explícita, obtendrás el siguiente resultado:

  {
    "name": "projects/123456789012/locations/global/config",
    "ingestion": {
      "rules": [
        {
          "integrationSelector": {
            "integration": "DATAPROC"
          },
          "lineageEnablement": {
            "enabled": true
          }
        }
      ]
    },
    "etag": "1a2b3c4d5e"
  }
    

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

  {
    "name": "projects/123456789012/locations/global/config",
    "ingestion": {
      "rules": [
        {
          "integrationSelector": {
            "integration": "DATAPROC"
          },
          "lineageEnablement": {
            "enabled": false
          }
        }
      ]
    },
    "etag": "1a2b3c4d5e"
  }
    

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 campo etag de la respuesta es una suma de comprobación que genera el servidor según el valor actual de la configuración. Cuando actualizas una configuración con el método patch, puedes incluir el valor etag que se muestra de una solicitud get reciente en el cuerpo de la solicitud. Si proporcionas el etag, Knowledge 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 reemplaces de forma involuntaria las configuraciones que realizaron otros usuarios en situaciones de lectura, modificación y escritura. Si no proporcionas un etag en tu solicitud patch, Knowledge Catalog reemplaza la configuración sin condiciones.

Inhabilita la transferencia de linaje para un servicio

Para administrar los costos, aplicar políticas de administración de datos o excluir proyectos de desarrollo y otras cargas de trabajo que no se beneficien del seguimiento del linaje, inhabilita la transferencia de linaje para un servicio.

Java

package com.google.cloud.datacatalog.lineage.configmanagement.v1.samples;

import com.google.api.gax.rpc.NotFoundException;
import com.google.cloud.datacatalog.lineage.configmanagement.v1.Config;
import com.google.cloud.datacatalog.lineage.configmanagement.v1.Config.Ingestion;
import com.google.cloud.datacatalog.lineage.configmanagement.v1.Config.Ingestion.IngestionRule;
import com.google.cloud.datacatalog.lineage.configmanagement.v1.Config.Ingestion.IngestionRule.IntegrationSelector;
import com.google.cloud.datacatalog.lineage.configmanagement.v1.Config.Ingestion.IngestionRule.IntegrationSelector.Integration;
import com.google.cloud.datacatalog.lineage.configmanagement.v1.Config.Ingestion.IngestionRule.LineageEnablement;
import com.google.cloud.datacatalog.lineage.configmanagement.v1.ConfigManagementServiceClient;
import com.google.cloud.datacatalog.lineage.configmanagement.v1.ConfigName;
import com.google.cloud.datacatalog.lineage.configmanagement.v1.GetConfigRequest;
import com.google.cloud.datacatalog.lineage.configmanagement.v1.UpdateConfigRequest;

public class DisableLineageIngestion {

  public static void main(String[] args) throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project-id";
    String location = "global";
    disableLineageIngestion(projectId, location);
  }

  // Disables lineage ingestion for a specific service
  // (Managed Service for Apache Spark).
  public static void disableLineageIngestion(String projectId, String location) throws Exception {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (ConfigManagementServiceClient client = ConfigManagementServiceClient.create()) {
      // Format the resource name.
      String name = ConfigName.ofProjectLocationName(projectId, location).toString();

      Config.Builder configBuilder = Config.newBuilder().setName(name);

      // It is a best practice to read the existing config to preserve other rules
      // and use the etag for optimistic concurrency control.
      try {
        GetConfigRequest getRequest = GetConfigRequest.newBuilder().setName(name).build();
        Config existingConfig = client.getConfig(getRequest);
        configBuilder.mergeFrom(existingConfig);
      } catch (NotFoundException e) {
        // If config doesn't exist, we will proceed by creating a new one.
      }

      // Create an integration selector for the service you want to disable.
      IntegrationSelector selector =
          IntegrationSelector.newBuilder().setIntegration(Integration.DATAPROC).build();

      // Set lineage enablement to false to disable tracking.
      LineageEnablement enablement = LineageEnablement.newBuilder().setEnabled(false).build();

      // Build the ingestion rule.
      IngestionRule disableRule =
          IngestionRule.newBuilder()
              .setIntegrationSelector(selector)
              .setLineageEnablement(enablement)
              .build();

      // Preserve existing rules except for the one we are modifying, then add the new rule.
      // We clear the ingestion block out of the configBuilder entirely to reconstruct it.
      Ingestion.Builder ingestionBuilder = Ingestion.newBuilder();
      if (configBuilder.hasIngestion()) {
        for (IngestionRule rule : configBuilder.getIngestion().getRulesList()) {
          // Keep all existing rules EXCEPT the one targeting DATAPROC
          if (rule.getIntegrationSelector().getIntegration() != Integration.DATAPROC) {
            ingestionBuilder.addRules(rule);
          }
        }
      }
      ingestionBuilder.addRules(disableRule);

      // Update the config builder with the reconstructed ingestion settings.
      configBuilder.setIngestion(ingestionBuilder.build());

      // Build the update request.
      UpdateConfigRequest request = UpdateConfigRequest.newBuilder()
          .setConfig(configBuilder.build())
          .build();

      // Update the config.
      Config response = client.updateConfig(request);
      System.out.printf("Successfully updated config: %s\n", response.getName());
    }
  }
}

Python

from google.api_core.exceptions import NotFound
from google.cloud.datacatalog.lineage import configmanagement_v1

def disable_lineage_ingestion(project_id: str, location: str = "global") -> configmanagement_v1.Config:
    """Disables lineage ingestion for a specific service.

    Args:
        project_id: The ID of your Google Cloud project.
        location: The region location, usually 'global'.

    Returns:
        The updated Configuration object.
    """
    # Initialize client that will be used to send requests.
    client = configmanagement_v1.ConfigManagementServiceClient()

    # The config name format
    name = f"projects/{project_id}/locations/{location}/config"

    try:
        # Retrieve the existing config to preserve other configurations and
        # obtain the latest etag for optimistic concurrency control.
        config = client.get_config(name=name)

        # Filter out existing rules for the integration we are updating
        new_rules = [
            rule for rule in config.ingestion.rules
            if rule.integration_selector.integration != configmanagement_v1.Config.Ingestion.IngestionRule.IntegrationSelector.Integration.DATAPROC
        ]
    except NotFound:
        # If the config does not exist, start fresh
        config = configmanagement_v1.Config(name=name)
        new_rules = []

    # Define the integration to disable tracking for (e.g., DATAPROC).
    integration_selector = configmanagement_v1.Config.Ingestion.IngestionRule.IntegrationSelector(
        integration=configmanagement_v1.Config.Ingestion.IngestionRule.IntegrationSelector.Integration.DATAPROC
    )

    # Set lineage enablement to False to disable tracking.
    lineage_enablement = configmanagement_v1.Config.Ingestion.IngestionRule.LineageEnablement(
        enabled=False
    )

    # Create the ingestion rule.
    disable_rule = configmanagement_v1.Config.Ingestion.IngestionRule(
        integration_selector=integration_selector,
        lineage_enablement=lineage_enablement,
    )
     # Append the new disabling rule and assign it back to the config ingestion rules
    new_rules.append(disable_rule)
    config.ingestion = configmanagement_v1.Config.Ingestion(rules=new_rules)

    # Create the update request using the config (which includes the etag if it existed).
    request = configmanagement_v1.UpdateConfigRequest(
        config=config,
    )

    # Make the request to update the config
    response = client.update_config(request=request)

    print(f"Successfully updated config: {response.name}")
    return response

gcloud

Para inhabilitar la transferencia de linaje de un servicio específico, usa el comando gcloud datalineage config update con una cadena JSON intercalada o una ruta de acceso a un archivo JSON que establezca lineageEnablement.enabled en false para el integration específico.

En el siguiente ejemplo, se muestra cómo inhabilitar la transferencia de linaje de un servicio para un proyecto con una cadena JSON intercalada:

gcloud datalineage config update --project=PROJECT_ID \
  --config='{
    "ingestion": {
      "rules": [
        {
          "integrationSelector": {
            "integration": "INTEGRATION"
          },
          "lineageEnablement": {
            "enabled": false
          }
        }
      ]
    },
    "etag": "ETAG"
  }'

Reemplaza lo siguiente:

• PROJECT_ID: Es el ID del proyecto cuya configuración deseas actualizar.
• INTEGRATION: Es la integración para la que estableces la configuración. Por ejemplo, DATAPROC o BIGQUERY.
• ETAG: Es el valor etag que se muestra de una solicitud get reciente en el cuerpo de la solicitud, que se usa para verificar que la configuración no haya cambiado desde la última solicitud de lectura.

Para actualizar la configuración con un archivo JSON, ejecuta el siguiente comando:

gcloud datalineage config update --project=PROJECT_ID --config=CONFIG_FILE

Reemplaza lo siguiente:

• CONFIG_FILE: Es la ruta de acceso al archivo JSON que contiene la configuración.

Para inhabilitar la transferencia de linaje de un servicio para una carpeta o una organización, reemplaza --project=PROJECT_ID por uno de los siguientes:

• --folder=FOLDER_ID si deseas actualizar la configuración de transferencia de datos de una carpeta.
• --organization=ORGANIZATION_ID si deseas actualizar la configuración de transferencia de datos de una organización.

REST

Para inhabilitar la transferencia de linaje de 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 reemplazar de forma involuntaria las configuraciones que realizaron otros usuarios en situaciones de lectura, modificación y escritura, puedes incluir el campo etag en el cuerpo de la solicitud. Para obtener más información, consulta Obtén la configuración actual.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

• CLIENT_PROJECT_ID: Es el ID del 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 muestra de una solicitud get reciente.
• INTEGRATION: Es el integration para el que estableces la configuración. Por ejemplo, DATAPROC.

HTTP method and URL:

PATCH https://datalineage.googleapis.com/v1/projects/PROJECT_ID/locations/global/config

Cuerpo JSON de la solicitud:

{
  "ingestion": {
    "rules": [
      {
        "integrationSelector": {
          "integration": "INTEGRATION"
        },
        "lineageEnablement": {
          "enabled": false
        }
      }
    ]
  },
  "etag": "ETAG"
}

Para enviar tu solicitud, expande una de estas opciones:

curl (Linux, macOS o Cloud Shell)

Nota: Con el siguiente comando, se supone que accediste a gcloud CLI con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login , o a través del uso de Cloud Shell, que accede de forma automática a gcloud CLI . Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: CLIENT_PROJECT_ID" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://datalineage.googleapis.com/v1/projects/PROJECT_ID/locations/global/config"

PowerShell (Windows)

Nota: El siguiente comando supone que accediste a gcloud CLI con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login . Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "CLIENT_PROJECT_ID" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://datalineage.googleapis.com/v1/projects/PROJECT_ID/locations/global/config" | Select-Object -Expand Content

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

{
  "name": "projects/PROJECT_ID/locations/global/config",
  "ingestion": {
    "rules": [
      {
        "integrationSelector": {
          "integration": "INTEGRATION"
        },
        "lineageEnablement": {
          "enabled": false
        }
      }
    ]
  },
  "etag": "1a2b3c4d5e"
}

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

Habilita la transferencia de linaje para un servicio

Para reanudar el seguimiento después de inhabilitarlo o habilitar una integración que está inhabilitada de forma predeterminada, habilita la transferencia de linaje para un servicio.

Java

package com.google.cloud.datacatalog.lineage.configmanagement.v1.samples;

import com.google.api.gax.rpc.NotFoundException;
import com.google.cloud.datacatalog.lineage.configmanagement.v1.Config;
import com.google.cloud.datacatalog.lineage.configmanagement.v1.Config.Ingestion;
import com.google.cloud.datacatalog.lineage.configmanagement.v1.Config.Ingestion.IngestionRule;
import com.google.cloud.datacatalog.lineage.configmanagement.v1.Config.Ingestion.IngestionRule.IntegrationSelector;
import com.google.cloud.datacatalog.lineage.configmanagement.v1.Config.Ingestion.IngestionRule.IntegrationSelector.Integration;
import com.google.cloud.datacatalog.lineage.configmanagement.v1.Config.Ingestion.IngestionRule.LineageEnablement;
import com.google.cloud.datacatalog.lineage.configmanagement.v1.ConfigManagementServiceClient;
import com.google.cloud.datacatalog.lineage.configmanagement.v1.ConfigName;
import com.google.cloud.datacatalog.lineage.configmanagement.v1.GetConfigRequest;
import com.google.cloud.datacatalog.lineage.configmanagement.v1.UpdateConfigRequest;

public class EnableLineageIngestion {

  public static void main(String[] args) throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project-id";
    String location = "global";
    enableLineageIngestion(projectId, location);
  }

  // Enables lineage ingestion for a specific service
  // (Managed Service for Apache Spark).
  public static void enableLineageIngestion(String projectId, String location) throws Exception {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (ConfigManagementServiceClient client = ConfigManagementServiceClient.create()) {
      // Format the resource name.
      String name = ConfigName.ofProjectLocationName(projectId, location).toString();

      Config.Builder configBuilder = Config.newBuilder().setName(name);

      // It is a best practice to read the existing config to preserve other rules
      // and use the etag for optimistic concurrency control.
      try {
        GetConfigRequest getRequest = GetConfigRequest.newBuilder().setName(name).build();
        Config existingConfig = client.getConfig(getRequest);
        configBuilder.mergeFrom(existingConfig);
      } catch (NotFoundException e) {
        // If config doesn't exist, we will proceed by creating a new one.
      }

      // Create an integration selector for the service you want to enable (e.g., DATAPROC).
      IntegrationSelector selector =
          IntegrationSelector.newBuilder().setIntegration(Integration.DATAPROC).build();

      // Set lineage enablement to true to enable tracking.
      LineageEnablement enablement = LineageEnablement.newBuilder().setEnabled(true).build();

      // Build the ingestion rule.
      IngestionRule enableRule =
          IngestionRule.newBuilder()
              .setIntegrationSelector(selector)
              .setLineageEnablement(enablement)
              .build();

      // Preserve existing rules except for the one we are modifying, then add the new rule.
      // We clear the ingestion block out of the configBuilder entirely to reconstruct it.
      Ingestion.Builder ingestionBuilder = Ingestion.newBuilder();
      if (configBuilder.hasIngestion()) {
        for (IngestionRule rule : configBuilder.getIngestion().getRulesList()) {
          // Keep all existing rules EXCEPT the one targeting DATAPROC
          if (rule.getIntegrationSelector().getIntegration() != Integration.DATAPROC) {
            ingestionBuilder.addRules(rule);
          }
        }
      }
      ingestionBuilder.addRules(enableRule);

      // Update the config builder with the reconstructed ingestion settings.
      configBuilder.setIngestion(ingestionBuilder.build());

      // Build the update request.
      UpdateConfigRequest request = UpdateConfigRequest.newBuilder()
          .setConfig(configBuilder.build())
          .build();

      // Update the config.
      Config response = client.updateConfig(request);
      System.out.printf("Successfully updated config: %s\n", response.getName());
    }
  }
}

Python

from google.api_core.exceptions import NotFound
from google.cloud.datacatalog.lineage import configmanagement_v1

def enable_lineage_ingestion(project_id: str, location: str = "global") -> configmanagement_v1.Config:
    """Enables lineage ingestion for a specific service like Dataproc
    (Managed Service for Apache Spark).

    Args:
        project_id: The ID of your Google Cloud project.
        location: The region location, usually 'global'.

    Returns:
        The updated Configuration object.
    """
    # Initialize client that will be used to send requests.
    client = configmanagement_v1.ConfigManagementServiceClient()

    # The config name format
    name = f"projects/{project_id}/locations/{location}/config"

    try:
        # Retrieve the existing config to preserve other configurations and
        # obtain the latest etag for optimistic concurrency control.
        config = client.get_config(name=name)

        # Filter out existing rules for the integration we are updating
        new_rules = [
            rule for rule in config.ingestion.rules
            if rule.integration_selector.integration != configmanagement_v1.Config.Ingestion.IngestionRule.IntegrationSelector.Integration.DATAPROC
        ]
    except NotFound:
        # If the config does not exist, start fresh
        config = configmanagement_v1.Config(name=name)
        new_rules = []

    # Define the integration to enable tracking for (e.g., DATAPROC).
    integration_selector = configmanagement_v1.Config.Ingestion.IngestionRule.IntegrationSelector(
        integration=configmanagement_v1.Config.Ingestion.IngestionRule.IntegrationSelector.Integration.DATAPROC
    )

    # Set lineage enablement to True to enable tracking.
    lineage_enablement = configmanagement_v1.Config.Ingestion.IngestionRule.LineageEnablement(
        enabled=True
    )

    # Create the ingestion rule.
    enable_rule = configmanagement_v1.Config.Ingestion.IngestionRule(
        integration_selector=integration_selector,
        lineage_enablement=lineage_enablement,
    )

    # Append the new enabling rule and assign it back to the config ingestion rules
    new_rules.append(enable_rule)
    config.ingestion = configmanagement_v1.Config.Ingestion(rules=new_rules)

    # Create the update request using the config (which includes the etag if it existed).
    request = configmanagement_v1.UpdateConfigRequest(
        config=config,
    )

    # Make the request to update the config
    response = client.update_config(request=request)

    print(f"Successfully updated config: {response.name}")
    return response

gcloud

Para habilitar la transferencia de linaje para un servicio específico, usa el comando gcloud datalineage config update con una cadena JSON intercalada o una ruta de acceso a un archivo JSON que establezca lineageEnablement.enabled en true para el integration específico. Las integraciones actuales incluyen Managed Service para Apache Spark, BigQuery y Managed Airflow.

En el siguiente ejemplo, se muestra cómo habilitar la transferencia de linaje de un servicio para un proyecto con una cadena JSON intercalada:

gcloud datalineage config update --project=PROJECT_ID \
  --config='{
    "ingestion": {
      "rules": [
        {
          "integrationSelector": {
            "integration": "INTEGRATION"
          },
          "lineageEnablement": {
            "enabled": true
          }
        }
      ]
    },
    "etag": "ETAG"
  }'

Reemplaza lo siguiente:

• PROJECT_ID: Es el ID del proyecto cuya configuración deseas actualizar.
• INTEGRATION: Es la integración para la que estableces la configuración (por ejemplo, DATAPROC o BIGQUERY).
• ETAG: Es el valor etag que se muestra de una solicitud get reciente en el cuerpo de la solicitud, que se usa para verificar que la configuración no haya cambiado desde la última solicitud de lectura.

Para actualizar la configuración con un archivo JSON, ejecuta el siguiente comando:

gcloud datalineage config update --project=PROJECT_ID --config=CONFIG_FILE

Reemplaza lo siguiente:

• CONFIG_FILE: Es la ruta de acceso al archivo JSON que contiene la configuración.

Para habilitar la transferencia de linaje de un servicio para una carpeta o una organización, reemplaza --project=PROJECT_ID por uno de los siguientes:

• --folder=FOLDER_ID si deseas actualizar la configuración de transferencia de datos de una carpeta.
• --organization=ORGANIZATION_ID si deseas actualizar la configuración de transferencia de datos de una organización.

REST

Para habilitar la transferencia 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.

Para evitar reemplazar de forma involuntaria las configuraciones que realizaron otros usuarios en situaciones de lectura, modificación y escritura, puedes incluir el campo etag en el cuerpo de la solicitud. Para obtener más información, consulta Obtén la configuración actual.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

• CLIENT_PROJECT_ID: Es el ID del 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 muestra de una solicitud get reciente.
• INTEGRATION: Es el integration para el que estableces la configuración. Por ejemplo, DATAPROC.

HTTP method and URL:

PATCH https://datalineage.googleapis.com/v1/projects/PROJECT_ID/locations/global/config

Cuerpo JSON de la solicitud:

{
  "ingestion": {
    "rules": [
      {
        "integrationSelector": {
          "integration": "INTEGRATION"
        },
        "lineageEnablement": {
          "enabled": true
        }
      }
    ]
  },
  "etag": "ETAG"
}

Para enviar tu solicitud, expande una de estas opciones:

curl (Linux, macOS o Cloud Shell)

Nota: Con el siguiente comando, se supone que accediste a gcloud CLI con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login , o a través del uso de Cloud Shell, que accede de forma automática a gcloud CLI . Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: CLIENT_PROJECT_ID" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://datalineage.googleapis.com/v1/projects/PROJECT_ID/locations/global/config"

PowerShell (Windows)

Nota: El siguiente comando supone que accediste a gcloud CLI con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login . Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "CLIENT_PROJECT_ID" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://datalineage.googleapis.com/v1/projects/PROJECT_ID/locations/global/config" | Select-Object -Expand Content

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

{
  "name": "projects/PROJECT_ID/locations/global/config",
  "ingestion": {
    "rules": [
      {
        "integrationSelector": {
          "integration": "INTEGRATION"
        },
        "lineageEnablement": {
          "enabled": true
        }
      }
    ]
  },
  "etag": "1a2b3c4d5e"
}

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

Configura la transferencia de linaje para varios servicios

Para configurar la transferencia de linaje para varias integraciones de forma simultánea, usa los métodos projects.locations.config.patch, folders.locations.config.patch o organizations.locations.config.patch. Puedes actualizar la configuración a nivel de proyecto, carpeta o de organización definiendo varias reglas en el cuerpo de la solicitud. Para obtener más información, consulta Cómo funciona la configuración de transferencia de datos para las integraciones de varios servicios.

Nivel de la organización

Configura la organización para habilitar la transferencia de linaje para Managed Service para Apache Spark:

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "X-Goog-User-Project: CLIENT_PROJECT_ID" \
  "https://datalineage.googleapis.com/v1/organizations/ORGANIZATION_ID/locations/global/config" \
  -d '{
    "ingestion": {
      "rules": [
        {
          "integrationSelector": {
            "integration": "DATAPROC"
          },
          "lineageEnablement": {
            "enabled": true
          }
        }
      ]
    },
    "etag": "ORGANIZATION_CONFIG_ETAG"
  }'

Reemplaza lo siguiente:

• ORGANIZATION_ID: Es el ID de la organización cuya configuración deseas actualizar.
• CLIENT_PROJECT_ID: Es el ID de tu proyecto de cliente que se usa para la facturación o las cuotas.
• ORGANIZATION_CONFIG_ETAG: Es el valor etag que se muestra en una solicitud get reciente para la configuración de la organización.

Nivel de carpeta

Configura la carpeta para habilitar la transferencia de linaje para BigQuery:

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "X-Goog-User-Project: CLIENT_PROJECT_ID" \
  "https://datalineage.googleapis.com/v1/folders/FOLDER_ID/locations/global/config" \
  -d '{
    "ingestion": {
      "rules": [
        {
          "integrationSelector": {
            "integration": "BIGQUERY"
          },
          "lineageEnablement": {
            "enabled": true
          }
        }
      ]
    },
    "etag": "FOLDER_CONFIG_ETAG"
  }'

Reemplaza lo siguiente:

• FOLDER_ID: Es el ID de la carpeta cuya configuración deseas actualizar.
• CLIENT_PROJECT_ID: Es el ID del proyecto de cliente que se usa para la facturación o las cuotas.
• FOLDER_CONFIG_ETAG: Es el valor etag que se muestra de una solicitud get reciente para la configuración de la carpeta.

Nivel de proyecto

Configura el proyecto para Inhabilitar la transferencia de linaje para BigQuery y, al mismo tiempo, Habilitar la transferencia de linaje para Managed Service para Apache Airflow:

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "X-Goog-User-Project: CLIENT_PROJECT_ID" \
  "https://datalineage.googleapis.com/v1/projects/PROJECT_ID/locations/global/config" \
  -d '{
    "ingestion": {
      "rules": [
        {
          "integrationSelector": {
            "integration": "BIGQUERY"
          },
          "lineageEnablement": {
            "enabled": false
          }
        },
        {
          "integrationSelector": {
            "integration": "MANAGED_AIRFLOW"
          },
          "lineageEnablement": {
            "enabled": true
          }
        }
      ]
    },
    "etag": "PROJECT_CONFIG_ETAG"
  }'

Reemplaza lo siguiente:

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

¿Qué sigue?

• Obtén información para controlar la transferencia del linaje de datos.
• Obtén más información para ver la información del linaje.