Multiregionale Herkunft mithilfe der serverseitigen Automatisierung durchsuchen

In diesem Dokument wird beschrieben, wie Sie mit der searchLineageStreaming API den Datenursprung auf mehreren Ebenen und regionenübergreifend abrufen.

Die searchLineageStreaming-API führt eine Breitensuche in einer angegebenen Richtung (Upstream oder Downstream) aus, die mit einer definierten Gruppe von Stamm-Entitäten beginnt, und gibt ein einheitliches Abstammungsdiagramm als Echtzeit-Streaming-Antwort zurück.

Weitere Informationen finden Sie unter Mehrregionale Herkunftssuche.

Hauptmerkmale

Die searchLineageStreaming API bietet folgende Funktionen:

• Breitensuche: Durchläuft das Lineage-Diagramm Ebene für Ebene und berechnet die Tiefe jedes verbundenen Assets genau.

• Streamingantwort: Gibt Untergraphen und Herkunftsinformationen zurück, sobald sie vom Back-End-System erkannt werden. Dies ist sehr effizient für breite oder tiefe Abstammungsdiagramme und verhindert Zeitüberschreitungen bei Anfragen.

• Traversierung über mehrere Standorte und Projekte hinweg: Obwohl Sie im Anfragepfad nur ein Abrechnungsprojekt angeben, werden Herkunftsinformationen automatisch über mehrere Google Cloud Projekte und geografische Standorte hinweg ermittelt und traversiert, sofern Sie die erforderlichen Berechtigungen haben.

• Detaillierte Herkunft auf Spaltenebene: Ermöglicht die Suche nach Abhängigkeiten auf Spaltenebene zwischen Assets.

• Platzhaltersuchen: Damit können Sie die gesamte Data Lineage auf Spaltenebene für eine bestimmte Entität abrufen, indem Sie den voll qualifizierten Namen (Fully Qualified Name, FQN) mit * ergänzen.

• Pipeline-Insights: Ruft optional Metadaten zu den Transformationspipelines (Prozessen) ab, mit denen die Herkunftsinformationen erstellt wurden.

Hinweis

Bevor Sie Anfragen an die API senden, müssen die folgenden Sicherheits- und Umgebungsanforderungen erfüllt sein:

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die IAM-Rolle Data Lineage Viewer (roles/datalineage.viewer) für die Projekte zuzuweisen, in denen die Herkunftsinformationen und Prozesse gespeichert sind, damit Sie die Berechtigungen erhalten, die Sie zum Suchen nach Herkunftsinformationen benötigen. Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Diese vordefinierte Rolle enthält die Berechtigungen, die zum Suchen nach Links zum Datenursprung erforderlich sind. Maximieren Sie den Abschnitt Erforderliche Berechtigungen, um die notwendigen Berechtigungen anzuzeigen:

Sie können diese Berechtigungen auch mit benutzerdefinierten Rollen oder anderen vordefinierten Rollen erhalten.

Ressourcenbereich

Wenn Sie Ihre API-Anfrage konfigurieren, müssen Sie zwischen der Ressource, die für die administrative Abrechnung verwendet wird, und den tatsächlichen Standorten unterscheiden, die von der API gescannt werden:

• Übergeordneter Abrechnungspfad: Der parent-Pfad in der URL-Anfrage muss das Format projects/project/locations/location verwenden. Dieses bestimmte Projekt-Standort-Paar wird ausschließlich zur Auswertung von Abrechnungskontingenten und API-Ratenbeschränkungen verwendet.

• Zielorte: Definieren Sie die Regionen, die das Backend scannen soll, explizit im Array locations im Anfragetext.

Authentifizierung einrichten

Initialisieren Sie eine Umgebungsvariable mit einem Google Cloud -Zugriffstoken, um Ihre curl-Befehle zu authentifizieren:

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

Beispiele für die Verwendung

In den folgenden Beispielen wird der Endpunkt datalineage.googleapis.com verwendet.

Mehrstufige, projektübergreifende Lineage durchsuchen

Wenn Sie eine detaillierte Herkunftssuche ausführen möchten, die mehrere Ebenen des Diagramms durchläuft und verschiedene Google Cloud Projekte durchsucht, definieren Sie die folgenden Variablen:

• Legen Sie limits.maxDepth auf die gewünschte Tiefe für die Pfadsuche fest (zulässige Werte: 1 bis 100).

• Füllen Sie das Array locations mit den Zielregionen, die vom Backend abgeglichen werden sollen (z. B. ["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"
    }
  ]
}

Nach mehreren geografischen Standorten suchen

Sie können den Scan des Herkunftsgraphen einschränken oder erweitern, indem Sie die geografischen Regionen ändern, die im wiederholten Arrayfeld locations übergeben werden.

Beispiel:

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

Prozessnamen für Herkunftsinformationen abrufen

Standardmäßig werden Prozessinformationen von der API ausgelassen (maxProcessPerLink wird standardmäßig auf 0 gesetzt). Wenn Sie die Ressourcennamen der Pipelines abrufen möchten, mit denen Ihre Datenverknüpfungen erstellt wurden, konfigurieren Sie limits.maxProcessPerLink auf eine positive Ganzzahl ungleich null.

Beispiel:

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

Antwortverhalten: Im resultierenden Stream wird das Feld links[].processes mit Prozessmeldungen gefüllt, die nur den absoluten Systemressourcennamen enthalten (z. B. projects/my-project/locations/us/processes/my-process).

Vollständige Prozessdetails mit einer FieldMask abrufen

Wenn Sie vollständige strukturelle Metadaten zu einer Pipeline benötigen, z. B. displayName, System-attributes oder Ausführungs-origin, anstatt nur den Ressourcennamen, müssen Sie eine API-FieldMask verwenden:

1. Geben Sie für limits.maxProcessPerLink einen Wert ungleich null an.

2. Hängen Sie dem URL-Pfad einen fields-Suchparameter an, in dem Sie links.processes.process sowie andere erforderliche Felder angeben.

Beispiel:

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

Sowohl die Herkunft auf Tabellen- als auch auf Spaltenebene durchsuchen

Sie können in einer einzelnen Anfrage sowohl die Herkunft auf Tabellenebene (Asset-Ebene) als auch auf Spaltenebene (Feldebene) abrufen, indem Sie mehrere Entitäten in der Liste rootCriteria.entities.entities angeben:

• Lassen Sie das field-Array für die Zeilen auf Tabellenebene weg.

• Geben Sie für den Datenursprung auf Spaltenebene eine einzelne Spalte im field-Array an.

Beispiel:

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

Platzhalter für die Herkunft auf Spaltenebene verwenden

Wenn Sie nach dem gesamten Lineage auf Spaltenebene für eine bestimmte Tabelle suchen möchten, ohne jede Spalte einzeln aufzulisten, verwenden Sie das Platzhalterzeichen * als einzelnen Wert im Array field.

Beispiel:

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

Lineage-Ergebnisse filtern

Sie können die Ergebnisse Ihrer Herkunftssuche mit dem filters-Block im Anfragetext verfeinern.

Nach Abhängigkeitstyp filtern

Wenn Sie die Ergebnisse auf bestimmte Abhängigkeitstypen beschränken möchten, z. B. direkte Kopien (EXACT_COPY) oder Transformationen wie Filtern und Gruppieren (OTHER), verwenden Sie den Filter dependencyTypes.

Beispiel:

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

Auf Tabellenzeilen beschränken

Damit bei der Suche nur die Herkunft auf Tabellenebene zurückgegeben und die Herkunft auf Spaltenebene vollständig ausgeschlossen wird, setzen Sie den Filter entitySet auf ENTITIES.

Beispiel:

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

Nach Zeitraum filtern

Sie können die Suchergebnisse für den Datenursprung auf ein bestimmtes Zeitintervall beschränken.

Wenn Sie beispielsweise nach Lineage-Daten suchen möchten, die nach einem bestimmten Zeitstempel erstellt wurden, verwenden Sie die folgende Anfrage:

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

Umgang mit nicht erreichbaren Standorten (Teilergebnisse)

Da die Streaming-API gleichzeitig eine verteilte Gruppe von Projekten und Standorten durchsucht, sind einige Remote-Regionen während der Ausführung möglicherweise vorübergehend nicht verfügbar, nicht kommunikativ oder falsch konfiguriert.

Zum Schutz der Datenintegrität enthält der searchLineageStreamingResponse-Stream ein spezielles Diagnosefeld namens unreachable:

• Feldname: unreachable (als wiederholter String dargestellt)

• Wertformat: projects/PROJECT_NUMBER/locations/LOCATION (z. B. projects/123456789/locations/us-east1)

Nächste Schritte

• Weitere Informationen zur Suche nach Herkunft in mehreren Regionen

• Weitere Informationen zur Datenherkunft

• Weitere Informationen zur Visualisierung des Datenursprungs