Pesquisar linhagem multirregional usando automação do lado do servidor

Este documento descreve como pesquisar linhagem de dados multirregional e de vários níveis usando a API searchLineageStreaming.

A API searchLineageStreaming realiza uma pesquisa em largura em uma direção especificada (upstream ou downstream) começando de um conjunto definido de entidades raiz e retorna um gráfico de linhagem unificado como uma resposta de streaming em tempo real.

Para mais informações, consulte Sobre a pesquisa de linhagem multirregional.

Principais recursos

A API searchLineageStreaming inclui os seguintes recursos:

  • Pesquisa em largura: percorre o gráfico de linhagem camada por camada, calculando com precisão a profundidade de cada recurso conectado.

  • Resposta de streaming: retorna subgrafos e links de linhagem à medida que são descobertos pelo sistema de back-end. Isso é altamente eficiente para gráficos de linhagem amplos ou profundos e evita tempos limite de solicitação.

  • Traversal em vários locais e projetos: embora você especifique apenas um projeto de faturamento no caminho da solicitação, a API descobre e percorre automaticamente os links de linhagem em vários projetos do Google Cloud e locais geográficos, desde que você tenha as permissões necessárias.

  • Linhagem refinada no nível da coluna: permite pesquisar dependências no nível da coluna entre recursos.

  • Pesquisas com caractere curinga: permite recuperar toda a linhagem no nível da coluna de uma entidade específica adicionando o sufixo * ao nome totalmente qualificado (FQN).

  • Insights do pipeline: recupera opcionalmente metadados sobre os pipelines de transformação (processos) que criaram os links de linhagem.

Antes de começar

Antes de fazer solicitações à API, verifique se você atende aos seguintes pré-requisitos de segurança e ambiente:

Funções exigidas

Para receber as permissões necessárias para pesquisar links de linhagem de dados, peça ao administrador para conceder a você o papel do IAM Leitor da linhagem de dados (roles/datalineage.viewer) nos projetos em que os links e processos de linhagem estão armazenados. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esse papel predefinido contém as permissões necessárias para pesquisar links de linhagem de dados. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As seguintes permissões são necessárias para pesquisar links de linhagem de dados:

  • Pesquisar linhagem no nível da entidade: datalineage.events.get no projeto em que o link está armazenado
  • Pesquisar linhagem no nível da coluna: datalineage.events.getFields no projeto em que o link está armazenado
  • Recupere os detalhes completos do processo do pipeline: datalineage.processes.get no projeto em que o processo está armazenado

Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.

Escopo de recursos

Ao configurar a solicitação de API, é necessário distinguir entre o recurso usado para faturamento administrativo e os locais reais verificados pela API:

  • Caminho principal de faturamento: o caminho parent na solicitação de URL precisa usar o formato projects/project/locations/location. Esse par específico de projeto e local é usado exclusivamente para avaliar cotas de faturamento e limites de taxa de API.

  • Locais de destino: defina explicitamente as regiões que você quer que o backend verifique na matriz locations dentro do corpo da solicitação.

Configuração da autenticação

Inicialize uma variável de ambiente com um token de acesso Google Cloud para autenticar seus comandos curl:

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

Exemplos de uso

Os exemplos a seguir usam o endpoint datalineage.googleapis.com.

Pesquisar linhagem multinível e de vários projetos

Para executar uma pesquisa de linhagem detalhada que percorre várias profundidades do gráfico e verifica diferentes projetos Google Cloud , defina as seguintes variáveis:

  • Defina limits.maxDepth como a profundidade de navegação desejada (aceita valores de 1 a 100).

  • Preencha a matriz locations com as regiões de destino que você quer que o back-end compare (por exemplo, ["us", "us-east1"]).

C#

C#

Antes de testar esta amostra, siga as instruções de configuração do C# no Guia de início rápido do Knowledge Catalog: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Knowledge Catalog C#.

Para autenticar no Knowledge Catalog, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

using Google.Api.Gax.Grpc;
using Google.Api.Gax.ResourceNames;
using Google.Cloud.DataCatalog.Lineage.V1;
using System.Threading.Tasks;

public sealed partial class GeneratedLineageClientSnippets
{
    /// <summary>Snippet for SearchLineageStreaming</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 async Task SearchLineageStreamingRequestObject()
    {
        // Create client
        LineageClient lineageClient = LineageClient.Create();
        // Initialize request argument(s)
        SearchLineageStreamingRequest request = new SearchLineageStreamingRequest
        {
            ParentAsLocationName = LocationName.FromProjectLocation("[PROJECT]", "[LOCATION]"),
            Locations = { "", },
            RootCriteria = new SearchLineageStreamingRequest.Types.RootCriteria(),
            Direction = SearchLineageStreamingRequest.Types.SearchDirection.Unspecified,
            Filters = new SearchLineageStreamingRequest.Types.SearchFilters(),
            Limits = new SearchLineageStreamingRequest.Types.SearchLimits(),
        };
        // Make the request, returning a streaming response
        using LineageClient.SearchLineageStreamingStream response = lineageClient.SearchLineageStreaming(request);

        // Read streaming responses from server until complete
        // Note that C# 8 code can use await foreach
        AsyncResponseStream<SearchLineageStreamingResponse> responseStream = response.GetResponseStream();
        while (await responseStream.MoveNextAsync())
        {
            SearchLineageStreamingResponse responseItem = responseStream.Current;
            // Do something with streamed response
        }
        // The response stream has completed
    }
}

Java

Java

Antes de testar esta amostra, siga as instruções de configuração do Java no Guia de início rápido do Knowledge Catalog: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Knowledge Catalog Java.

Para autenticar no Knowledge Catalog, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

import com.google.api.gax.rpc.ServerStream;
import com.google.cloud.datacatalog.lineage.v1.LineageClient;
import com.google.cloud.datacatalog.lineage.v1.LocationName;
import com.google.cloud.datacatalog.lineage.v1.SearchLineageStreamingRequest;
import com.google.cloud.datacatalog.lineage.v1.SearchLineageStreamingResponse;
import java.util.ArrayList;

public class AsyncSearchLineageStreaming {

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

  public static void asyncSearchLineageStreaming() 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 (LineageClient lineageClient = LineageClient.create()) {
      SearchLineageStreamingRequest request =
          SearchLineageStreamingRequest.newBuilder()
              .setParent(LocationName.of("[PROJECT]", "[LOCATION]").toString())
              .addAllLocations(new ArrayList<String>())
              .setRootCriteria(SearchLineageStreamingRequest.RootCriteria.newBuilder().build())
              .setFilters(SearchLineageStreamingRequest.SearchFilters.newBuilder().build())
              .setLimits(SearchLineageStreamingRequest.SearchLimits.newBuilder().build())
              .build();
      ServerStream<SearchLineageStreamingResponse> stream =
          lineageClient.searchLineageStreamingCallable().call(request);
      for (SearchLineageStreamingResponse response : stream) {
        // Do something when a response is received.
      }
    }
  }
}

Node.js

Java

Antes de testar esta amostra, siga as instruções de configuração do Java no Guia de início rápido do Knowledge Catalog: como usar bibliotecas de cliente.

Para autenticar no Knowledge Catalog, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento 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.
 * TODO(developer): Uncomment these variables before running the sample.
 */
/**
 *  Required. The project and location to initiate the search from.
 */
// const parent = 'abc123'
/**
 *  Required. The locations to search in.
 */
// const locations = ['abc','def']
/**
 *  Required. Criteria for the root of the search.
 */
// const rootCriteria = {}
/**
 *  Required. Direction of the search.
 */
// const direction = {}
/**
 *  Optional. Filters for the search.
 */
// const filters = {}
/**
 *  Optional. Limits for the search.
 */
// const limits = {}

// Imports the Lineage library
const {LineageClient} = require('@google-cloud/lineage').v1;

// Instantiates a client
const lineageClient = new LineageClient();

async function callSearchLineageStreaming() {
  // Construct request
  const request = {
    parent,
    locations,
    rootCriteria,
    direction,
  };

  // Run request
  const stream = await lineageClient.searchLineageStreaming(request);
  stream.on('data', (response) => { console.log(response) });
  stream.on('error', (err) => { throw(err) });
  stream.on('end', () => { /* API call completed */ });
}

callSearchLineageStreaming();

Python

Python

Antes de testar esta amostra, siga as instruções de configuração do Python no Guia de início rápido do Knowledge Catalog: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Knowledge Catalog Python.

Para autenticar no Knowledge Catalog, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento 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_v1


def sample_search_lineage_streaming():
    # Create a client
    client = datacatalog_lineage_v1.LineageClient()

    # Initialize request argument(s)
    request = datacatalog_lineage_v1.SearchLineageStreamingRequest(
        parent="parent_value",
        locations=["locations_value1", "locations_value2"],
        direction="UPSTREAM",
    )

    # Make the request
    stream = client.search_lineage_streaming(request=request)

    # Handle the response
    for response in stream:
        print(response)

Ruby

Ruby

Antes de testar esta amostra, siga as instruções de configuração do Ruby no Guia de início rápido do Knowledge Catalog: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Knowledge Catalog Ruby.

Para autenticar no Knowledge Catalog, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

require "google/cloud/data_catalog/lineage/v1"

##
# Snippet for the search_lineage_streaming call in the Lineage service
#
# 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/ruby/docs/reference.
#
# This is an auto-generated example demonstrating basic usage of
# Google::Cloud::DataCatalog::Lineage::V1::Lineage::Client#search_lineage_streaming.
#
def search_lineage_streaming
  # Create a client object. The client can be reused for multiple calls.
  client = Google::Cloud::DataCatalog::Lineage::V1::Lineage::Client.new

  # Create a request. To set request fields, pass in keyword arguments.
  request = Google::Cloud::DataCatalog::Lineage::V1::SearchLineageStreamingRequest.new

  # Call the search_lineage_streaming method to start streaming.
  output = client.search_lineage_streaming request

  # The returned object is a streamed enumerable yielding elements of type
  # ::Google::Cloud::DataCatalog::Lineage::V1::SearchLineageStreamingResponse
  output.each do |current_response|
    p current_response
  end
end

REST

Para pesquisar linhagem de dados, use o método searchLineageStreaming.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o ID do seu Google Cloud projeto usado para faturamento administrativo e avaliação de cota.
  • LOCATION_ID: o local Google Cloud , como us-central1.
  • SOURCE_PROJECT_ID: o ID do projeto Google Cloud em que a tabela de origem está localizada.
  • DATASET_ID: o ID do conjunto de dados do BigQuery.
  • TABLE_ID: o ID da tabela do BigQuery.

Método HTTP e URL:

POST https://datalineage.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID:searchLineageStreaming

Corpo JSON da solicitação:

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

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante a esta:

{
  "links": [
    {
      "source": {
        "fullyQualifiedName": "bigquery:project-prod.dataset.source_table"
      },
      "target": {
        "fullyQualifiedName": "bigquery:project-prod.dataset.target_table"
      },
      "depth": 1,
      "location": "us"
    }
  ]
}

Pesquisar várias localizações geográficas

É possível limitar ou expandir a verificação do gráfico de linhagem modificando as regiões geográficas transmitidas no campo de matriz repetida locations.

Exemplo:

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

Por padrão, a API omite as informações do processo (maxProcessPerLink é definido como 0). Para recuperar os nomes de recursos dos pipelines que criaram seus links de dados, configure limits.maxProcessPerLink como um número inteiro positivo diferente de zero.

Exemplo:

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

Comportamento da resposta: o fluxo resultante preenche o campo links[].processes com mensagens de processo que contêm apenas o nome absoluto do recurso do sistema (como projects/my-project/locations/us/processes/my-process).

Recuperar detalhes completos do processo usando um FieldMask

Se você precisar de metadados estruturais completos sobre um pipeline (como displayName, attributes do sistema ou origin de execução) em vez de apenas o nome do recurso, use uma API FieldMask:

  1. Forneça um valor diferente de zero para limits.maxProcessPerLink.

  2. Adicione um parâmetro de consulta fields ao caminho do URL, especificando links.processes.process e outros campos obrigatórios.

Exemplo:

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

Pesquisar linhagem no nível da tabela e da coluna

É possível pesquisar a linhagem no nível da tabela (recurso) e da coluna (campo) em uma única solicitação fornecendo várias entidades na lista rootCriteria.entities.entities:

  • Para linhagem no nível da tabela, omita a matriz field.

  • Para linhagem no nível da coluna, especifique uma única coluna na matriz field.

Exemplo:

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

Usar caracteres curinga para linhagem no nível da coluna

Para pesquisar toda a linhagem disponível no nível da coluna de uma tabela específica sem listar cada coluna individualmente, use o caractere curinga * como o único valor na matriz field.

Exemplo:

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

Filtrar resultados de linhagem

É possível refinar os resultados da pesquisa de linhagem usando o bloco filters no corpo da solicitação.

Filtrar por tipo de dependência

Para restringir os resultados a tipos específicos de dependência, como cópias diretas (EXACT_COPY) ou transformações como filtragem e agrupamento (OTHER), use o filtro dependencyTypes.

Exemplo:

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

Restringir à linhagem somente de tabela

Para garantir que a pesquisa retorne apenas a linhagem no nível da tabela e exclua completamente a linhagem no nível da coluna, defina o filtro entitySet como ENTITIES.

Exemplo:

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

Filtrar por período

É possível restringir os resultados da pesquisa de linhagem a um intervalo de tempo específico.

Por exemplo, para pesquisar dados de linhagem criados após uma data/hora específica, use a seguinte solicitação:

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

Processar locais inacessíveis (resultados parciais)

Como a API de streaming faz verificações em um conjunto distribuído de projetos e locais simultaneamente, algumas regiões remotas podem ficar temporariamente inativas, sem comunicação ou mal configuradas durante a execução.

Para proteger a integridade dos dados, o stream searchLineageStreamingResponse contém um campo de diagnóstico dedicado chamado unreachable:

  • Nome do campo: unreachable (representado como uma string repetida)

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

A seguir