Definizioni dei tipi e come creare tipi personalizzati
Questa esercitazione descrive le definizioni dei tipi, come creare tipi personalizzati e come inizializzare asset di tipi personalizzati in Microsoft Purview.
In questa esercitazione si apprenderà quanto segue:
- Come Microsoft Purview usa il sistema di tipi di Apache Atlas
- Come creare un nuovo tipo personalizzato
- Come creare relazioni tra tipi personalizzati
- Come inizializzare nuove entità di tipi personalizzati
Per questa esercitazione sono necessari:
Un account Azure con una sottoscrizione attiva. Se non ne hai uno, puoi creare un account gratuitamente.
Un account Microsoft Purview attivo (in precedenza Azure Purview). Se non è disponibile, vedere la guida per iniziare a usare Microsoft Purview gratuitamente.
Token di connessione per l'account Microsoft Purview. Per stabilire un token di connessione e chiamare qualsiasi API, vedere la documentazione su come autenticare le API per Microsoft Purview.
L'endpoint Apache Atlas dell'account Microsoft Purview. Sarà uno di questi due endpoint, a seconda dell'ambiente:
- Se si usa il portale di governance di Microsoft Purview classico:
https://{{ACCOUNTNAME}}.purview.azure.com/catalog
- Se si usa il nuovo portale di Microsoft Purview:
https://api.purview-service.microsoft.com/catalog
- Se si usa il portale di governance di Microsoft Purview classico:
Nota
Prima di passare alla parte pratica dell'esercitazione, le prime quattro sezioni illustrano che cos'è un tipo di sistema e come viene usato in Microsoft Purview. Tutte le chiamate API REST descritte più avanti useranno il token di connessione e l'endpoint descritti nei prerequisiti.
Per passare direttamente ai passaggi, usare i collegamenti seguenti:
Un asset è un elemento di metadati che descrive una risorsa digitale o fisica. Le risorse digitali o fisiche che dovrebbero essere catalogate come asset includono:
- Origini dati, ad esempio database, file e feed di dati.
- Modelli e processi analitici.
- Criteri e termini aziendali.
- Infrastruttura come il server.
Microsoft Purview offre agli utenti un sistema di tipo flessibile per espandere la definizione dell'asset in modo da includere nuovi tipi di risorse man mano che diventano rilevanti. Microsoft Purview si basa sul sistema di tipi di Apache Atlas. Tutti gli oggetti metadati (asset) gestiti da Microsoft Purview vengono modellati usando definizioni di tipo. Comprendere il sistema di tipi è fondamentale per creare nuovi tipi personalizzati in Microsoft Purview.
In sostanza, un tipo può essere visto come una classe dalla programmazione orientata a oggetti (OOP):
- Definisce le proprietà che rappresentano tale tipo.
- Ogni tipo è identificato in modo univoco dal relativo nome.
- Un tipo può ereditare da un supertType. Si tratta di un concetto equivalente come ereditarietà da OOP. Un tipo che estende un superType erediterà gli attributi del superType.
È possibile visualizzare tutte le definizioni di tipo nell'account Microsoft Purview inviando una GET
richiesta all'endpoint Tutte le definizioni dei tipi :
GET https://{{ENDPOINT}}/catalog/api/atlas/v2/types/typedefs
Apache Atlas ha pochi tipi di sistema predefiniti comunemente usati come supertipi.
Ad esempio:
Riferimento: questo tipo rappresenta tutte le entità che è possibile cercare usando un attributo univoco denominato qualifiedName.
Asset: questo tipo si estende da Referenceable e include altri attributi, ad esempio nome, descrizione e proprietario.
DataSet: questo tipo estende Referenceable e Asset. Concettualmente, può essere usato per rappresentare un tipo che archivia i dati. È possibile che i tipi che estendono DataSet abbiano uno schema. Ad esempio, una tabella SQL.
Derivazione: le informazioni sulla derivazione consentono di comprendere l'origine dei dati e le trasformazioni che potrebbero essere state attraversate prima di arrivare in un file o in una tabella. La derivazione viene calcolata tramite dataset e processo: i dataset (input del processo) influiscono su altri DataSet (output del processo) tramite Process.
Per comprendere meglio il sistema di tipi, verrà illustrato un esempio e verrà illustrato come viene definita una tabella Azure SQL.
È possibile ottenere la definizione completa del tipo inviando una GET
richiesta all'endpoint di definizione del tipo:
GET https://{{ENDPOINT}}/catalog/api/atlas/v2/types/typedef/name/{name}
Suggerimento
La proprietà {name} indica a quale definizione si è interessati. In questo caso, è consigliabile usare azure_sql_table.
Di seguito è possibile visualizzare un risultato JSON semplificato:
{
"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",
},
]
}
In base alla definizione del tipo JSON, verranno esaminate alcune proprietà:
Il campo Categoria descrive in quale categoria è il tipo. L'elenco delle categorie supportate da Apache Atlas è disponibile qui.
Il campo ServiceType è utile quando si esplorano gli asset in base al tipo di origine in Microsoft Purview. Il tipo di servizio sarà un punto di ingresso per trovare tutti gli asset che appartengono allo stesso tipo di servizio , come definito nella definizione del tipo. Nello screenshot seguente dell'interfaccia utente di Purview, l'utente limita il risultato alle entità specificate con Azure SQL Database in serviceType:
Nota
Azure SQL Database viene definito con lo stesso serviceType di Azure SQL Table.
SuperTypes descrive i tipi "padre" da cui si vuole "ereditare".
schemaElementsAttributes da opzioni influenza ciò che viene visualizzato nella scheda Schema dell'asset in Microsoft Purview.
Di seguito è riportato un esempio dell'aspetto della scheda Schema per un asset di tipo Azure SQL Table:
Le proprietà relationshipAttributeDef vengono calcolate tramite le definizioni dei tipi di relazione. In JSON è possibile notare che schemaElementsAttributes punta all'attributo di relazione denominato columns , ovvero uno degli elementi della matrice relationshipAttributeDefs , come illustrato di seguito:
... "relationshipAttributeDefs": [ ... { "name": "columns", "typeName": "array<azure_sql_column>", "isOptional": true, "cardinality": "SET", "relationshipTypeName": "azure_sql_table_columns", }, ]
Ogni relazione ha una propria definizione. Il nome della definizione si trova nell'attributo relationshipTypeName . In questo caso, è azure_sql_table_columns.
- La cardinalità di questo attributo di relazione è impostata su *SET, il che suggerisce che contiene un elenco di asset correlati.
- L'asset correlato è di tipo azure_sql_column, come visibile nell'attributo typeName .
In altre parole, l'attributo di relazione columns mette in relazione la tabella Azure SQL a un elenco di Azure SQL colonne visualizzate nella scheda Schema.
Ogni relazione è costituita da due estremità, denominate endDef1 e endDef2.
Nell'esempio precedente azure_sql_table_columns era il nome della relazione che caratterizza una tabella (endDef1) e le relative colonne (endDef2).
Per la definizione completa, è possibile effettuare una GET
richiesta all'endpoint seguente usando azure_sql_table_columns come nome:
GET https://{{ENDPOINT}}/catalog/api/atlas/v2/types/typedef/name/azure_sql_table_columns
Di seguito è possibile visualizzare un risultato JSON semplificato:
{
"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 è il nome della definizione della relazione. Il valore, in questo caso azure_sql_table_columns viene usato nell'attributo relationshipTypeName dell'entità che ha questa relazione, come è possibile vedere come riferimento nel json.
relationshipCategory è la categoria della relazione e può essere COMPOSITION, AGGREGATION o ASSOCIATION come descritto qui.
enDef1 è la prima fine della definizione e contiene gli attributi:
type è il tipo dell'entità prevista da questa relazione come end1.
name è l'attributo che verrà visualizzato nell'attributo di relazione dell'entità.
la cardinalità è SINGLE, SET o LIST.
isContainer è un valore booleano e si applica alla categoria di relazioni di contenimento. Se impostato su true in un'estremità, indica che questa fine è il contenitore dell'altra estremità. Pertanto:
- Solo le relazioni di categoria Composizione o Aggregazione possono e devono avere in un'estremità isContainer impostata su true.
- La relazione di categoria dell'associazione non deve avere la proprietà isContainer impostata su true in alcun modo.
endDef2 è la seconda estremità della definizione e descrive, analogamente a endDef1, le proprietà della seconda parte della relazione.
Lo schema è un concetto importante che riflette il modo in cui i dati vengono archiviati e organizzati nell'archivio dati. Riflette la struttura dei dati e le restrizioni dei dati degli elementi che costruiscono la struttura.
Gli elementi nello stesso schema possono essere classificati in modo diverso (a causa del relativo contenuto). Inoltre, una trasformazione diversa (derivazione) può verificarsi solo in un subset di elementi. A causa di questi aspetti, Purview può modellare gli elementi dello schema e dello schema come entità, quindi lo schema è in genere un attributo di relazione con l'entità dell'asset di dati. Esempi di elementi dello schema sono: colonne di una tabella, proprietà json dello schema json, elementi xml dello schema xml e così via.
Esistono due tipi di schemi:
Schema intrinseco : alcuni sistemi sono intrinseci allo schema. Ad esempio, quando si crea una tabella SQL, il sistema richiede di definire le colonne che costruiscono la tabella; in questo senso, lo schema di una tabella viene riflesso dalle relative colonne.
Per l'archivio dati con schema predefinito, Purview usa la relazione corrispondente tra l'asset di dati e gli elementi dello schema per riflettere lo schema. Questo attributo di relazione viene specificato dalla parola chiave schemaElementsAttribute nella proprietà options della definizione del tipo di entità.
Schema non intrinseco : alcuni sistemi non applicano tali restrizioni dello schema, ma gli utenti possono usarle per archiviare i dati strutturali applicando alcuni protocolli dello schema ai dati. Ad esempio, i BLOB di Azure archivia i dati binari e non si preoccupano dei dati nel flusso binario. Pertanto, non è a conoscenza di alcun schema, ma l'utente può serializzare i dati con protocolli dello schema come json prima di archiviarli nel BLOB. In questo senso, lo schema viene gestito da alcuni protocolli aggiuntivi e dalla convalida corrispondente applicata dall'utente.
Per l'archivio dati senza schema intrinseco, il modello di schema è indipendente da questo archivio dati. In questi casi, Purview definisce un'interfaccia per lo schema e una relazione tra DataSet e schema, denominata dataset_attached_schemas . In questo modo, qualsiasi tipo di entità che eredita da DataSet viene esteso in modo che abbia un attributo di relazione attachedSchema da collegare alla relativa rappresentazione dello schema.
L'esempio di tabella Azure SQL precedente ha uno schema intrinseco. Le informazioni visualizzate nella scheda Schema della tabella Azure SQL provengono dalla colonna Azure SQL stessa.
Selezionando un elemento di colonna, si vedrà quanto segue:
La domanda è: in che modo Microsoft Purview ha selezionato la proprietà data_tye dalla colonna e l'ha mostrata nella scheda Schema della tabella?
È possibile ottenere la definizione del tipo di una colonna Azure SQL effettuando una GET
richiesta all'endpoint:
GET https://{{ENDPOINT}}/catalog/api/atlas/v2/types/typedef/name/{name}
Nota
{name} in questo caso è: azure_sql_column
Ecco un risultato JSON semplificato:
{
"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
},
...
]
...
}
Nota
serviceType è Azure SQL Database, come per la tabella
- schemaAttributes è impostato su data_type, uno degli attributi di questo tipo.
Azure SQL Table ha usato schemaElementAttribute per puntare a una relazione costituita da un elenco di colonne Azure SQL. La definizione del tipo di una colonna ha schemaAttributes definito.
In questo modo, nella scheda Schema della tabella vengono visualizzati gli attributi elencati nello schemaAttributes degli asset correlati.
Prima di tutto, perché qualcuno vuole creare una definizione di tipo personalizzata?
In alcuni casi non esiste alcun tipo predefinito corrispondente alla struttura dei metadati da importare in Microsoft Purview.
In questo caso, deve essere definita una nuova definizione di tipo.
Nota
L'utilizzo dei tipi predefiniti deve essere favorito rispetto alla creazione di tipi personalizzati, quando possibile.
Ora che è stata acquisita una conoscenza generale delle definizioni dei tipi, è possibile creare definizioni di tipo personalizzate.
In questa esercitazione si vuole modellare una relazione 1:n tra due tipi, denominata custom_type_parent e custom_type_child.
Un custom_type_child deve fare riferimento a un elemento padre, mentre un custom_type_parent può fare riferimento a un elenco di elementi figlio.
Devono essere collegati tra loro tramite una relazione 1:n.
Suggerimento
Qui è possibile trovare alcuni suggerimenti per la creazione di un nuovo tipo personalizzato.
- Creare la definizione del tipo custom_type_parent effettuando una
POST
richiesta a uno dei due endpoint seguenti:
Portale di governance di Microsoft Purview classico:
POST https://{{ENDPOINT}}.purview.azure.com/catalog/api/atlas/v2/types/typedefs
Nuovo portale di Microsoft Purview:
POST https://api.purview-service.microsoft.com/catalog/api/atlas/v2/types/typedefs
Con il corpo:
{
"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"
}
}
]
}
- Creare la definizione del tipo custom_type_child effettuando una
POST
richiesta a uno dei due endpoint seguenti:
Portale di governance di Microsoft Purview classico:
POST https://{{ENDPOINT}}.purview.azure.com/catalog/api/atlas/v2/types/typedefs
Nuovo portale di Microsoft Purview:
POST https://api.purview-service.microsoft.com/catalog/api/atlas/v2/types/typedefs
Con il corpo:
{
"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"
}
}
]
}
- Creare una definizione di relazione di tipo personalizzata effettuando una
POST
richiesta a uno dei due endpoint seguenti:
Portale di governance di Microsoft Purview classico:
POST https://{{ENDPOINT}}.purview.azure.com/catalog/api/atlas/v2/types/typedefs
Nuovo portale di Microsoft Purview:
POST https://api.purview-service.microsoft.com/catalog/api/atlas/v2/types/typedefs
Con il corpo:
{
"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"
}
]
}
- Inizializzare un nuovo asset di tipo custom_type_parent effettuando una
POST
richiesta a uno dei due endpoint seguenti:
Portale di governance di Microsoft Purview classico:
POST https://{{ENDPOINT}}.purview.azure.com/catalog/api/atlas/v2/entity
Nuovo portale di Microsoft Purview:
POST https://api.purview-service.microsoft.com/catalog/api/atlas/v2/entity
Con il corpo:
{
"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"
}
}
}
Salvare il GUID come necessario in un secondo momento.
- Inizializzare un nuovo asset di tipo custom_type_child effettuando una
POST
richiesta a uno dei due endpoint seguenti:
Portale di governance di Microsoft Purview classico:
POST https://{{ENDPOINT}}.purview.azure.com/catalog/api/atlas/v2/entity
Nuovo portale di Microsoft Purview:
POST https://api.purview-service.microsoft.com/catalog/api/atlas/v2/entity
Con il corpo:
{
"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"
}
}
}
Salvare il GUID come necessario in un secondo momento.
- Inizializzare una nuova relazione di tipo custom_parent_child_relationship effettuando una
POST
richiesta a uno dei due endpoint seguenti:
Portale di governance di Microsoft Purview classico:
POST https://{{ENDPOINT}}.purview.azure.com/catalog/api/atlas/v2/relationship/
Nuovo portale di Microsoft Purview:
POST https://api.purview-service.microsoft.com/catalog/api/atlas/v2/relationship/
Con il corpo seguente:
Nota
Il GUID in end1 deve essere sostituito con il GUID dell'oggetto creato al passaggio 6.1 Il GUID in end2 deve essere sostituito con il GUID dell'oggetto creato al passaggio 6.2
{
"typeName": "custom_parent_child_relationship",
"end1": {
"guid": "...",
"typeName": "custom_type_parent"
},
"end2": {
"guid": "...",
"typeName": "custom_type_child"
}
}
Passare a Data Catalog in Microsoft Purview.
Selezionare Sfoglia.
Selezionare Per tipo di origine.
Selezionare Sample-Custom-Types.
Selezionare il First_parent_object:
Selezionare la scheda Proprietà :
È possibile visualizzare il First_child_object collegato.
Selezionare il First_child_object:
Selezionare la scheda Proprietà :
È possibile visualizzare l'oggetto Parent collegato.
Analogamente, è possibile selezionare la scheda Correlato e verrà visualizzata la relazione tra i due oggetti:
È possibile creare più elementi figlio inizializzando un nuovo asset figlio e inizializzando una relazione
Nota
QualifiedName è univoco per asset, pertanto il secondo elemento figlio deve essere chiamato in modo diverso, ad esempio: custom//custom_type_child:Second_child_object
Suggerimento
Se si elimina il First_parent_object si noterà che anche gli elementi figlio verranno rimossi a causa della relazione COMPOSITION scelta nella definizione.
Esistono diverse limitazioni note quando si usano tipi personalizzati che verranno migliorate in futuro, ad esempio:
- La scheda Relazione ha un aspetto diverso rispetto ai tipi predefiniti
- I tipi personalizzati non hanno icone
- La gerarchia non è supportata