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 lignée 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 lignée au fur et à mesure de leur découverte par le système backend. Cette méthode est très efficace pour les graphiques de lignée 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 l'arborescence au niveau des colonnes pour une entité spécifique en ajoutant * à la fin du 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 :

Autorisations requises

Les autorisations suivantes sont requises pour rechercher des liens de traçabilité des données :

  • Rechercher la lignée au niveau de l'entité : datalineage.events.get sur le projet dans lequel le lien est stocké
  • Rechercher la traçabilité au niveau des colonnes : datalineage.events.getFields sur le projet dans lequel le lien est stocké
  • Récupérez tous les détails du processus de pipeline : datalineage.processes.get sur le projet dans lequel le processus est stocké

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 du compte de facturation parent : le chemin parent dans la requête 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 des 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 lignée à plusieurs niveaux et dans plusieurs projets

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

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

Rechercher plusieurs zones géographiques

Vous pouvez limiter ou étendre l'analyse de votre graphique de lignée 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"
}'

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 (par exemple, 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 un FieldMask d'API :

  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 lignée 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'arborescence

Vous pouvez affiner les résultats de votre recherche sur la lignée 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, comme les copies directes (EXACT_COPY) ou les transformations telles que 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 l'historique à 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