Cercare la derivazione multiregionale utilizzando l'automazione lato server

L'API searchLineageStreaming consente di cercare la derivazione dei dati multilivello e tra regioni e di ricevere un grafico unificato come stream in tempo reale. Puoi creare strumenti che attraversano architetture di dati ampie, profonde o multiprogetto senza timeout delle richieste. Per saperne di più, consulta Informazioni sulla ricerca della derivazione multiregionale.

Funzionalità chiave

L'API searchLineageStreaming include le seguenti funzionalità:

  • Ricerca in ampiezza: attraversa il grafico della derivazione livello per livello a monte o a valle di un insieme definito di entità base, calcolando con precisione la profondità di ogni asset collegato.

  • Risposta in streaming: fornisce risposte in tempo reale e suddivise in blocchi contenenti sottografi e link di derivazione man mano che il sistema di backend li rileva. A differenza delle API di ricerca della derivazione standard che potrebbero scadere su grafici multiprogetto di grandi dimensioni, lo streaming impedisce i timeout delle richieste su grafici ampi o profondi.

  • Attraversamento di più località e progetti: anche se specifichi un solo progetto di fatturazione nel percorso della richiesta, l'API rileva e attraversa automaticamente i link di derivazione in più progetti e località geografiche Google Cloud , a condizione che tu disponga delle autorizzazioni richieste.

  • Derivazione granulare a livello di colonna: supporta la ricerca di dipendenze a livello di colonna tra gli asset.

  • Ricerche con caratteri jolly: consente di recuperare tutta la derivazione a livello di colonna per un'entità specifica aggiungendo il suffisso * al nome completo (FQN).

  • Insight sulla pipeline: (facoltativo) recupera i metadati sulle pipeline di trasformazione (processi) che hanno creato i link di derivazione.

Prima di iniziare

Prima di inviare richieste all'API, assicurati di aver soddisfatto i seguenti prerequisiti di sicurezza e ambientali:

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per cercare i link di derivazione dei dati, chiedi all'amministratore di concederti il ruolo IAM Visualizzatore derivazione dati (roles/datalineage.viewer) nei progetti in cui sono archiviati i link e i processi di derivazione. Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Questo ruolo predefinito contiene le autorizzazioni necessarie per cercare i link di derivazione dei dati. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

Per cercare i link di derivazione dei dati sono necessarie le seguenti autorizzazioni:

  • Cerca la derivazione a livello di entità: datalineage.events.get sul progetto in cui è archiviato il link
  • Ricerca della derivazione a livello di colonna: datalineage.events.getFields sul progetto in cui è archiviato il link
  • Recupera i dettagli completi del processo della pipeline: datalineage.processes.get sul progetto in cui è archiviato il processo

Potresti anche ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.

Ambito delle risorse

Quando configuri la richiesta API, devi distinguere tra la risorsa utilizzata per la fatturazione amministrativa e le località effettive analizzate dall'API:

  • Percorso principale di fatturazione: il percorso parent nella richiesta URL deve utilizzare il formato projects/project/locations/location. Questa specifica coppia progetto-località viene utilizzata esclusivamente per valutare le quote di fatturazione e i limiti di frequenza delle API.

  • Località target: definisci esplicitamente le regioni che vuoi che il backend analizzi nell'array locations all'interno del corpo della richiesta.

Configurazione dell'autenticazione

Inizializza una variabile di ambiente con un token di accesso Google Cloud per autenticare i comandi curl:

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

Esempi di utilizzo

I seguenti esempi utilizzano l'endpoint datalineage.googleapis.com.

Cerca la derivazione multilivello e multiprogetto

Per eseguire una ricerca di derivazione approfondita che attraversa più livelli del grafico ed esegue la scansione di progetti Google Cloud distinti, definisci le seguenti variabili:

  • Imposta limits.maxDepth sulla profondità di attraversamento target (accetta valori da 1 a 100).

  • Compila l'array locations con le regioni di destinazione con cui vuoi che il backend faccia un controllo incrociato (ad esempio, ["us", "us-east1"]).

C#

C#

Prima di provare questo esempio, segui le istruzioni di configurazione di C# nella guida rapida di Data Lineage per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Data Lineage C#.

Per eseguire l'autenticazione in Data Lineage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale. 

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

Prima di provare questo esempio, segui le istruzioni di configurazione di Java nella guida rapida di Data Lineage per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Data Lineage Java.

Per eseguire l'autenticazione in Data Lineage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale. 

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

Prima di provare questo esempio, segui le istruzioni di configurazione di Node.js nella guida rapida di Data Lineage per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Data Lineage Node.js.

Per eseguire l'autenticazione in Data Lineage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale. 

/**
 * 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

Prima di provare questo esempio, segui le istruzioni di configurazione di Python nella guida rapida di Data Lineage per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Data Lineage Python.

Per eseguire l'autenticazione in Data Lineage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale. 

# 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

Prima di provare questo esempio, segui le istruzioni di configurazione di Ruby nella guida rapida di Data Lineage per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Data Lineage Ruby.

Per eseguire l'autenticazione in Data Lineage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale. 

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

Per cercare la derivazione dei dati, utilizza il metodo searchLineageStreaming.

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • PROJECT_ID: l'ID progetto Google Cloud utilizzato per la fatturazione amministrativa e la valutazione della quota.
  • LOCATION_ID: la località Google Cloud , ad esempio us-central1.
  • SOURCE_PROJECT_ID: l'ID progetto Google Cloud in cui si trova la tabella di origine.
  • DATASET_ID: l'ID del set di dati BigQuery.
  • TABLE_ID: l'ID tabella BigQuery.

Metodo HTTP e URL: 

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

Corpo JSON della richiesta: 

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

Per inviare la richiesta, espandi una di queste opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

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

Cerca più posizioni geografiche

Puoi limitare o espandere l'analisi del grafico di derivazione modificando le regioni geografiche passate all'interno del campo dell'array ripetuto locations.

C#

C#

Prima di provare questo esempio, segui le istruzioni di configurazione di C# nella guida rapida di Data Lineage per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Data Lineage C#.

Per eseguire l'autenticazione in Data Lineage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale. 

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

Prima di provare questo esempio, segui le istruzioni di configurazione di Java nella guida rapida di Data Lineage per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Data Lineage Java.

Per eseguire l'autenticazione in Data Lineage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale. 

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

Prima di provare questo esempio, segui le istruzioni di configurazione di Java nella guida rapida di Data Lineage per l'utilizzo delle librerie client.

Per eseguire l'autenticazione in Data Lineage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale. 

/**
 * 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

Prima di provare questo esempio, segui le istruzioni di configurazione di Python nella guida rapida di Data Lineage per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Data Lineage Python.

Per eseguire l'autenticazione in Data Lineage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale. 

# 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

Prima di provare questo esempio, segui le istruzioni di configurazione di Ruby nella guida rapida di Data Lineage per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Data Lineage Ruby.

Per eseguire l'autenticazione in Data Lineage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale. 

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

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • PROJECT_ID: l'ID progetto Google Cloud utilizzato per la fatturazione amministrativa e la valutazione della quota.
  • LOCATION_ID: la località Google Cloud , ad esempio us-central1.
  • SOURCE_PROJECT_ID: l'ID progetto Google Cloud in cui si trova la tabella di origine.
  • DATASET_ID: l'ID del set di dati BigQuery.
  • TABLE_ID: l'ID tabella BigQuery.

Metodo HTTP e URL: 

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

Corpo JSON della richiesta: 

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

Per inviare la richiesta, espandi una di queste opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

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

Per impostazione predefinita, l'API omette le informazioni sul processo (maxProcessPerLink ha come valore predefinito 0). Per recuperare i nomi delle risorse delle pipeline che hanno creato i tuoi link ai dati, configura limits.maxProcessPerLink su un numero intero positivo diverso da zero.

Ad esempio:

Java

Java

Prima di provare questo esempio, segui le istruzioni di configurazione di Java nella guida rapida di Data Lineage per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Data Lineage Java.

Per eseguire l'autenticazione in Data Lineage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale. 

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

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • BILLING_PROJECT_ID: il progetto Google Cloud utilizzato per la fatturazione amministrativa e la valutazione della quota. Fornisci un numero di progetto o un ID progetto.
  • LOCATION_ID: la località Google Cloud in cui viene eseguita la ricerca della derivazione.
  • FULLY_QUALIFIED_NAME: il nome completo (FQN) dell'entità di destinazione, nel formato bigquery:PROJECT_ID.DATASET_ID.TABLE_ID.

Metodo HTTP e URL: 

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

Corpo JSON della richiesta: 

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

Per inviare la richiesta, espandi una di queste opzioni:

 

Comportamento della risposta: lo stream risultante compila il campo links[].processes con i messaggi di processo contenenti solo il nome della risorsa di sistema assoluto (ad esempio projects/my-project/locations/us/processes/my-process).

Recupera i dettagli completi del processo utilizzando un FieldMask

Se hai bisogno di metadati strutturali completi su una pipeline (come displayName, attributes di sistema o origin di esecuzione) anziché solo del nome della risorsa, devi utilizzare un'API FieldMask:

  1. Fornisci un valore diverso da zero per limits.maxProcessPerLink.

  2. Aggiungi un parametro di query fields al percorso dell'URL, specificando links.processes.process insieme ad altri campi obbligatori.

Ad esempio:

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

Cerca la derivazione sia a livello di tabella che di colonna

Puoi cercare la derivazione sia a livello di tabella (a livello di asset) sia a livello di colonna (a livello di campo) in un'unica richiesta fornendo più entità nell'elenco rootCriteria.entities.entities:

  • Per la derivazione a livello di tabella, ometti l'array field.

  • Per la derivazione a livello di colonna, specifica una singola colonna nell'array field.

Ad esempio:

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

Utilizza i caratteri jolly per la derivazione a livello di colonna

Per cercare tutta la derivazione a livello di colonna disponibile per una tabella specifica senza elencare ogni colonna singolarmente, utilizza il carattere jolly * come singolo valore nell'array field.

Ad esempio:

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

Filtra i risultati della derivazione

Puoi perfezionare i risultati di ricerca della derivazione utilizzando il blocco filters nel corpo della richiesta.

Filtra per tipo di dipendenza

Per limitare i risultati a tipi di dipendenza specifici, come copie dirette (EXACT_COPY) o trasformazioni come filtri e raggruppamenti (OTHER), utilizza il filtro dependencyTypes.

Ad esempio:

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

Per assicurarti che la ricerca restituisca solo la derivazione a livello di tabella ed escluda completamente la derivazione a livello di colonna, imposta il filtro entitySet su ENTITIES.

Ad esempio:

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

Filtra per intervallo di tempo

Puoi limitare i risultati di ricerca della derivazione a un intervallo di tempo specifico.

Ad esempio, per cercare i dati di lignaggio creati dopo una specifica data e ora, utilizzare la seguente richiesta:

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

Risoluzione dei problemi: gestione di località non raggiungibili e grafici parziali

Poiché l'API di streaming esegue la scansione di un insieme distribuito di progetti e località contemporaneamente, alcune regioni remote potrebbero essere temporaneamente inattive, non comunicative o configurate in modo errato durante l'esecuzione.

  • Sintomo: il layout del grafico di derivazione restituito sembra incompleto o mancano gli hop regionali previsti.

  • Diagnostica: per proteggere l'integrità dei dati, lo stream searchLineageStreamingResponse compila un campo unreachable dedicato (stringa ripetuta) con le località problematiche, utilizzando il formato projects/PROJECT_NUMBER/locations/LOCATION (ad esempio, projects/123456789/locations/us-east1).

  • Best practice: crea sempre le tue applicazioni client per ispezionare il campo unreachable per verificare la completezza dei dati prima di elaborare il grafico.

Passaggi successivi