Affichez la traçabilité des données pour comprendre les relations entre les ressources de votre projet et les processus qui les ont créées. Ces relations montrent comment les éléments de données, tels que les tables et les ensembles de données, sont transformés par des processus tels que les requêtes et les pipelines. Ce guide explique comment afficher les détails de la traçabilité des données dans la console Google Cloud ou les récupérer à l'aide de l'API Data Lineage.
Rôles et autorisations
La traçabilité des données suit automatiquement les informations de traçabilité lorsque vous activez l'API Data Lineage. Vous n'avez besoin d'aucun rôle d'administrateur ni d'éditeur pour capturer la traçabilité de vos éléments de données.
Pour afficher la traçabilité des données, vous devez disposer d'autorisations Identity and Access Management (IAM) spécifiques. Les informations sur la traçabilité sont capturées dans plusieurs projets. Vous devez donc disposer d'autorisations dans plusieurs projets.
Lorsque vous consultez la traçabilité dans Knowledge Catalog, BigQuery ou Vertex AI, vous avez besoin d'autorisations pour afficher les informations de traçabilité dans le projet dans lequel vous les consultez.
Lorsque vous consultez la traçabilité enregistrée dans d'autres projets : vous devez disposer des autorisations nécessaires pour afficher les informations de traçabilité dans les projets où il a été enregistré.
Pour obtenir les autorisations nécessaires pour afficher la traçabilité des données, demandez à votre administrateur de vous accorder les rôles IAM suivants :
- Lecteur de la traçabilité des données (
roles/datalineage.viewer) sur le projet dans lequel la traçabilité est enregistrée et sur celui dans lequel elle est consultée -
Affichez les détails de la table BigQuery :
Lecteur de données BigQuery (
roles/bigquery.dataViewer) sur le projet de stockage de la table. -
Afficher les détails d'un job BigQuery :
Lecteur de ressources BigQuery (
roles/bigquery.resourceViewer) sur le projet de calcul du job -
Afficher les détails des autres éléments catalogués : Lecteur de catalogue Dataplex (
roles/dataplex.catalogViewer) sur le projet dans lequel les entrées de catalogue sont stockées
Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.
Ces rôles prédéfinis contiennent les autorisations requises pour afficher la traçabilité des données. Pour connaître les autorisations exactes requises, développez la section Autorisations requises :
Autorisations requises
Les autorisations suivantes sont requises pour afficher la traçabilité des données :
-
Affichez les détails de la table BigQuery :
bigquery.tables.get: projet de stockage de la table -
Afficher les détails du job BigQuery :
bigquery.jobs.get: projet de calcul du job
Vous pouvez également obtenir ces autorisations avec des rôles personnalisés ou d'autres rôles prédéfinis.
Types de vues de traçabilité des données
Vous pouvez afficher les informations sur la traçabilité sous forme de graphique interactif ou de liste structurée dans la console Google Cloud .
Pour obtenir une description détaillée des éléments du graphique (tels que les nœuds, les arêtes, les icônes de processus et les libellés) et des colonnes disponibles dans les vues Liste, consultez À propos de la visualisation de la traçabilité des données dans Knowledge Catalog.
Activer la traçabilité des données
Activez la traçabilité des données pour commencer à suivre automatiquement les informations de traçabilité pour les systèmes compatibles. Par défaut, l'activation de l'API active le suivi de la traçabilité pour la plupart des services compatibles. Pour contrôler l'ingestion de la traçabilité Managed Service pour Apache Spark, consultez Contrôler l'ingestion de la traçabilité pour un service.
L'API Data Lineage est facturée sous le SKU de traitement premium Knowledge Catalog. Pour en savoir plus, consultez les tarifs de Knowledge Catalog.
Vous devez activer l'API Data Lineage à la fois dans le projet où vous consultez la traçabilité et dans les projets où elle est enregistrée. Pour en savoir plus, consultez Types de projets.
- Pour capturer des informations sur la traçabilité, procédez comme suit :
-
Dans la console Google Cloud , sur la page Sélecteur de projet, sélectionnez le projet dans lequel vous souhaitez enregistrer la traçabilité.
Activez l'API Data Lineage.
- Répétez les étapes précédentes pour chaque projet dans lequel vous souhaitez enregistrer la traçabilité.
-
Dans le projet dans lequel vous consultez la traçabilité, activez l'API Data Lineage et l'API Dataplex.
Contrôler l'ingestion de la traçabilité pour un service
Vous pouvez activer ou désactiver sélectivement le suivi automatique de la traçabilité pour des services spécifiques au niveau du projet, du dossier ou de l'organisation.
Pour en savoir plus sur la façon dont ces configurations sont appliquées de manière hiérarchique dans l'arborescence des ressources, consultez Contrôler l'ingestion de l'historique.
Afficher la traçabilité
Pour suivre la façon dont les données sont transformées et déplacées dans les systèmes, vous pouvez afficher la traçabilité des données à l'aide de la console Google Cloud ou de l'API.
Console
Vous pouvez accéder aux informations sur la lignée des données dans la console Google Cloud à partir de différents points de départ :
- Knowledge Catalog : accédez à la page Rechercher de Knowledge Catalog, sélectionnez Knowledge Catalog comme mode de recherche, recherchez l'entrée que vous souhaitez afficher, puis cliquez dessus. Pour en savoir plus, consultez Rechercher des ressources dans Knowledge Catalog.
- BigQuery : accédez à la page BigQuery et ouvrez la table pour laquelle vous souhaitez afficher la traçabilité des données.
- Vertex AI : accédez à la page Ensembles de données ou Model Registry, puis cliquez sur l'ensemble de données ou le modèle pour lequel vous souhaitez afficher la traçabilité des données.
Pour afficher le graphique de traçabilité, procédez comme suit :
Cliquez sur l'onglet Traçabilité.
La vue Graphique par défaut s'ouvre et affiche la traçabilité au niveau de la table dans les systèmes et les régions. Pour en savoir plus, consultez Vue Graphique de traçabilité.
Pour explorer manuellement le graphique de traçabilité, cliquez sur Développer à côté d'un nœud pour charger cinq nœuds supplémentaires à la fois.
Pour en savoir plus, consultez Explorer manuellement le graphique de traçabilité.
Cliquez sur un nœud dans la vue Graphique.
Le panneau Détails s'ouvre et affiche des informations sur l'élément, comme son nom complet et son type. Pour en savoir plus, consultez Détails du nœud.
Dans la vue Graphique, cliquez sur une arête comportant une icône de processus.
Le panneau Requête s'ouvre. Pour en savoir plus, consultez Inspecter la logique de transformation et Audit et historique des exécutions.
- Pour inspecter la logique de transformation, cliquez sur l'onglet Détails.
- Pour afficher l'audit et l'historique des exécutions, cliquez sur l'onglet Exécutions.
Dans le panneau Explorateur de traçabilité, sélectionnez des critères de filtre (par exemple, Direction, Type de dépendance ou Période), puis cliquez sur Appliquer.
Une vue ciblée s'ouvre dans une région spécifique (preview). Cette vue développe automatiquement le graphique jusqu'à trois niveaux de nœuds. Pour en savoir plus, consultez Appliquer des filtres pour afficher une vue ciblée de la traçabilité.
Dans la vue Graphique ciblée, sélectionnez un nœud, puis, dans le panneau d'informations du nœud, cliquez sur Visualiser le chemin pour visualiser le chemin de traçabilité du nœud sélectionné jusqu'à l'entrée racine (uniquement dans la vue ciblée).
Pour en savoir plus, consultez Visualisation du chemin de traçabilité.
Pour afficher la traçabilité au niveau des colonnes (uniquement pour les jobs BigQuery et Managed Service pour Apache Spark), procédez comme suit :
- Dans une vue Graphique ciblée, cliquez sur l'icône de colonne d'une table.
Icône Colonnes - Dans le panneau Explorateur de traçabilité, filtrez par nom de colonne, puis cliquez sur Appliquer.
Pour en savoir plus, consultez Traçabilité au niveau des colonnes.
- Dans une vue Graphique ciblée, cliquez sur l'icône de colonne d'une table.
Cliquez sur Réinitialiser.
Cette action supprime tous les filtres appliqués et vous ramène au début de la vue graphique.
Cliquez sur Liste pour passer à la vue Liste.
La vue Liste propose des représentations tabulaires simplifiées et détaillées de la traçabilité au niveau des tables et des colonnes, synchronisées avec la vue Graphique. Par défaut, la vue Liste simplifiée est affichée. Vous pouvez passer à la vue Liste détaillée pour analyser les relations source-cible individuelles. Vous pouvez configurer les colonnes affichées et exporter les données de traçabilité. Pour en savoir plus, consultez Vue Liste de la traçabilité.
Java
import com.google.api.gax.rpc.ApiException;
import com.google.cloud.datacatalog.lineage.v1.BatchSearchLinkProcessesRequest;
import com.google.cloud.datacatalog.lineage.v1.EntityReference;
import com.google.cloud.datacatalog.lineage.v1.EventLink;
import com.google.cloud.datacatalog.lineage.v1.LineageClient;
import com.google.cloud.datacatalog.lineage.v1.LineageEvent;
import com.google.cloud.datacatalog.lineage.v1.Link;
import com.google.cloud.datacatalog.lineage.v1.ListLineageEventsRequest;
import com.google.cloud.datacatalog.lineage.v1.ListRunsRequest;
import com.google.cloud.datacatalog.lineage.v1.LocationName;
import com.google.cloud.datacatalog.lineage.v1.ProcessLinks;
import com.google.cloud.datacatalog.lineage.v1.Run;
import com.google.cloud.datacatalog.lineage.v1.SearchLinksRequest;
import java.io.IOException;
import java.util.ArrayList;
import java.util.HashSet;
import java.util.LinkedList;
import java.util.List;
import java.util.Queue;
import java.util.Set;
public class ViewLineageExample {
public static void main(String[] args) throws IOException {
// TODO(developer): Replace these variables before running the sample.
String projectId = "my-project-id";
String location = "us";
String targetFullyQualifiedName = "bigquery:my-project-id.my_dataset.my_table";
int maxDepth = 3;
viewLineage(projectId, location, targetFullyQualifiedName, maxDepth);
}
static class Node {
String fqn;
int depth;
Node(String fqn, int depth) {
this.fqn = fqn;
this.depth = depth;
}
}
public static void viewLineage(
String projectId, String location, String targetFullyQualifiedName, int maxDepth)
throws IOException {
// Initialize client that will be used to send requests. This client only needs
// to be created once, and can be reused for multiple requests.
try (LineageClient client = LineageClient.create()) {
String parent = LocationName.of(projectId, location).toString();
Set<String> visitedNodes = new HashSet<>();
Queue<Node> queue = new LinkedList<>();
visitedNodes.add(targetFullyQualifiedName);
queue.offer(new Node(targetFullyQualifiedName, 0));
while (!queue.isEmpty()) {
Node current = queue.poll();
System.out.printf("\nExploring node (Depth %d): %s\n", current.depth, current.fqn);
if (current.depth >= maxDepth) {
continue;
}
EntityReference targetEntity =
EntityReference.newBuilder().setFullyQualifiedName(current.fqn).build();
SearchLinksRequest searchLinksRequest =
SearchLinksRequest.newBuilder().setParent(parent).setTarget(targetEntity).build();
List<String> linkNames = new ArrayList<>();
try {
// 1. Search for links related to the target entity
for (Link link : client.searchLinks(searchLinksRequest).iterateAll()) {
linkNames.add(link.getName());
}
} catch (ApiException e) {
System.out.printf(" Failed to retrieve links for %s: %s\n", current.fqn, e.getMessage());
continue;
}
if (linkNames.isEmpty()) {
continue;
}
// 2. Batch search for processes in chunks of 100
for (int i = 0; i < linkNames.size(); i += 100) {
List<String> batch = linkNames.subList(i, Math.min(linkNames.size(), i + 100));
BatchSearchLinkProcessesRequest batchSearchRequest =
BatchSearchLinkProcessesRequest.newBuilder()
.setParent(parent)
.addAllLinks(batch)
.build();
try {
for (ProcessLinks processLinks :
client.batchSearchLinkProcesses(batchSearchRequest).iterateAll()) {
String processName = processLinks.getProcess();
System.out.printf(" Process: %s\n", processName);
// 3. List runs for the process
ListRunsRequest runsRequest =
ListRunsRequest.newBuilder().setParent(processName).build();
for (Run run : client.listRuns(runsRequest).iterateAll()) {
System.out.printf(" Run: %s\n", run.getName());
// 4. List events for the run
ListLineageEventsRequest eventsRequest =
ListLineageEventsRequest.newBuilder().setParent(run.getName()).build();
for (LineageEvent event : client.listLineageEvents(eventsRequest).iterateAll()) {
for (EventLink eventLink : event.getLinksList()) {
String sourceFqn = eventLink.getSource().getFullyQualifiedName();
// If exploring upstream, queue the source
if (!sourceFqn.isEmpty() && !visitedNodes.contains(sourceFqn)) {
visitedNodes.add(sourceFqn);
queue.offer(new Node(sourceFqn, current.depth + 1));
}
}
}
}
}
} catch (ApiException e) {
System.out.printf(" Failed to retrieve processes/runs: %s\n", e.getMessage());
}
}
}
}
}
}
Python
from google.cloud import datacatalog_lineage_v1
from google.api_core.exceptions import GoogleAPICallError
def view_lineage(project_id: str, location: str, target_fully_qualified_name: str, max_depth: int = 3):
"""Retrieves lineage for a given entity using a depth-limited search."""
client = datacatalog_lineage_v1.LineageClient()
parent = f"projects/{project_id}/locations/{location}"
# Store visited nodes to avoid infinite loops in cyclic graphs
visited_nodes = set([target_fully_qualified_name])
queue = [(target_fully_qualified_name, 0)]
while queue:
current_node, current_depth = queue.pop(0)
print(f"\nExploring node (Depth {current_depth}): {current_node}")
if current_depth >= max_depth:
continue
target_entity = datacatalog_lineage_v1.EntityReference(
fully_qualified_name=current_node
)
search_links_request = datacatalog_lineage_v1.SearchLinksRequest(
parent=parent,
target=target_entity,
)
try:
links = list(client.search_links(request=search_links_request))
except GoogleAPICallError as e:
print(f" Failed to retrieve links for {current_node}: {e.message}")
continue
if not links:
continue
# Extract link names to query processes in batches
link_names = [link.name for link in links]
# Batch max size is 100
for i in range(0, len(link_names), 100):
batch = link_names[i:i + 100]
batch_request = datacatalog_lineage_v1.BatchSearchLinkProcessesRequest(
parent=parent,
links=batch
)
try:
for process_links in client.batch_search_link_processes(request=batch_request):
process_name = process_links.process
print(f" Process: {process_name}")
runs_request = datacatalog_lineage_v1.ListRunsRequest(parent=process_name)
for run in client.list_runs(request=runs_request):
print(f" Run: {run.name}")
events_request = datacatalog_lineage_v1.ListLineageEventsRequest(parent=run.name)
for event in client.list_lineage_events(request=events_request):
for event_link in event.links:
source_fqn = event_link.source.fully_qualified_name
# If exploring upstream, queue the source
if source_fqn and source_fqn not in visited_nodes:
visited_nodes.add(source_fqn)
queue.append((source_fqn, current_depth + 1))
except GoogleAPICallError as e:
print(f" Failed to retrieve processes/runs: {e.message}")
Affiner la visualisation de la traçabilité
Pour affiner la visualisation de la traçabilité, vous pouvez utiliser les options de mise en surbrillance et de filtrage dans l'explorateur de traçabilité :
Pour rechercher des projets, des ensembles de données ou des noms d'entités spécifiques, utilisez le panneau Filtres.
Une fois les filtres appliqués, les nœuds de traçabilité qui correspondent à vos critères de filtrage sont considérés comme des nœuds correspondants. Vous pouvez affiner l'affichage des nœuds correspondants et non correspondants.
Dans le graphique de lignée, cliquez sur l'icône Autres actions située à côté du bouton Effacer les filtres pour afficher les options d'affichage.
Sélectionnez l'une des options suivantes, ou les deux :
Vous pouvez sélectionner les deux options en même temps. Si les deux options sont sélectionnées, les nœuds non filtrés sont masqués et les nœuds correspondants sont mis en surbrillance dans la vue filtrée du graphique.
Désactiver la traçabilité des données
Pour arrêter le suivi de la traçabilité et éviter les frais associés, désactivez l'API Data Lineage (datalineage.googleapis.com) dans chaque projet où elle est activée.
La désactivation de l'API Dataplex ne désactive pas la traçabilité des données ni n'arrête sa facturation. Vous devez désactiver l'API Data Lineage.
Pour désactiver la traçabilité des données, sélectionnez l'un des onglets suivants et suivez les étapes pour chaque projet dans lequel le suivi de la traçabilité a été activé :
Console
Dans la console Google Cloud , accédez à la page API et services activés.
Dans la liste des API, cliquez sur API Data Lineage.
Cliquez sur Désactiver l'API.
Bouton "Désactiver l'API" sur la page d'informations de l'API Data Lineage. Lorsque vous y êtes invité, cliquez sur Désactiver.
gcloud
Pour désactiver l'API Data Lineage, utilisez la commande gcloud services disable :
gcloud services disable datalineage.googleapis.com --project=PROJECT_ID
Remplacez les éléments suivants :
PROJECT_ID: ID de votre projet Google Cloud
Si vous souhaitez arrêter le suivi de la traçabilité pour des services spécifiques sans désactiver complètement l'API, consultez Contrôler l'ingestion de la traçabilité pour un service.
Étapes suivantes
- Suivez la traçabilité des données pour les jobs de copie et de requête d'une table BigQuery.
- Renseignez-vous sur le modèle d'informations sur la traçabilité des données.
- Découvrez les considérations et les limites liées à la traçabilité des données.
- Renseignez-vous sur la journalisation d'audit de la traçabilité des données.
- Découvrez comment résoudre les problèmes liés à la traçabilité des données.
- Découvrez comment intégrer OpenLineage.
- Découvrez comment utiliser la traçabilité des données avec Managed Service pour Apache Spark.