Créer et obtenir des relations à l’aide de l’API REST

Article
11/12/2024

Dans ce tutoriel, vous allez apprendre à utiliser les API REST Purview pour :

Créez des ressources et des relations de traçabilité entre les ressources de données.
Interroger les relations/chemins de traçabilité.

API référencées dans cet article :

Configuration requise

L’utilisation de ces API nécessite des rôles Conservateur de données et Lecteur de données. Consultez ce tutoriel pour plus d’informations sur l’obtention du jeton d’accès.

Concepts

Ressource

Dans Purview, nous avons deux types de ressources de base : DataSet et Process.

Les ressources de DataSet qui contiennent des données telles que Azure SQL Table, Oracle Table, etc. doivent être héritées du DataSet.
Les ressources de processus qui traitent des données, telles qu’un pipeline de données, une requête, une fonction, etc. doivent être héritées de Process.

Reportez-vous aux ressources et aux types pour comprendre les définitions de type des datasets et des processus.

Relations & traçabilité

Dans Microsoft Purview, nous définissons trois types de relations pour la traçabilité :

dataset_process_inputs : connecte DataSet à Process, ce qui signifie que le DataSet est l’entrée du processus
process_dataset_outputs : connecte Process à DataSet, ce qui signifie que le processus produit le DataSet
direct_lineage_dataset_dataset : connecte DataSet1 à DataSet2, ce qui signifie que DataSet1 est le amont de DataSet2, bien que nous ne sachions pas exactement quel processus se trouve entre eux

Exemple 1 :Voici un exemple de traçabilité avec 2 datasets, un processus et deux relations de traçabilité :

Jeu de données ---> dataset_process_inputs --- ---> processus process_dataset_outputs --->> DataSet

Exemple 2 :Autre exemple de traçabilité avec 2 DataSets et une relation de traçabilité :

Jeu de données ---> direct_lineage_dataset_dataset ---> DataSet

Créer des ressources et des relations de traçabilité entre les ressources de données

Dans les sections suivantes, prenons hive_table comme exemple de type pour DataSet et hive_query_process comme type d’exemple pour Process. Nous allons créer des ressources avec ces deux types et créer des lignages entre eux. Vous pouvez utiliser n’importe quel autre type, qui hérite de DataSet ou Process pour créer des lignages.

Exemple 1

Créer des ressources via l’API

Si les ressources pour lesquelles vous souhaitez créer une traçabilité ne sont pas encore créées dans Microsoft Purview, vous pouvez appeler l’API suivante pour les créer.

API : Créer des ressources en bloc

Tâche : Créez deux hive_tables en tant que jeux de données : table1 et table2, chacun avec 2 hive_columns - colonne1 et colonne2.

POST {endpoint}/datamap/api/atlas/v2/entity/bulk

Avec le corps :

{
  "entities": [
    {
      "typeName": "hive_table",
      "attributes": {
        "qualifiedName": "test_lineage.table1",
        "name": "table1"
      },
      "relationshipAttributes": {
        "columns": [
          {
            "guid": "-11",
            "typeName": "hive_column"
          },{
            "guid": "-12",
            "typeName": "hive_column"
          }
        ]
      },
      "guid": "-1"
    },
    {
      "typeName": "hive_column",
      "attributes": {
        "qualifiedName": "test_lineage.table1#column1",
        "name": "column1",
        "type": "int"
      },
      "guid": "-11",
      "relationshipAttributes": {
        "table": {
          "guid": "-1",
          "typeName": "hive_table"
        }
      }
    },
    {
      "typeName": "hive_column",
      "attributes": {
        "qualifiedName": "test_lineage.table1#column2",
        "name": "column2",
        "type": "int"
      },
      "guid": "-12",
      "relationshipAttributes": {
        "table": {
          "guid": "-1",
          "typeName": "hive_table"
        }
      }
    },
    {
      "typeName": "hive_table",
      "attributes": {
        "qualifiedName": "test_lineage.table2",
        "name": "table2"
      },
      "relationshipAttributes": {
        "columns": [
          {
            "guid": "-21",
            "typeName": "hive_column"
          },{
            "guid": "-22",
            "typeName": "hive_column"
          }
        ]
      },
      "guid": "-2"
    },
    {
      "typeName": "hive_column",
      "attributes": {
        "qualifiedName": "test_lineage.table2#column1",
        "name": "column1",
        "type": "int"
      },
      "guid": "-21",
      "relationshipAttributes": {
        "table": {
          "guid": "-2",
          "typeName": "hive_table"
        }
      }
    },
    {
      "typeName": "hive_column",
      "attributes": {
        "qualifiedName": "test_lineage.table2#column2",
        "name": "column2",
        "type": "int"
      },
      "guid": "-22",
      "relationshipAttributes": {
        "table": {
          "guid": "-2",
          "typeName": "hive_table"
        }
      }
    }    
  ]
}

Tâche : Créer la ressource de processus « hive_view_query »

POST {endpoint}/datamap/api/atlas/v2/entity/bulk

Avec le corps :

{
  "entities": [
    {
      "typeName": "hive_view_query",
      "attributes": {
        "qualifiedName": "test_lineage.HiveQuery1",
        "name": "HiveQuery1",
        "columnMapping": "[{\"DatasetMapping\":{\"Source\":\"test_lineage.table1\",\"Sink\":\"test_lineage.table2\"},\"ColumnMapping\":[{\"Source\":\"column1\",\"Sink\":\"column1\"},{\"Source\":\"column2\",\"Sink\":\"column2\"}]}]"
      },
      "guid": "-1"
    }
  ]
}

Les appels d’API ci-dessus entraînent la création de deux hive_tables(jeux de données) et d’un hive_view_query(Processus).

Créer des relations de traçabilité entre les jeux de données et le processus

API : Créer une relation

Tâche : Créer une traçabilité à partir de table1 -> HiveQuery1 (autrement dit, Jeu de données -> Processus)

POST {endpoint}/datamap/api/atlas/v2/relationship

Avec le corps :

{
        "typeName": "dataset_process_inputs",
        "guid": "-1",
        "end1": {
            "typeName": "hive_table",
            "uniqueAttributes": {
                "qualifiedName": "test_lineage.table1"
            }
        },
        "end2": {
            "typeName": "Process",
            "uniqueAttributes": {
                "qualifiedName": "test_lineage.HiveQuery1"
            }
        }
}

Tâche : Créer une traçabilité à partir de HiveQuery1 -> table2 (autrement dit, Processus -> Jeu de données)

POST {endpoint}/datamap/api/atlas/v2/relationship

Avec le corps :

{
        "typeName": "process_dataset_outputs",
        "guid": "-2",
        "end1": {
            "typeName": "Process",
            "uniqueAttributes": {
                "qualifiedName": "test_lineage.HiveQuery1"
            }
        },
        "end2": {
            "typeName": "hive_table",
            "uniqueAttributes": {
                "qualifiedName": "test_lineage.table2"
            }
        }
}

Afficher la traçabilité

Une fois les ressources et les relations de traçabilité créées, vous pouvez case activée le graphique de traçabilité dans Microsoft Purview :

Exemple 2

Créer une table hive, table3, avec deux colonnes

API : Créer des ressources en bloc

Tâche : Créer une table3, avec 2 hive_columns, colonne1 et colonne2

POST {endpoint}/datamap/api/atlas/v2/entity/bulk

Avec le corps :

{
"entities": [
    {
      "typeName": "hive_table",
      "attributes": {
        "qualifiedName": "test_lineage.table3",
        "name": "table3"
      },
      "relationshipAttributes": {
        "columns": [
          {
            "guid": "-31",
            "typeName": "hive_column"
          },{
            "guid": "-32",
            "typeName": "hive_column"
          }
        ]
      },
      "guid": "-3"
    },
    {
      "typeName": "hive_column",
      "attributes": {
        "qualifiedName": "test_lineage.table3#column1",
        "name": "column1",
        "type": "int"
      },
      "guid": "-31",
      "relationshipAttributes": {
        "table": {
          "guid": "-3",
          "typeName": "hive_table"
        }
      }
    },
    {
      "typeName": "hive_column",
      "attributes": {
        "qualifiedName": "test_lineage.table3#column2",
        "name": "column2",
        "type": "int"
      },
      "guid": "-32",
      "relationshipAttributes": {
        "table": {
          "guid": "-3",
          "typeName": "hive_table"
        }
      }
    }
   ]
}

Créer une traçabilité directe entre la table 2 et la table 3, avec le mappage de colonnes

API : Créer une relation

Tâche : Créer une traçabilité à partir de table2 -> table3 (autrement dit, jeu de données -> jeu de données) avec mappage de colonnes

POST {endpoint}/datamap/api/atlas/v2/relationship

Avec le corps :

{
    "typeName": "direct_lineage_dataset_dataset",
    "guid": "-1",
    "end1": {
        "typeName": "hive_table",
        "uniqueAttributes": {
            "qualifiedName": "test_lineage.table2"
        }
    },
    "end2": {
        "typeName": " hive_table ",
        "uniqueAttributes": {
            "qualifiedName": "test_lineage.table3"
        }
    },
    "attributes": {
      "columnMapping": "[{\"Source\":\"column1\",\"Sink\":\"column1\"},{\"Source\":\"column2\",\"Sink\":\"column2\"}]"
    }
}

Afficher la traçabilité

À présent, le graphique de traçabilité (ensemble de l’exemple 1 & l’exemple 2 ci-dessus) devient :

Notez que table2 est directement lié à table3, sans HiveQuery entre eux.

Relations/chemins de traçabilité des requêtes

API : Obtenir la traçabilité par GUID

Tâche : Obtenir la traçabilité de table2 via l’API REST

GET {{endpoint}}/api/atlas/v2/lineage/{{guid_of_table2}}?direction=BOTH

Vous trouverez ci-dessous une charge utile de réponse JSON :

{
    "baseEntityGuid": "2a12b3ff-5816-4222-833a-035bf82e06e0",
    "lineageDirection": "BOTH",
    "lineageDepth": 3,
    "lineageWidth": -1,
    "childrenCount": -1,
    "guidEntityMap": {
        "16b93b78-8683-4f88-9651-24c4a9d797b0": {
            "typeName": "hive_table",
            "attributes": {
                "temporary": false,
                "lastAccessTime": 0,
                "createTime": 0,
                "qualifiedName": "test_lineage.table3",
                "name": "table3",
                "retention": 0
            },
            "lastModifiedTS": "1",
            "guid": "16b93b78-8683-4f88-9651-24c4a9d797b0",
            "status": "ACTIVE",
            "displayText": "table3",
            "classificationNames": [],
            "meaningNames": [],
            "meanings": [],
            "isIncomplete": false,
            "labels": [],
            "isIndexed": true
        },
        "cb22ba23-47a2-4149-ade6-e3d9642fe592": {
            "typeName": "hive_table",
            "attributes": {
                "temporary": false,
                "lastAccessTime": 0,
                "createTime": 0,
                "qualifiedName": "test_lineage.table1",
                "name": "table1",
                "retention": 0
            },
            "lastModifiedTS": "1",
            "guid": "cb22ba23-47a2-4149-ade6-e3d9642fe592",
            "status": "ACTIVE",
            "displayText": "table1",
            "classificationNames": [],
            "meaningNames": [],
            "meanings": [],
            "isIncomplete": false,
            "labels": [],
            "isIndexed": true
        },
        "bbeacce6-5bde-46f7-8fe4-689cbb36ba51": {
            "typeName": "hive_view_query",
            "attributes": {
                "qualifiedName": "test_lineage.HiveQuery1",
                "name": "HiveQuery1",
                "columnMapping": "[{\"DatasetMapping\":{\"Source\":\"test_lineage.table1\",\"Sink\":\"test_lineage.table2\"},\"ColumnMapping\":[{\"Source\":\"column1\",\"Sink\":\"column1\"},{\"Source\":\"column2\",\"Sink\":\"column2\"}]}]"
            },
            "lastModifiedTS": "1",
            "guid": "bbeacce6-5bde-46f7-8fe4-689cbb36ba51",
            "status": "ACTIVE",
            "displayText": "HiveQuery1",
            "classificationNames": [],
            "meaningNames": [],
            "meanings": [],
            "isIncomplete": false,
            "labels": [],
            "isIndexed": true
        },
        "2a12b3ff-5816-4222-833a-035bf82e06e0": {
            "typeName": "hive_table",
            "attributes": {
                "temporary": false,
                "lastAccessTime": 0,
                "createTime": 0,
                "qualifiedName": "test_lineage.table2",
                "name": "table2",
                "retention": 0
            },
            "lastModifiedTS": "1",
            "guid": "2a12b3ff-5816-4222-833a-035bf82e06e0",
            "status": "ACTIVE",
            "displayText": "table2",
            "classificationNames": [],
            "meaningNames": [],
            "meanings": [],
            "isIncomplete": false,
            "labels": [],
            "isIndexed": true
        }
    },
    "includeParent": false,
    "relations": [
        {
            "fromEntityId": "2a12b3ff-5816-4222-833a-035bf82e06e0",
            "toEntityId": "16b93b78-8683-4f88-9651-24c4a9d797b0",
            "relationshipId": "23df8e3e-b066-40b2-be29-9fd90693c51b",
            "columnMapping": "[{\"Source\":\"column1\",\"Sink\":\"column1\"},{\"Source\":\"column2\",\"Sink\":\"column2\"}]"
        },
        {
            "fromEntityId": "bbeacce6-5bde-46f7-8fe4-689cbb36ba51",
            "toEntityId": "2a12b3ff-5816-4222-833a-035bf82e06e0",
            "relationshipId": "5fe8d378-39cd-4c6b-8ced-91b0152d3014"
        },
        {
            "fromEntityId": "cb22ba23-47a2-4149-ade6-e3d9642fe592",
            "toEntityId": "bbeacce6-5bde-46f7-8fe4-689cbb36ba51",
            "relationshipId": "73e084bf-98a3-45fb-a1e4-c56cc40661b8"
        }
    ],
    "parentRelations": [],
    "widthCounts": {
        "INPUT": {
            "cb22ba23-47a2-4149-ade6-e3d9642fe592": 0,
            "bbeacce6-5bde-46f7-8fe4-689cbb36ba51": 1,
            "2a12b3ff-5816-4222-833a-035bf82e06e0": 1
        },
        "OUTPUT": {
            "16b93b78-8683-4f88-9651-24c4a9d797b0": 0,
            "2a12b3ff-5816-4222-833a-035bf82e06e0": 1
        }
    }
}

Autres ressources

Définitions de type

Toutes les ressources/entités et relations sont définies dans le système de type.

Api lister toutes les définitions de type pour obtenir les définitions de type actuelles dans votre instance Microsoft Purview. Si vous ne savez pas quel typeName utiliser dans les appels d’API décrits, vous pouvez case activée l’API de définitions de type pour trouver le type d’actif/entité approprié.

Voici un exemple de réponse de cette API :

Vous pouvez voir que dans les entityDefs de la réponse ci-dessus, les types de ressources (tels que oracle_table, oracle_view, etc.) sont définis. Un examen approfondi de la définition de la ressource (dans cet exemple, oracle_view) montre que la ressource est de type DataSet hérité.

De même, vous pouvez constater qu’un processus (par exemple, Oracle_function) est hérité du type « Processus » comme indiqué :

Créer des types personnalisés

Si vous souhaitez créer des ressources ou des processus personnalisés, vous pouvez utiliser les API suivantes.

API : Créer une API Typedef

Tâche : Créer un type de processus personnalisé

POST {endpoint}/datamap/api/atlas/v2/types/typedefs

Avec le corps :

{
  "enumDefs": [],
  "structDefs": [],
  "classificationDefs": [],
  "entityDefs": [
    {
      "name": "MyCustomServiceProcess",
      "superTypes": [
        "Process"
      ],
      "typeVersion": "1.0",
      "attributeDefs": []
    }
  ],
  "relationshipDefs": []
}

Tâche : Créer un type de dataset personnalisé

POST {endpoint}/datamap/api/atlas/v2/types/typedefs

Avec le corps :

{
  "enumDefs": [],
  "structDefs": [],
  "classificationDefs": [],
  "entityDefs": [
    {
      "name": "MyCustomDataSet",
      "superTypes": [
        "DataSet"
      ],
      "typeVersion": "1.0",
      "attributeDefs": []
    }
  ],
  "relationshipDefs": []
}

Partager via

Créer et obtenir des relations à l’aide de l’API REST

Configuration requise

Concepts

Ressource

Relations & traçabilité

Créer des ressources et des relations de traçabilité entre les ressources de données

Exemple 1

Créer des ressources via l’API

Créer des relations de traçabilité entre les jeux de données et le processus

Afficher la traçabilité

Exemple 2

Créer une table hive, table3, avec deux colonnes

Créer une traçabilité directe entre la table 2 et la table 3, avec le mappage de colonnes

Afficher la traçabilité

Relations/chemins de traçabilité des requêtes

Autres ressources

Définitions de type

Créer des types personnalisés

Commentaires

Ressources supplémentaires