Cercare la derivazione multiregionale utilizzando l'automazione lato server

Questo documento descrive come cercare la derivazione dei dati multiregionale e multilivello 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 genealogia livello per livello, calcolando con precisione la profondità di ogni asset collegato.

  • Risposta in streaming: restituisce i sottografi e i link di derivazione man mano che vengono scoperti dal sistema di backend. Questo metodo è molto efficiente per grafici di derivazione 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 derivazione in più progetti e località geografiche, a condizione che tu disponga delle autorizzazioni richieste. Google Cloud

  • Derivazione 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 derivazione a livello di colonna per un'entità specifica aggiungendo il suffisso * al nome completo (FQN).

  • Informazioni sulle pipeline: recupera facoltativamente i metadati relativi alle 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) 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 nel progetto in cui è memorizzato il collegamento
  • Cerca la derivazione a livello di colonna: datalineage.events.getFields nel progetto in cui è archiviato il collegamento
  • 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.

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 genitore 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 derivazione che attraversa più livelli del grafico ed esegue la scansione di progetti distinti, definisci le seguenti variabili: Google Cloud

  • 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"]).

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

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

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 FieldMask

Se hai bisogno di metadati strutturali completi su una pipeline (come displayName, attributes o origin) 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 derivazione 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 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"
     }'

Utilizzare 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 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 alla derivazione solo delle tabelle

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

Filtrare per intervallo di tempo

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

Ad esempio, per cercare dati di derivazione 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