Multiregionale Herkunft mithilfe der serverseitigen Automatisierung durchsuchen

In diesem Dokument wird beschrieben, wie Sie mit der searchLineageStreaming API die mehrstufige, regionsübergreifende Datenherkunft suchen.

Die searchLineageStreaming API führt eine Breitensuche in einer bestimmten Richtung (Upstream oder Downstream) aus, beginnend mit einer definierten Gruppe von Stamm-Entities. Sie gibt einen einheitlichen Herkunftsdiagramm als Streaming-Antwort in Echtzeit zurück.

Weitere Informationen finden Sie unter Informationen zur regionsübergreifenden Suche nach Herkunft.

Hauptmerkmale

Die searchLineageStreaming API bietet die folgenden Funktionen:

  • Breitensuche: Durchläuft das Herkunftsdiagramm Ebene für Ebene, berechnet genau die Tiefe jedes verbundenen Assets.

  • Streaming-Antwort: Gibt Unterdiagramme und Herkunftslinks zurück, sobald sie vom Back-End-System gefunden werden. Dies ist sehr effizient für breite oder tiefe Herkunftsdiagramme und verhindert Zeitüberschreitungen bei Anfragen.

  • Durchlaufen mehrerer Standorte und Projekte: Obwohl Sie im Anfragepfad nur ein Abrechnungsprojekt angeben, erkennt und durchläuft die API automatisch Herkunftslinks in mehreren Google Cloud Projekten und geografischen Standorten, sofern Sie die erforderlichen Berechtigungen haben.

  • Detaillierte Herkunft auf Spaltenebene: Unterstützt die Suche nach Abhängigkeiten auf Spaltenebene zwischen Assets.

  • Platzhaltersuchen: Ermöglicht es Ihnen, die gesamte Herkunft auf Spaltenebene für eine bestimmte Entität abzurufen, indem Sie den vollständig qualifizierten Namen (Fully Qualified Name, FQN) mit * ergänzen.

  • Pipeline-Einblicke: Ruft optional Metadaten zu den Transformations pipelines (Prozessen) ab, die die Herkunftslinks erstellt haben.

Hinweis

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

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die Data Lineage Viewer (roles/datalineage.viewer) IAM-Rolle für die Projekte zu gewähren, in denen die Herkunftslinks und -prozesse gespeichert sind, um die Berechtigungen zu erhalten, die Sie zum Suchen nach Datenherkunftslinks 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 Datenherkunftslinks erforderlich sind. Maximieren Sie den Abschnitt Erforderliche Berechtigungen , um die notwendigen Berechtigungen anzuzeigen, die erforderlich sind:

Erforderliche Berechtigungen

Zum Suchen nach Datenherkunftslinks sind die folgenden Berechtigungen erforderlich:

  • Herkunft auf Entitätsebene suchen: datalineage.events.get für das Projekt, in dem der Link gespeichert ist
  • Herkunft auf Spaltenebene suchen: datalineage.events.getFields für das Projekt, in dem der Link gespeichert ist
  • Vollständige Details zum Pipelineprozess abrufen: datalineage.processes.get für das Projekt, in dem der Prozess gespeichert ist

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 für die administrative Abrechnung und den tatsächlichen Standorten unterscheiden, die von der API gescannt werden:

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

  • Zielstandorte: Definieren Sie die Regionen, die vom Back-End gescannt werden sollen, 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 Herkunft in mehreren Projekten suchen

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

  • Legen Sie limits.maxDepth auf die gewünschte Durchlaufstiefe fest (Werte von 1 bis 100 sind zulässig).

  • Füllen Sie das Array locations mit den Zielregionen, die vom Back-End abgeglichen werden sollen (z. B. ["us", "us-east1"]).

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", "us-east1", "us-central1"],
  "rootCriteria": {
    "entities": {
      "entities": [{
        "fullyQualifiedName": "bigquery:project-prod.dataset.source_table"
      }]
    }
  },
  "direction": "DOWNSTREAM",
  "limits": {
    "maxDepth": 10,
    "maxResults": 5000
  }
}'

Mehrere geografische Standorte suchen

Sie können den Scan Ihres Herkunftsdiagramms 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"
}'

Standardmäßig werden Prozessinformationen von der API ausgelassen (maxProcessPerLink ist standardmäßig auf 0 gesetzt). Wenn Sie die Ressourcennamen der Pipelines abrufen möchten, die Ihre Datenlinks erstellt haben, legen Sie limits.maxProcessPerLink auf eine positive Ganzzahl ungleich null fest.

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: Der resultierende Stream füllt das Feld links[].processes mit Prozessnachrichten, die nur ihren absoluten Systemressourcennamen enthalten (z. B. projects/my-project/locations/us/processes/my-process).

Vollständige Prozessdetails mit einer FieldMask abrufen

Wenn Sie anstelle des Ressourcennamens vollständige strukturelle Metadaten zu einer Pipeline benötigen (z. B. displayName, Systemattributes oder origin der Ausführung), müssen Sie eine API-FieldMask verwenden:

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

  2. Hängen Sie einen Abfrageparameter fields an den URL-Pfad an und geben Sie links.processes.process zusammen mit anderen erforderlichen Feldern an.

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

Herkunft auf Tabellen- und Spaltenebene suchen

Sie können in einer einzigen Anfrage sowohl die Herkunft auf Tabellen- (Assetebene) als auch auf Spaltenebene (Feldebene) suchen, indem Sie mehrere Entitäten in der Liste rootCriteria.entities.entities angeben:

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

  • Geben Sie für die Herkunft auf Spaltenebene eine einzelne Spalte im Array field 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 der gesamten verfügbaren Herkunft 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"
     }'

Herkunftsergebnisse filtern

Sie können Ihre Herkunftssuchergebnisse mit dem Block filters 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 Herkunft nur auf Tabellenebene beschränken

Wenn Sie sicherstellen möchten, dass die Suche nur die Herkunft auf Tabellenebene zurückgibt und die Herkunft auf Spaltenebene vollständig ausschließt, 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 Herkunftssuchergebnisse auf ein bestimmtes Zeitintervall beschränken.

Wenn Sie beispielsweise nach Herkunftsdaten 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 scannt, sind einige Remote-Regionen während der Ausführung möglicherweise vorübergehend nicht verfügbar, nicht erreichbar oder falsch konfiguriert.

Zum Schutz der Datenintegrität enthält der Stream searchLineageStreamingResponse 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