Rechercher la traçabilité multirégionale à l'aide de l'automatisation côté serveur

Ce document explique comment rechercher le lineage des données multirégionales et à plusieurs niveaux à l'aide de l'API searchLineageStreaming.

L'API searchLineageStreaming effectue une recherche en largeur dans une direction spécifiée (en amont ou en aval) à partir d'un ensemble défini d'entités racines, et renvoie un graphique de traçabilité unifié sous forme de réponse de streaming en temps réel.

Pour en savoir plus, consultez À propos de la recherche de traçabilité multirégionale.

Capacités clés

L'API searchLineageStreaming inclut les fonctionnalités suivantes :

• Recherche en largeur : parcourt le graphique de traçabilité couche par couche, en calculant précisément la profondeur de chaque élément connecté.

• Réponse en streaming : renvoie les sous-graphiques et les liens de traçabilité au fur et à mesure de leur découverte par le système backend. Cette méthode est très efficace pour les graphiques de traçabilité larges ou profonds, et elle empêche les délais d'expiration des requêtes.

• Parcours multi-emplacements et multi-projets : bien que vous ne spécifiiez qu'un seul projet de facturation dans le chemin de requête, l'API découvre et parcourt automatiquement les liens de traçabilité dans plusieurs projets Google Cloud et zones géographiques, à condition que vous disposiez des autorisations requises.

• Traçabilité précise au niveau des colonnes : permet de rechercher les dépendances au niveau des colonnes entre les composants.

• Recherches avec caractères génériques : vous permettent de récupérer l'intégralité de la traçabilité au niveau des colonnes pour une entité spécifique en ajoutant le suffixe * au nom complet (FQN).

• Insights sur les pipelines : récupère éventuellement les métadonnées sur les pipelines de transformation (processus) qui ont créé les liens de traçabilité.

Avant de commencer

Avant d'envoyer des requêtes à l'API, assurez-vous de remplir les conditions préalables de sécurité et d'environnement suivantes :

Rôles requis

Pour obtenir les autorisations nécessaires pour rechercher des liens de traçabilité des données, demandez à votre administrateur de vous accorder le rôle IAM Lecteur de traçabilité des données (roles/datalineage.viewer) sur les projets dans lesquels sont stockés les liens et les processus de traçabilité. Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Ce rôle prédéfini contient les autorisations requises pour rechercher des liens de traçabilité des données. Pour connaître les autorisations exactes requises, développez la section Autorisations requises :

Vous pouvez également obtenir ces autorisations avec des rôles personnalisés ou d'autres rôles prédéfinis.

Définition du champ d'application des ressources

Lorsque vous configurez votre requête d'API, vous devez faire la distinction entre la ressource utilisée pour la facturation administrative et les emplacements réels analysés par l'API :

• Chemin parent de facturation : le chemin parent dans la requête d'URL doit utiliser le format projects/project/locations/location. Cette paire projet/emplacement spécifique est utilisée exclusivement pour évaluer les quotas de facturation et les limites de fréquence de l'API.

• Emplacements cibles : définissez explicitement les régions que vous souhaitez que le backend analyse dans le tableau locations du corps de la requête.

Configuration de l'authentification

Initialisez une variable d'environnement avec un jeton d'accès Google Cloud pour authentifier vos commandes curl :

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

Exemples d'utilisation

Les exemples suivants utilisent le point de terminaison datalineage.googleapis.com.

Rechercher la traçabilité multi-niveaux et multiprojets

Pour exécuter une recherche d'ascendance détaillée qui traverse plusieurs profondeurs du graphique et analyse différents projets Google Cloud , définissez les variables suivantes :

• Définissez limits.maxDepth sur la profondeur de parcours cible (accepte les valeurs comprises entre 1 et 100).

• Renseignez le tableau locations avec les régions cibles que vous souhaitez que le backend croise (par exemple, ["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"
    }
  ]
}

Rechercher plusieurs zones géographiques

Vous pouvez limiter ou étendre l'analyse de votre graphique de traçabilité en modifiant les régions géographiques transmises dans le champ de tableau répété locations.

Exemple :

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

Récupérer les noms de processus pour les liens de traçabilité

Par défaut, l'API omet les informations sur le processus (maxProcessPerLink est défini sur 0 par défaut). Pour récupérer les noms de ressources des pipelines qui ont créé vos associations de données, définissez limits.maxProcessPerLink sur un entier positif non nul.

Exemple :

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

Comportement de la réponse : le flux obtenu remplit le champ links[].processes avec des messages de processus contenant uniquement leur nom de ressource système absolu (tel que projects/my-project/locations/us/processes/my-process).

Récupérer les détails complets du processus à l'aide d'un FieldMask

Si vous avez besoin de métadonnées structurelles complètes sur un pipeline (telles que son displayName, son attributes système ou son origin d'exécution) au lieu de son nom de ressource, vous devez utiliser une API FieldMask :

1. Indiquez une valeur non nulle pour limits.maxProcessPerLink.

2. Ajoutez un paramètre de requête fields au chemin d'URL, en spécifiant links.processes.process ainsi que les autres champs obligatoires.

Exemple :

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

Rechercher la traçabilité au niveau des tables et des colonnes

Vous pouvez rechercher la traçabilité au niveau des tables (au niveau des assets) et des colonnes (au niveau des champs) dans une même requête en fournissant plusieurs entités dans la liste rootCriteria.entities.entities :

• Pour la traçabilité au niveau de la table, omettez le tableau field.

• Pour la traçabilité au niveau des colonnes, spécifiez une seule colonne dans le tableau field.

Exemple :

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

Utiliser des caractères génériques pour la traçabilité au niveau des colonnes

Pour rechercher l'intégralité de la traçabilité au niveau des colonnes disponibles pour une table spécifique sans lister chaque colonne individuellement, utilisez le caractère générique * comme valeur unique dans le tableau field.

Exemple :

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

Filtrer les résultats de l'analyse de l'origine

Vous pouvez affiner les résultats de recherche sur la traçabilité en utilisant le bloc filters dans le corps de la requête.

Filtrer par type de dépendance

Pour limiter les résultats à des types de dépendances spécifiques, tels que les copies directes (EXACT_COPY) ou les transformations comme le filtrage et le regroupement (OTHER), utilisez le filtre dependencyTypes.

Exemple :

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

Restreindre la traçabilité aux tables uniquement

Pour vous assurer que la recherche ne renvoie que la traçabilité au niveau des tables et exclut complètement la traçabilité au niveau des colonnes, définissez le filtre entitySet sur ENTITIES.

Exemple :

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

Filtrer par période

Vous pouvez limiter les résultats de recherche de traçabilité à un intervalle de temps spécifique.

Par exemple, pour rechercher des données de traçabilité créées après un code temporel spécifique, utilisez la requête suivante :

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

Gérer les emplacements inaccessibles (résultats partiels)

Étant donné que l'API de streaming analyse simultanément un ensemble distribué de projets et de régions, il est possible que certaines régions distantes soient temporairement indisponibles, non communicatives ou mal configurées lors de l'exécution.

Pour protéger l'intégrité des données, le flux searchLineageStreamingResponse contient un champ de diagnostic dédié appelé unreachable :

• Nom du champ : unreachable (représenté sous forme de chaîne répétée)

• Format de la valeur : projects/PROJECT_NUMBER/locations/LOCATION (par exemple, projects/123456789/locations/us-east1)

Étapes suivantes

• En savoir plus sur la recherche de traçabilité multirégionale

• En savoir plus sur la traçabilité des données

• En savoir plus sur la visualisation de la traçabilité