Traçabilité externe¶

Workflow de traçabilité externe¶

La mise en œuvre de la traçabilité externe pour un outil de données comprend les tâches suivantes :

1. Accorder les privilèges nécessaires à l’utilisateur qui s’authentifie auprès du point de terminaison de traçabilité externe.

2. Configurer votre outil de données pour envoyer des événements OpenLineage au point de terminaison REST Snowflake.

3. Choisir une méthode d’authentification qui fonctionne pour les APIs REST Snowflake, puis configurer votre outil de données pour qu’il l’utilise pour authentifier ses requêtes vers le point de terminaison de traçabilité externe.

4. Utilisez votre outil de données comme d’habitude. Les événements OpenLineage sont envoyés automatiquement à Snowflake et apparaissent dans le graphique de traçabilité native dans Snowsight.

Si vous souhaitez tester le point de terminaison de traçabilité externe avant de configurer un outil de données pour qu’il émette des événements OpenLineage, voir Envoyer des requêtes manuelles pour établir la traçabilité.

Afficher votre traçabilité de données¶

Pour voir la traçabilité des données dans Snowsight, procédez comme suit :

1. Connectez-vous à Snowsight avec les privilèges nécessaires.

2. Dans le menu de navigation, sélectionnez Catalog » Database Explorer, puis sélectionnez un objet pris en charge, comme une table ou une vue.

3. Sélectionnez l’onglet Lineage.

Lorsqu’un outil de données envoie des informations de traçabilité à Snowflake, des objets externes apparaissent dans le graphique de traçabilité Snowsight et sont étiquetés comme un nœud externe. Par exemple :

Vous pouvez sélectionner un objet externe ou la ligne reliant les objets pour obtenir des informations supplémentaires, comme vous le faites avec la traçabilité native.

Accorder des privilèges Snowflake¶

Après qu’une requête REST est authentifiée, Snowflake vérifie si l’utilisateur associé à la requête est autorisé à utiliser une traçabilité externe. L’utilisateur associé à la requête doit avoir un rôle auquel est attribué le privilège INGEST LINEAGE sur le compte.

Par exemple, supposons que vous souhaitiez que des requêtes soient envoyées par l’utilisateur du service. dbt_integration_user pour apparaître dans la traçabilité Snowsight. En tant qu’administrateur, exécutez les commandes suivantes pour créer un rôle dédié, lui accorder le privilège nécessaire, puis attribuer le rôle à l’utilisateur :

CREATE ROLE dbt_lineage_role;
GRANT INGEST LINEAGE ON ACCOUNT TO ROLE dbt_lineage_role;
GRANT ROLE dbt_lineage_role TO USER dbt_integration_user;

Configurer votre outil de données¶

Les sections suivantes fournissent des instructions de base pour l’utilisation de la traçabilité externe avec dbt et Apache AirFlow.

• Configurer dbt pour envoyer des données de traçabilité à Snowflake

• Configurer Airflow pour envoyer des données de traçabilité à Snowflake

Choisir une méthode d’authentification¶

Snowflake fournit plusieurs méthodes pour authentifier les requêtes vers un point de terminaison REST Snowflake comme celui utilisé par la traçabilité externe. Pour une liste complète des méthodes d’authentification, voir Authentification d”Snowflake REST APIs avec Snowflake.

Après avoir sélectionné votre méthode d’authentification préférée, vous devez générer un jeton de sécurité pour un utilisateur spécifique. Le jeton est utilisé pour associer un utilisateur à la requête REST pour que Snowflake puisse authentifier l’utilisateur et vérifier que l’utilisateur est autorisé à utiliser la traçabilité externe.

Après avoir associé avec succès un utilisateur à un jeton de sécurité dans Snowflake, vous devez configurer votre outil de données pour authentifier ses demandes avec ce jeton. Par exemple, si vous utilisez un fichier de configuration YAML pour définir des variables de transport OpenLineage, utilisez le code suivant pour spécifier le jeton de sécurité qui est envoyé dans l’en-tête de la requête :

transport:
   auth:
      type: api_key
      apiKey: eyJ0eXAiOiJKV1QiLsecuritytoken...

Pour d’autres méthodes de spécification d’un jeton de sécurité, voir la documentation OpenLineage de votre outil de données.

Envoyer des requêtes manuelles pour établir la traçabilité¶

La traçabilité externe fonctionne en acceptant les charges utiles JSON conformes à la spécification OpenLineage pour les événements COMPLETE. Lorsqu’il est intégré à un outil de données, l’outil émet ces événements COMPLETE. Mais vous pouvez aussi construire un événement COMPLETE ; envoyez-le vers le point de terminaison en utilisant un outil ou un langage qui peut envoyer les requêtes POST vers un point de terminaison.

Une requête valide se compose de la méthode suivante, une URL de base, et un point de terminaison :

POST https://<account_identifier>.snowflakecomputing.com/api/v2/lineage/external-lineage

Où account_identifier est l’identificateur de compte de votre compte Snowflake.

L’exemple suivant montre comment utiliser curl pour envoyer des informations de traçabilité à une traçabilité externe :

curl -i -X POST \
 -H "Content-Type: application/json" \
 -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLsecuritytoken..." \
 -H "Accept: application/json" \
 -H "User-Agent: myApplicationName/1.0" \
 -H "X-Snowflake-Authorization-Token-Type: KEYPAIR_JWT" \
 -d "@request_body.json" \
 "https://MYORG-DEV_ACCOUNT.snowflakecomputing.com/api/v2/lineage/external-lineage"

Où request_body.json est conforme à la spécification OpenLineage pour les événements COMPLETE. Pour plus d’informations sur cette charge utile JSON, voir Exigences en matière de charge utile.

{
   "eventType": "COMPLETE",
   "eventTime": "2025-03-12T06:51:12.000Z",
   "job": {"namespace": "exampleNamespace", "name": "exampleJob"},
   "run": {"runId": "123e4567-e89b-12d3-a456-426614174000"},
   "producer": "https://github.com/OpenLineage/OpenLineage/blob/v1-0-0/client",
   "schemaURL": "https://openlineage.io/spec/0-0-1/OpenLineage.json",
   "inputs": [{"namespace": "snowflake://AXORG-AX_TEST_PP8", "name": "OL_TEST.OL_TEST_SCH.TEST_DEMO"}],
   "outputs": [{"namespace": "postgres://localhost:5432", "name": "PDB.SCH.OUTPUT"}]
}

"outputs": [
    {
        "namespace": "postgres://db.company.com:5432",
        "name": "db.schema.view",
        "facets": {"datasetType": {"datasetType": "VIEW"}},
    },
],

Envoyer des requêtes pour supprimer la traçabilité¶

Vous pouvez envoyer une requête DELETE au point de terminaison de traçabilité externe pour supprimer la traçabilité établie entre un objet Snowflake et un objet externe.

• Pour rompre la traçabilité entre l’objet source et l’objet cible, utilisez les paramètres de requête URL pour spécifier les détails des deux objets.

• Pour rompre la traçabilité entre un objet et tous ses objets en aval, spécifiez l’objet source sans spécifier d’objet cible.

• Pour supprimer un objet cible du graphique de traçabilité, quel que soit le nombre d’objets qui se trouvent en amont, spécifiez l’objet cible sans spécifier d’objet source.

Une requête valide de suppression de traçabilité se compose de la méthode suivante, URL de base et point de terminaison :

DELETE https://<account_identifier>.snowflakecomputing.com/api/v2/lineage/external-lineage

Limites et considérations¶

• Un objet Snowflake doit être soit l’INPUT ou l’OUTPUT d’un événement COMPLETE. En d’autres termes, la traçabilité externe n’ingère pas d’événements de traçabilité lorsque ni les données d’entrée ni les données de sortie ne sont un objet Snowflake.

• Snowflake ne prend pas en charge OpenLineage version 2.

• La période de conservation des événements de traçabilité externe est d’un an.

• Snowflake ne reconnaît que les événements COMPLETE de traçabilité. Tous les autres événements émis par un outil de données sont ignorés.

• La traçabilité de sources externes n’apparaît pas dans la sortie de la fonction GET_LINEAGE.

• La traçabilité externe ne prend pas en charge la traçabilité des colonnes.

• Le nom complet d’un ensemble de données, c’est-à-dire l’entrée ou la sortie, ne peut pas dépasser 1 000 caractères.

• Vous ne pouvez pas stocker plus de 10 000 événements dans le même compte. Si vous atteignez cette limite, vous devrez supprimer des événements avant d’en ajouter de nouveaux.