Cercare la derivazione multiregionale utilizzando l'automazione lato server

Questo documento descrive come cercare la tracciabilità dei dati multilivello e interregionale utilizzando l'API searchLineageStreaming.

L'API searchLineageStreaming esegue una ricerca in ampiezza in una direzione specificata (a monte o a valle) a partire da un insieme definito di entità radice e restituisce un grafico di derivazione unificato come risposta di streaming in tempo reale.

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 tracciabilità livello per livello, calcolando con precisione la profondità di ogni asset collegato.

• Risposta in streaming: restituisce i sottografi e i link di tracciabilità man mano che vengono scoperti dal sistema di backend. Questo metodo è molto efficiente per grafici di tracciabilità ampi o profondi e impedisce i timeout delle richieste.

• 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 tracciabilità in più progetti e località geografiche, a condizione che tu disponga delle autorizzazioni richieste. Google Cloud

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

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

• Approfondimenti sulle pipeline: recupera facoltativamente i metadati sulle pipeline di trasformazione (processi) che hanno creato i link di derivazione.

Prima di iniziare

Prima di effettuare 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 dei dati (roles/datalineage.viewer) sui 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:

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

Definizione dell'ambito delle risorse

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

• Percorso principale di fatturazione: il percorso parent nella richiesta URL deve utilizzare il formato projects/project/locations/location. Questa coppia progetto-posizione specifica 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 esamini 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

Gli esempi riportati di seguito utilizzano l'endpoint datalineage.googleapis.com.

Cercare la derivazione multilivello e multiprogetto

Per eseguire una ricerca approfondita della tracciabilità che attraversa più livelli del grafo 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 che vuoi che il backend esegua un controllo incrociato (ad esempio, ["us", "us-east1"]).

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

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

/**
 * 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();

# 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)

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

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

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

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://datalineage.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID:searchLineageStreaming"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

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

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

Cercare più località geografiche

Puoi limitare o espandere la scansione del grafico di derivazione modificando le regioni geografiche trasmesse all'interno del campo array ripetuto locations.

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

Recuperare i nomi dei processi per i link di derivazione

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

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 \
--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 della risposta: il flusso 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).

Recuperare i dettagli completi del processo utilizzando una maschera di campo

Se hai bisogno di metadati strutturali completi su una pipeline (come displayName, attributes di sistema o origin di esecuzione) anziché solo il 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 a livello di tabella e di colonna

Puoi cercare la tracciabilità sia a livello di tabella (asset) sia a livello di colonna (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 tracciabilità 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"
     }'

Utilizzare i caratteri jolly per la tracciabilità a livello di colonna

Per cercare tutta la tracciabilità a livello di colonna disponibile per una tabella specifica senza elencare ogni colonna singolarmente, utilizza il carattere jolly * come unico 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"
     }'

Filtrare i risultati della derivazione

Puoi perfezionare i risultati della 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 il filtraggio e il raggruppamento (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"]
       }
     }'

Limita la tracciabilità solo alle tabelle

Per assicurarti che la ricerca restituisca solo la tracciabilità a livello di tabella ed escluda completamente la tracciabilità 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"
       }
     }'

Filtrare per intervallo di tempo

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

Ad esempio, per cercare dati di tracciabilità creati dopo un timestamp specifico, utilizza 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"
         }
       }
     }'

Gestire le località non raggiungibili (risultati parziali)

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

Per proteggere l'integrità dei dati, lo stream searchLineageStreamingResponse contiene un campo diagnostico dedicato chiamato unreachable:

• Nome campo: unreachable (rappresentato come stringa ripetuta)

• Formato del valore: projects/PROJECT_NUMBER/locations/LOCATION (ad esempio, projects/123456789/locations/us-east1)

Passaggi successivi

• Scopri di più sulla ricerca della derivazione multiregionale.

• Scopri di più sulla tracciabilità dei dati.

• Scopri di più sulla visualizzazione della tracciabilità.