Définitions de types et création de types personnalisés

Article
06/06/2024

Ce tutoriel explique ce que sont les définitions de type, comment créer des types personnalisés et comment initialiser des ressources de types personnalisés dans Microsoft Purview.

Dans ce tutoriel, vous allez apprendre à :

Comment Microsoft Purview utilise le système de type d’Apache Atlas
Comment créer un type personnalisé
Comment créer des relations entre des types personnalisés
Comment initialiser de nouvelles entités de types personnalisés

Configuration requise

Pour ce tutoriel, vous aurez besoin des éléments suivants :

Un compte Azure avec un abonnement actif. Si vous n’en avez pas, vous pouvez créer un compte gratuitement.
Un compte Microsoft Purview actif (anciennement Azure Purview). Si vous n’en avez pas, consultez le guide de prise en main gratuite de Microsoft Purview.
Jeton du porteur pour votre compte Microsoft Purview. Pour établir un jeton du porteur et appeler des API, consultez la documentation sur l’authentification des API pour Microsoft Purview.
Votre point de terminaison Apache Atlas de votre compte Microsoft Purview. Il s’agit de l’un de ces deux points de terminaison, en fonction de votre environnement :
- Si vous utilisez le portail de gouvernance Microsoft Purview classique : https://{{ACCOUNTNAME}}.purview.azure.com/catalog
- Si vous utilisez le nouveau portail Microsoft Purview : https://api.purview-service.microsoft.com/catalog

Remarque

Avant de passer à la partie pratique du tutoriel, les quatre premières sections expliquent ce qu’est un type de système et comment il est utilisé dans Microsoft Purview. Tous les appels d’API REST décrits plus loin utilisent le jeton du porteur et le point de terminaison décrits dans les conditions préalables.

Pour passer directement aux étapes, utilisez les liens suivants :

Créer des définitions de type personnalisées
Initialiser des ressources de types personnalisés

Que sont les ressources et les types dans Microsoft Purview ?

Une ressource est un élément de métadonnées qui décrit une ressource numérique ou physique. Les ressources numériques ou physiques qui sont censées être catalogées en tant que ressources sont les suivantes :

Sources de données telles que les bases de données, les fichiers et le flux de données.
Modèles et processus analytiques.
Stratégies et conditions de l’entreprise.
Infrastructure comme le serveur.

Microsoft Purview fournit aux utilisateurs un système de type flexible pour étendre la définition de la ressource afin d’inclure de nouveaux types de ressources à mesure qu’ils deviennent pertinents. Microsoft Purview s’appuie sur le système de type d’Apache Atlas. Tous les objets de métadonnées (ressources) gérés par Microsoft Purview sont modélisés à l’aide de définitions de type. La compréhension du système de type est fondamentale pour créer de nouveaux types personnalisés dans Microsoft Purview.

Essentiellement, un type peut être vu comme une classe à partir de la programmation orientée objet (POO) :

Il définit les propriétés qui représentent ce type.
Chaque type est identifié de manière unique par son nom.
Un type peut hériter d’un supertType. Il s’agit d’un concept équivalent à l’héritage de la POO. Un type qui étend un superType hérite des attributs du superType.

Vous pouvez voir toutes les définitions de type dans votre compte Microsoft Purview en envoyant une GET requête au point de terminaison Toutes les définitions de type :

GET https://{{ENDPOINT}}/catalog/api/atlas/v2/types/typedefs

Apache Atlas a peu de types système prédéfinis qui sont couramment utilisés comme supertypes.

Par exemple :

Référenceable : ce type représente toutes les entités qui peuvent être recherchées à l’aide d’un attribut unique appelé qualifiedName.
Ressource : ce type s’étend à partir de Referenceable et possède d’autres attributs tels que : nom, description et propriétaire.
DataSet : ce type étend la ressource et la ressource référencées. Conceptuellement, il peut être utilisé pour représenter un type qui stocke des données. Les types qui étendent DataSet peuvent avoir un schéma. Par exemple, une table SQL.
Traçabilité : les informations de traçabilité permettent de comprendre l’origine des données et les transformations qu’elles ont pu subir avant d’arriver dans un fichier ou une table. La traçabilité est calculée via DataSet et Process : les DataSets (entrée du processus) ont un impact sur d’autres DataSets (sortie du processus) via Process.

Exemple de définition de type

Pour mieux comprendre le système de type, examinons un exemple et voyons comment une table Azure SQL est définie.

Vous pouvez obtenir la définition de type complète en envoyant une GET requête au point de terminaison définition de type :

GET https://{{ENDPOINT}}/catalog/api/atlas/v2/types/typedef/name/{name}

Conseil

La propriété {name} indique la définition qui vous intéresse. Dans ce cas, vous devez utiliser azure_sql_table.

Vous pouvez voir ci-dessous un résultat JSON simplifié :

{
  "category": "ENTITY",
  "guid": "7d92a449-f7e8-812f-5fc8-ca6127ba90bd",
  "name": "azure_sql_table",
  "description": "azure_sql_table",
  "typeVersion": "1.0",
  "serviceType": "Azure SQL Database",
  "options": {
    "schemaElementsAttribute": "columns",
  },
  "attributeDefs": [
    { "name": "principalId", ...},
    { "name": "objectType", ...},
    { "name": "createTime", ...},
    { "name": "modifiedTime", ... }
  ],
  "superTypes": [
    "DataSet",
    "Purview_Table",
    "Table"
  ],
  "subTypes": [],
  "relationshipAttributeDefs": [
    {
      "name": "dbSchema",
      "typeName": "azure_sql_schema",
      "isOptional": false,
      "cardinality": "SINGLE",
      "relationshipTypeName": "azure_sql_schema_tables",
    },
    {
      "name": "columns",
      "typeName": "array<azure_sql_column>",
      "isOptional": true,
      "cardinality": "SET",
      "relationshipTypeName": "azure_sql_table_columns",
    },
  ]
}

En fonction de la définition de type JSON, examinons certaines propriétés :

Le champ Catégorie décrit la catégorie de votre type. La liste des catégories prises en charge par Apache Atlas est disponible ici.
Le champ ServiceType est utile lors de la navigation des ressources par type de source dans Microsoft Purview. Le type de service est un point d’entrée pour rechercher toutes les ressources qui appartiennent au même type de service , comme défini sur leur définition de type. Dans la capture d’écran ci-dessous de l’interface utilisateur Purview, l’utilisateur limite le résultat aux entités spécifiées avec Azure SQL Database dans serviceType :

Remarque

Azure SQL Database est défini avec le même serviceType que Azure SQL Table.
SuperTypes décrit les types « parents » dont vous souhaitez « hériter ».
schemaElementsAttributes des options influence ce qui apparaît dans l’onglet Schéma de votre ressource dans Microsoft Purview.

Vous trouverez ci-dessous un exemple de l’onglet Schéma pour une ressource de type Azure SQL Table :
les relationshipAttributeDefs sont calculés par le biais des définitions de type de relation. Dans notre json, nous pouvons voir que schemaElementsAttributes pointe vers l’attribut de relation appelé columns , qui est l’un des éléments du tableau relationshipAttributeDefs , comme indiqué ci-dessous :
```
...
"relationshipAttributeDefs": [
     ...
     {
       "name": "columns",
       "typeName": "array<azure_sql_column>",
       "isOptional": true,
       "cardinality": "SET",
       "relationshipTypeName": "azure_sql_table_columns",
     },
   ]
```
Chaque relation a sa propre définition. Le nom de la définition se trouve dans l’attribut relationshipTypeName . Dans ce cas, c’est azure_sql_table_columns.
- La cardinalité de cet attribut de relation est définie sur *SET, ce qui suggère qu’il contient une liste de ressources associées.
- La ressource associée est de type azure_sql_column, comme visible dans l’attribut typeName .
En d’autres termes, l’attribut de relation columns lie l’Azure SQL Table à une liste de Azure SQL Colonnes qui s’affichent sous l’onglet Schéma.

Exemple de définition de type de relation

Chaque relation se compose de deux extrémités, appelées endDef1 et endDef2.

Dans l’exemple précédent, azure_sql_table_columns était le nom de la relation qui caractérise une table (endDef1) et ses colonnes (endDef2).

Pour la définition complète, vous pouvez effectuer une GET demande au point de terminaison suivant en utilisant azure_sql_table_columns comme nom :

GET https://{{ENDPOINT}}/catalog/api/atlas/v2/types/typedef/name/azure_sql_table_columns

Vous pouvez voir ci-dessous un résultat JSON simplifié :

{
  "category": "RELATIONSHIP",
  "guid": "c80d0027-8f29-6855-6395-d243b37d8a93",
  "name": "azure_sql_table_columns",
  "description": "azure_sql_table_columns",
  "serviceType": "Azure SQL Database",
  "relationshipCategory": "COMPOSITION",
  "endDef1": {
    "type": "azure_sql_table",
    "name": "columns",
    "isContainer": true,
    "cardinality": "SET",
  },
  "endDef2": {
    "type": "azure_sql_column",
    "name": "table",
    "isContainer": false,
    "cardinality": "SINGLE",
  }
}

name est le nom de la définition de relation. La valeur, dans ce cas azure_sql_table_columns est utilisée dans l’attribut relationshipTypeName de l’entité qui a cette relation, comme vous pouvez le voir référencé dans le json.
relationshipCategory est la catégorie de la relation et peut être COMPOSITION, AGRÉGATION ou ASSOCIATION comme décrit ici.
enDef1 est la première fin de la définition et contient les attributs :
- type est le type de l’entité que cette relation attend comme end1.
- name est l’attribut qui apparaîtra sur l’attribut de relation de cette entité.
- la cardinalité est UNIQUE, SET ou LIST.
- isContainer est une valeur booléenne qui s’applique à la catégorie de relation de conteneur. Lorsqu’elle est définie sur true à une extrémité, elle indique que cette fin est le conteneur de l’autre extrémité. Donc:
  - Seules les relations de catégorie Composition ou Agrégation peuvent et doivent avoir dans une extrémité isContainer défini sur true.
  - La propriété isContainer ne doit pas avoir la valeur true à la relation de catégorie d’association.
endDef2 est la deuxième fin de la définition et décrit, de la même façon que endDef1, les propriétés de la deuxième partie de la relation.

Onglet Schéma

Qu’est-ce que le schéma dans Microsoft Purview ?

Le schéma est un concept important qui reflète la façon dont les données sont stockées et organisées dans le magasin de données. Il reflète la structure des données et les restrictions de données des éléments qui construisent la structure.

Les éléments du même schéma peuvent être classés différemment (en raison de leur contenu). En outre, une transformation différente (traçabilité) ne peut se produire qu’à un sous-ensemble d’éléments. En raison de ces aspects, Purview peut modéliser des éléments de schéma et de schéma en tant qu’entités. Par conséquent, le schéma est généralement un attribut de relation à l’entité de ressource de données. Voici quelques exemples d’éléments de schéma : colonnes d’une table, propriétés json du schéma json, éléments xml du schéma xml, etc.

Il existe deux types de schémas :

Schéma intrinsèque : certains systèmes sont intrinsèques au schéma. Par exemple, lorsque vous créez une table SQL, le système vous oblige à définir les colonnes qui construisent la table ; en ce sens, le schéma d’une table est reflété par ses colonnes.

Pour le magasin de données avec un schéma prédéfini, Purview utilise la relation correspondante entre la ressource de données et les éléments de schéma pour refléter le schéma. Cet attribut de relation est spécifié par la propriété mot clé schemaElementsAttribute dans options de la définition de type d’entité.
Schéma non intrinsèque : certains systèmes n’appliquent pas ces restrictions de schéma, mais les utilisateurs peuvent l’utiliser pour stocker des données structurelles en appliquant des protocoles de schéma aux données. Par exemple, les objets blob Azure stockent des données binaires et ne se soucient pas des données du flux binaire. Par conséquent, il ne connaît aucun schéma, mais l’utilisateur peut sérialiser ses données avec des protocoles de schéma comme json avant de les stocker dans l’objet blob. En ce sens, le schéma est géré par des protocoles supplémentaires et la validation correspondante appliquée par l’utilisateur.

Pour le magasin de données sans schéma inhérent, le modèle de schéma est indépendant de ce magasin de données. Dans ce cas, Purview définit une interface pour le schéma et une relation entre Le DataSet et le schéma, appelée dataset_attached_schemas . Cela étend tout type d’entité qui hérite de DataSet à avoir un attribut de relation attachedSchema à lier à leur représentation de schéma.

Exemple d’onglet Schéma

L’exemple Azure SQL Table ci-dessus a un schéma intrinsèque. Les informations qui s’affichent sous l’onglet Schéma de la table Azure SQL proviennent de la colonne Azure SQL elle-même.

En sélectionnant un élément de colonne, nous voyons les éléments suivants :

La question est de savoir comment Microsoft Purview a-t-il sélectionné la propriété data_tye dans la colonne et l’a affichée sous l’onglet Schéma de la table ?

Vous pouvez obtenir la définition de type d’une colonne Azure SQL en effectuant une GET requête au point de terminaison :

GET https://{{ENDPOINT}}/catalog/api/atlas/v2/types/typedef/name/{name}

Remarque

{name} dans ce cas est : azure_sql_column

Voici un résultat JSON simplifié :

{
  "category": "ENTITY",
  "guid": "58034a18-fc2c-df30-e474-75803c3a8957",
  "name": "azure_sql_column",
  "description": "azure_sql_column",
  "serviceType": "Azure SQL Database",
  "options": {
    "schemaAttributes": "[\"data_type\"]"
  },
  "attributeDefs": 
  [
    {
      "name": "data_type",
      "typeName": "string",
      "isOptional": false,
      "cardinality": "SINGLE",
      "valuesMinCount": 1,
      "valuesMaxCount": 1,
      "isUnique": false,
      "isIndexable": false,
      "includeInNotification": false
    }, 
  ...
  ]
  ...
}

Remarque

serviceType est Azure SQL Database, identique à celui de la table

schemaAttributes est défini sur data_type, qui est l’un des attributs de ce type.

Azure SQL Table utilisait schemaElementAttribute pour pointer vers une relation composée d’une liste de colonnes Azure SQL. La définition de type d’une colonne a schemaAttributes défini.

De cette façon, l’onglet Schéma de la table affiche le ou les attributs répertoriés dans les schemaAttributes des ressources associées.

Créer des définitions de type personnalisées

Pourquoi ?

Tout d’abord, pourquoi une personne souhaite-t-elle créer une définition de type personnalisée ?

Dans certains cas, aucun type intégré ne correspond à la structure des métadonnées que vous souhaitez importer dans Microsoft Purview.

Dans ce cas, une nouvelle définition de type doit être définie.

Remarque

L’utilisation de types intégrés doit être favorisée par rapport à la création de types personnalisés, dans la mesure du possible.

Maintenant que nous avons acquis une compréhension des définitions de type en général, nous allons créer des définitions de type personnalisées.

Scénario

Dans ce tutoriel, nous aimerions modéliser une relation 1 :n entre deux types, appelée custom_type_parent et custom_type_child.

Un custom_type_child doit référencer un parent, tandis qu’un custom_type_parent peut référencer une liste d’enfants.

Ils doivent être liés par le biais d’une relation 1 :n.

Conseil

Vous trouverez ici quelques conseils lors de la création d’un type personnalisé.

Créer des définitions

Créez la définition de type custom_type_parent en effectuant une POST requête à l’un des deux points de terminaison suivants :

Portail de gouvernance Microsoft Purview classique :

POST https://{{ENDPOINT}}.purview.azure.com/catalog/api/atlas/v2/types/typedefs

Nouveau portail Microsoft Purview :

POST https://api.purview-service.microsoft.com/catalog/api/atlas/v2/types/typedefs

Avec le corps :

 {
    "entityDefs": 
    [
        {
            "category": "ENTITY",
            "version": 1,
            "name": "custom_type_parent",
            "description": "Sample custom type of a parent object",
            "typeVersion": "1.0",
            "serviceType": "Sample-Custom-Types",
            "superTypes": [
                "DataSet"
            ],
            "subTypes": [],
            "options":{
                "schemaElementsAttribute": "columns"
            }
        }
    ]
 }

Créez la définition de type custom_type_child en effectuant une POST requête à l’un des deux points de terminaison suivants :

Portail de gouvernance Microsoft Purview classique :

POST https://{{ENDPOINT}}.purview.azure.com/catalog/api/atlas/v2/types/typedefs

Nouveau portail Microsoft Purview :

POST https://api.purview-service.microsoft.com/catalog/api/atlas/v2/types/typedefs

Avec le corps :

 {
    "entityDefs": 
    [
        {
            "category": "ENTITY",
            "version": 1,
            "name": "custom_type_child",
            "description": "Sample custom type of a CHILD object",
            "typeVersion": "1.0",
            "serviceType": "Sample-Custom-Types",
            "superTypes": [
                "DataSet"
            ],
            "subTypes": [],
            "options":{
               "schemaAttributes": "data_type"
            }
        }
    ]
 }

Créez une définition de relation de type personnalisée en effectuant une POST requête à l’un des deux points de terminaison suivants :

Portail de gouvernance Microsoft Purview classique :

POST https://{{ENDPOINT}}.purview.azure.com/catalog/api/atlas/v2/types/typedefs

Nouveau portail Microsoft Purview :

POST https://api.purview-service.microsoft.com/catalog/api/atlas/v2/types/typedefs

Avec le corps :

{
    "relationshipDefs": [
        {
            "category": "RELATIONSHIP",
            "endDef1" : {
                "cardinality" : "SET",
                "isContainer" : true,
                "name" : "Children",
                "type" : "custom_type_parent"
            },
            "endDef2" : {
                "cardinality" : "SINGLE",
                "isContainer" : false,
                "name" : "Parent",
                "type" : "custom_type_child"
            },
            "relationshipCategory" : "COMPOSITION",
            "serviceType": "Sample-Custom-Types",
            "name": "custom_parent_child_relationship"
        }
    ]
}

Initialiser des ressources de types personnalisés

Initialisez une nouvelle ressource de type custom_type_parent en effectuant une POST requête à l’un des deux points de terminaison suivants :

Portail de gouvernance Microsoft Purview classique :

POST https://{{ENDPOINT}}.purview.azure.com/catalog/api/atlas/v2/entity

Nouveau portail Microsoft Purview :

POST https://api.purview-service.microsoft.com/catalog/api/atlas/v2/entity

Avec le corps :


{
    "entity": {
        "typeName":"custom_type_parent",
        "status": "ACTIVE",
        "version": 1,
         "attributes":{
            "name": "First_parent_object",
            "description": "This is the first asset of type custom_type_parent",
            "qualifiedName": "custom//custom_type_parent:First_parent_object"
         }

    }
}

Enregistrez le GUID , car vous en aurez besoin ultérieurement.

Initialisez une nouvelle ressource de type custom_type_child en effectuant une POST requête à l’un des deux points de terminaison suivants :

Portail de gouvernance Microsoft Purview classique :

POST https://{{ENDPOINT}}.purview.azure.com/catalog/api/atlas/v2/entity

Nouveau portail Microsoft Purview :

POST https://api.purview-service.microsoft.com/catalog/api/atlas/v2/entity

Avec le corps :

{
   "entity": {
       "typeName":"custom_type_child",
       "status": "ACTIVE",
       "version": 1,
       "attributes":{
           "name": "First_child_object",
           "description": "This is the first asset of type custom_type_child",
           "qualifiedName": "custom//custom_type_child:First_child_object"
        }
   }
}

Enregistrez le GUID , car vous en aurez besoin ultérieurement.

Initialisez une nouvelle relation de type custom_parent_child_relationship en effectuant une POST requête à l’un des deux points de terminaison suivants :

Portail de gouvernance Microsoft Purview classique :

POST https://{{ENDPOINT}}.purview.azure.com/catalog/api/atlas/v2/relationship/

Nouveau portail Microsoft Purview :

POST https://api.purview-service.microsoft.com/catalog/api/atlas/v2/relationship/

Avec le corps suivant :

Remarque

Le GUID dans end1 doit être remplacé par le GUID de l’objet créé à l’étape 6.1 Le GUID à la fin2 doit être remplacé par le GUID de l’objet créé à l’étape 6.2

{
   "typeName": "custom_parent_child_relationship",
   "end1": {
         "guid": "...",
       "typeName": "custom_type_parent"
   },
   "end2": {
       "guid": "...",
       "typeName": "custom_type_child"
   }
}

Afficher les ressources dans Microsoft Purview

Accédez à Data Catalog dans Microsoft Purview.
Sélectionnez Parcourir.
Sélectionnez Par type de source.
Sélectionnez Sample-Custom-Types.
Sélectionnez le First_parent_object :
Sélectionnez l’onglet Propriétés :
Vous pouvez voir les First_child_object qui y sont liées.
Sélectionnez le First_child_object :
Sélectionnez l’onglet Propriétés :
Vous pouvez voir que l’objet Parent y est lié.
De même, vous pouvez sélectionner l’onglet Connexe et voir la relation entre les deux objets :
Vous pouvez créer plusieurs enfants en initialisant une nouvelle ressource enfant et en inititialisant une relation

Remarque

Le qualifiedName est unique par ressource. Par conséquent, le deuxième enfant doit être appelé différemment, par exemple : custom//custom_type_child :Second_child_object

Conseil

Si vous supprimez le First_parent_object vous remarquerez que les enfants seront également supprimés, en raison de la relation COMPOSITION que nous avons choisie dans la définition.