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

A API searchLineageStreaming permite que você consulte a linhagem de dados multinível e inter-regional e receba um gráfico unificado como um stream em tempo real. É possível criar ferramentas que percorrem arquiteturas de dados amplas, profundas ou de vários projetos sem tempos limite de solicitação. Para mais informações, consulte Sobre a pesquisa de linhagem multirregional.

Principais recursos

A API searchLineageStreaming inclui os seguintes recursos:

  • Pesquisa em largura: atravessa o gráfico de linhagem camada por camada upstream ou downstream de um conjunto definido de entidades raiz, calculando com precisão a profundidade de cada recurso conectado.

  • Resposta de streaming: fornece respostas em tempo real e em partes, contendo subgráficos e links de linhagem à medida que o sistema de back-end os descobre. Ao contrário das APIs de pesquisa de linhagem padrão, que podem expirar em grandes gráficos multiprojetos, o streaming evita tempos limite de solicitação em gráficos amplos ou profundos.

  • Travessia de vários locais e projetos: embora você especifique apenas um projeto de faturamento no caminho da solicitação, a API descobre e atravessa 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 detalhada no nível da coluna: permite pesquisar dependências no nível da coluna entre recursos.

  • Pesquisas com caracteres curinga: permite recuperar toda a linhagem no nível da coluna de uma entidade específica adicionando o sufixo * ao nome totalmente qualificado (FQN, na sigla em inglês).

  • Insights de 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ê atendeu aos seguintes pré-requisitos de segurança e ambientais:

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 de Leitor de 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
  • Recuperar detalhes completos do processo de 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, é preciso distinguir entre o recurso usado para faturamento administrativo e os locais reais verificados pela API:

  • Caminho pai 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.

  • Regiões de segmentação: defina explicitamente as regiões que você quer que o back-end 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 do 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 de vários níveis e projetos

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

  • Defina limits.maxDepth como a profundidade de travessia 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 da linhagem de dados: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Data Lineage C#.

Para autenticar na linhagem de dados, 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 da linhagem de dados: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Data Lineage Java.

Para autenticar na linhagem de dados, 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

Node.js

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

Para autenticar na linhagem de dados, 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 da linhagem de dados: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Data Lineage Python.

Para autenticar na linhagem de dados, 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 da linhagem de dados: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Data Lineage Ruby.

Para autenticar na linhagem de dados, 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 a 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 projeto do Google Cloud usado para faturamento administrativo e avaliação de cotas.
  • LOCATION_ID: o local do Google Cloud , como us-central1.
  • SOURCE_PROJECT_ID: o ID do projeto do 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.

C#

C#

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

Para autenticar na linhagem de dados, 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 da linhagem de dados: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Data Lineage Java.

Para autenticar na linhagem de dados, 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 da linhagem de dados: como usar bibliotecas de cliente.

Para autenticar na linhagem de dados, 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 da linhagem de dados: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Data Lineage Python.

Para autenticar na linhagem de dados, 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 da linhagem de dados: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Data Lineage Ruby.

Para autenticar na linhagem de dados, 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

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

  • PROJECT_ID: o ID do projeto do Google Cloud usado para faturamento administrativo e avaliação de cotas.
  • LOCATION_ID: o local do Google Cloud , como us-central1.
  • SOURCE_PROJECT_ID: o ID do projeto do 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"
    }
  ]
}

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 os links de dados, configure limits.maxProcessPerLink como um número inteiro positivo diferente de zero.

Exemplo:

Java

Java

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

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

import com.google.cloud.datacatalog.lineage.v1.LineageClient;
import com.google.cloud.datacatalog.lineage.v1.Process;
import com.google.cloud.datacatalog.lineage.v1.ProcessName;

public class SyncGetProcessProcessname {

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

  public static void syncGetProcessProcessname() 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()) {
      ProcessName name = ProcessName.of("[PROJECT]", "[LOCATION]", "[PROCESS]");
      Process response = lineageClient.getProcess(name);
    }
  }
}

REST

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

  • BILLING_PROJECT_ID: o projeto do Google Cloud usado para faturamento administrativo e avaliação de cotas. Informe um número ou ID do projeto.
  • LOCATION_ID: o local do Google Cloud em que a pesquisa de linhagem é realizada.
  • FULLY_QUALIFIED_NAME: o nome totalmente qualificado (FQN) da entidade de destino, no formato bigquery:PROJECT_ID.DATASET_ID.TABLE_ID.

Método HTTP e URL: 

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

Corpo JSON da solicitação:

{
  "parent": "projects/BILLING_PROJECT_ID/locations/LOCATION_ID",
  "locations": [
    "LOCATION_ID"
  ],
  "rootCriteria": {
    "entities": {
      "entities": [
        {
          "fullyQualifiedName": "FULLY_QUALIFIED_NAME"
        }
      ]
    }
  },
  "direction": "UPSTREAM",
  "limits": {
    "maxProcessPerLink": 5
  }
}

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

 

Comportamento da resposta: o stream 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 uma 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 FieldMask de API:

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

  2. Anexe um parâmetro de consulta fields ao caminho do URL, especificando links.processes.process com 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 (nível do recurso) e da coluna (nível do 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 para 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 de dependência específicos, 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"]
       }
     }'

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 um carimbo de data/hora específico, 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"
         }
       }
     }'

Solução de problemas: lidar com locais inacessíveis e gráficos parciais

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

  • Sintoma: o layout do gráfico de linhagem retornado parece incompleto ou não tem os saltos regionais esperados.

  • Diagnóstico: para proteger a integridade de dados, o stream searchLineageStreamingResponse preenche um campo unreachable dedicado (string repetida) com locais problemáticos, usando o formato projects/PROJECT_NUMBER/locations/LOCATION (por exemplo, projects/123456789/locations/us-east1).

  • Prática recomendada: sempre crie seus aplicativos cliente para inspecionar o campo unreachable e verificar se os dados estão completos antes de processar o gráfico.

A seguir