Typdefinitionen und Erstellen benutzerdefinierter Typen
In diesem Tutorial wird erläutert, was Typdefinitionen sind, wie benutzerdefinierte Typen erstellt werden und wie Ressourcen mit benutzerdefinierten Typen in Microsoft Purview initialisiert werden.
In diesem Tutorial erfahren Sie Folgendes:
- So verwendet Microsoft Purview das Typsystem von Apache Atlas
- Erstellen eines neuen benutzerdefinierten Typs
- Erstellen von Beziehungen zwischen benutzerdefinierten Typen
- Initialisieren neuer Entitäten benutzerdefinierter Typen
Für dieses Tutorial benötigen Sie Folgendes:
Ein Azure-Konto mit einem aktiven Abonnement. Wenn Sie noch kein Konto haben, können Sie kostenlos ein Konto erstellen.
Ein aktives Microsoft Purview-Konto (vormals Azure Purview). Wenn Sie noch keines haben, lesen Sie den Leitfaden für die ersten Schritte mit Microsoft Purview kostenlos.
Ein Bearertoken für Ihr Microsoft Purview-Konto. Informationen zum Einrichten eines Bearertokens und zum Aufrufen beliebiger APIs finden Sie in der Dokumentation zum Authentifizieren von APIs für Microsoft Purview.
Ihr Apache Atlas-Endpunkt Ihres Microsoft Purview-Kontos. Abhängig von Ihrer Umgebung ist dies einer der beiden folgenden Endpunkte:
- Wenn Sie das klassische Microsoft Purview-Governanceportal verwenden:
https://{{ACCOUNTNAME}}.purview.azure.com/catalog
- Wenn Sie das neue Microsoft Purview-Portal verwenden:
https://api.purview-service.microsoft.com/catalog
- Wenn Sie das klassische Microsoft Purview-Governanceportal verwenden:
Hinweis
Bevor Sie mit dem praktischen Teil des Tutorials fortfahren, erläutern die ersten vier Abschnitte, was ein Systemtyp ist und wie er in Microsoft Purview verwendet wird. Alle weiter beschriebenen REST-API-Aufrufe verwenden das Bearertoken und den Endpunkt , die in den Voraussetzungen beschrieben werden.
Um direkt mit den Schritten zu springen, verwenden Sie die folgenden Links:
Ein Medienobjekt ist ein Metadatenelement, das eine digitale oder physische Ressource beschreibt. Zu den digitalen oder physischen Ressourcen, die als Ressourcen katalogisiert werden sollen, gehören:
- Datenquellen wie Datenbanken, Dateien und Datenfeed.
- Analytische Modelle und Prozesse.
- Geschäftsrichtlinien und -bedingungen.
- Infrastruktur wie der Server.
Microsoft Purview bietet Benutzern ein flexibles Typsystem , um die Definition des Medienobjekts zu erweitern, um neue Arten von Ressourcen einzuschließen, sobald diese relevant werden. Microsoft Purview basiert auf dem Typsystem von Apache Atlas. Alle von Microsoft Purview verwalteten Metadatenobjekte (Objekte) werden mithilfe von Typdefinitionen modelliert. Das Verständnis des Typsystems ist für die Erstellung neuer benutzerdefinierter Typen in Microsoft Purview von grundlegender Bedeutung.
Im Wesentlichen kann ein Typ als Klasse aus objektorientierter Programmierung (OOP) betrachtet werden:
- Es definiert die Eigenschaften, die diesen Typ darstellen.
- Jeder Typ wird durch seinen Namen eindeutig identifiziert.
- Ein Typ kann von einem supertType erben. Dies ist ein äquivalentes Konzept wie die Vererbung aus OOP. Ein Typ, der einen superType erweitert, erbt die Attribute des superType.
Sie können alle Typdefinitionen in Ihrem Microsoft Purview-Konto anzeigen, indem Sie eine GET
Anforderung an den Endpunkt Alle Typdefinitionen senden:
GET https://{{ENDPOINT}}/catalog/api/atlas/v2/types/typedefs
Apache Atlas verfügt über einige vordefinierte Systemtypen, die häufig als Supertypen verwendet werden.
Zum Beispiel:
Referenzierbar: Dieser Typ stellt alle Entitäten dar, nach denen mithilfe eines eindeutigen Attributs namens qualifiedName gesucht werden kann.
Asset: Dieser Typ erweitert sich von Referenceable und verfügt über andere Attribute wie Name, Beschreibung und Besitzer.
DataSet: Dieser Typ erweitert referenzierbar und Asset. Konzeptionell kann es verwendet werden, um einen Typ darzustellen, der Daten speichert. Typen, die DataSet erweitern, können mit einem Schema rechnen. Beispielsweise eine SQL-Tabelle.
Herkunft: Herkunftsinformationen helfen ihnen, den Ursprung der Daten und die Transformationen zu verstehen, die sie möglicherweise durchlaufen haben, bevor sie in einer Datei oder Tabelle eintreffen. Die Herkunft wird durch DataSet und Process berechnet: DataSets (Eingabe des Prozesses) wirken sich auf einige andere DataSets (Ausgabe des Prozesses) durch Prozess aus.
Um das Typsystem besser zu verstehen, sehen wir uns ein Beispiel an und sehen uns an, wie eine Azure SQL Table definiert ist.
Sie können die vollständige Typdefinition abrufen, indem Sie eine GET
Anforderung an den Typdefinitionsendpunkt senden:
GET https://{{ENDPOINT}}/catalog/api/atlas/v2/types/typedef/name/{name}
Tipp
Die {name} -Eigenschaft gibt an, an welcher Definition Sie interessiert sind. In diesem Fall sollten Sie azure_sql_table verwenden.
Unten sehen Sie ein vereinfachtes JSON-Ergebnis:
{
"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",
},
]
}
Basierend auf der JSON-Typdefinition sehen wir uns einige Eigenschaften an:
Das Kategoriefeld beschreibt, in welcher Kategorie Sich Ihr Typ befindet. Die Liste der von Apache Atlas unterstützten Kategorien finden Sie hier.
Das ServiceType-Feld ist nützlich, wenn Ressourcen nach Quelltyp in Microsoft Purview durchsucht werden. Der Diensttyp ist ein Einstiegspunkt, um alle Ressourcen zu finden, die demselben Diensttyp angehören – wie in ihrer Typdefinition definiert. Im folgenden Screenshot der Purview-Benutzeroberfläche beschränkt der Benutzer das Ergebnis auf die Entitäten, die mit Azure SQL Database in serviceType angegeben sind:
Hinweis
Azure SQL Datenbank wird mit demselben serviceType wie Azure SQL Table definiert.
SuperTypes beschreibt die "übergeordneten" Typen, von denen Sie "erben" möchten.
schemaElementsAttributes aus Optionen beeinflussen, was auf der Registerkarte Schema Ihres Medienobjekts in Microsoft Purview angezeigt wird.
Nachfolgend sehen Sie ein Beispiel dafür, wie die Registerkarte Schema für ein Objekt vom Typ Azure SQL Tabelle aussieht:
relationshipAttributeDefs werden über die Beziehungstypdefinitionen berechnet. In unserem JSON-Code können Sie sehen, dass schemaElementsAttributes auf das Beziehungsattribut namens columns verweist. Hierbei handelt es sich um eines der Elemente aus dem Array relationshipAttributeDefs , wie unten gezeigt:
... "relationshipAttributeDefs": [ ... { "name": "columns", "typeName": "array<azure_sql_column>", "isOptional": true, "cardinality": "SET", "relationshipTypeName": "azure_sql_table_columns", }, ]
Jede Beziehung verfügt über eine eigene Definition. Der Name der Definition befindet sich im attribut relationshipTypeName . In diesem Fall ist es azure_sql_table_columns.
- Die Kardinalität dieses Beziehungsattributs ist auf *SET festgelegt, was darauf hindeutet, dass es eine Liste verwandter Ressourcen enthält.
- Das zugehörige Objekt ist vom Typ azure_sql_column, wie im typeName-Attribut sichtbar.
Anders ausgedrückt: Das Beziehungsattribut columns bezieht die Azure SQL Tabelle mit einer Liste von Azure SQL Spalten, die auf der Registerkarte Schema angezeigt werden.
Jede Beziehung besteht aus zwei Enden, die als endDef1 und endDef2 bezeichnet werden.
Im vorherigen Beispiel war azure_sql_table_columns der Name der Beziehung, die eine Tabelle (endDef1) und ihre Spalten (endDef2) charakterisiert.
Für die vollständige Definition können Sie eine GET
Anforderung an den folgenden Endpunkt senden, indem Sie azure_sql_table_columns als Namen verwenden:
GET https://{{ENDPOINT}}/catalog/api/atlas/v2/types/typedef/name/azure_sql_table_columns
Unten sehen Sie ein vereinfachtes JSON-Ergebnis:
{
"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 ist der Name der Beziehungsdefinition. Der Wert, in diesem Fall azure_sql_table_columns wird im relationshipTypeName-Attribut der Entität verwendet, die über diese Beziehung verfügt, wie Sie im JSON-Code darauf verweisen können.
relationshipCategory ist die Kategorie der Beziehung und kann entweder COMPOSITION, AGGREGATION oder ASSOCIATION sein, wie hier beschrieben.
enDef1 ist das erste Ende der Definition und enthält die Attribute:
type ist der Typ der Entität, die diese Beziehung als end1 erwartet.
name ist das Attribut, das im Beziehungsattribut dieser Entität angezeigt wird.
Die Kardinalität ist entweder SINGLE, SET oder LIST.
isContainer ist ein boolescher Wert und gilt für die Kategorie der Einschlussbeziehung. Bei Festlegung auf TRUE an einem Ende gibt dies an, dass dieses Ende der Container des anderen Endes ist. Deshalb:
- Nur für die Kompositions- oder Aggregationskategoriebeziehungen kann und sollte an einem Ende isContainer auf true festgelegt sein.
- Für die Zuordnungskategoriebeziehung sollte die isContainer-Eigenschaft an keinem Ende auf true festgelegt sein.
endDef2 ist das zweite Ende der Definition und beschreibt ähnlich wie endDef1 die Eigenschaften des zweiten Teils der Beziehung.
Schema ist ein wichtiges Konzept, das widerspiegelt, wie Daten im Datenspeicher gespeichert und organisiert werden. Es spiegelt die Struktur der Daten und die Dateneinschränkungen der Elemente wider, die die Struktur erstellen.
Elemente im selben Schema können (aufgrund ihres Inhalts) unterschiedlich klassifiziert werden. Außerdem kann eine andere Transformation (Herkunft) nur für eine Teilmenge von Elementen erfolgen. Aufgrund dieser Aspekte kann Purview Schema- und Schemaelemente als Entitäten modellieren. Daher ist schema in der Regel ein Beziehungsattribut zur Datenobjektentität. Beispiele für Schemaelemente sind: Spalten einer Tabelle, JSON-Eigenschaften des JSON-Schemas, XML-Elemente des XML-Schemas usw.
Es gibt zwei Arten von Schemas:
Systeminternes Schema : Einige Systeme sind systemintern für das Schema. Wenn Sie beispielsweise eine SQL-Tabelle erstellen, müssen Sie vom System die Spalten definieren, die die Tabelle erstellen. In diesem Sinne spiegelt sich das Schema einer Tabelle in den zugehörigen Spalten wider.
Für Datenspeicher mit vordefiniertem Schema verwendet Purview die entsprechende Beziehung zwischen der Datenressource und den Schemaelementen, um das Schema widerzuspiegeln. Dieses Beziehungsattribut wird vom Schlüsselwort (keyword) schemaElementsAttribute in der options-Eigenschaft der Entitätstypdefinition angegeben.
Nicht systeminternes Schema : Einige Systeme erzwingen solche Schemaeinschränkungen nicht, aber Benutzer können es verwenden, um Strukturdaten zu speichern, indem sie einige Schemaprotokolle auf die Daten anwenden. Beispielsweise speichern Azure-Blobs Binärdaten und kümmern sich nicht um die Daten im binären Datenstrom. Daher ist ihr kein Schema bekannt, aber der Benutzer kann seine Daten mit Schemaprotokollen wie JSON serialisieren, bevor er sie im Blob speichert. In diesem Sinne wird das Schema von einigen zusätzlichen Protokollen verwaltet, und die entsprechende Validierung wird vom Benutzer erzwungen.
Für Datenspeicher ohne inhärentes Schema ist das Schemamodell unabhängig von diesem Datenspeicher. In solchen Fällen definiert Purview eine Schnittstelle für das Schema und eine Beziehung zwischen DataSet und Schema, die als dataset_attached_schemas bezeichnet wird. Dadurch wird jeder Entitätstyp, der von DataSet erbt, um ein Attribut für eine angefügteSchema-Beziehung zum Verknüpfen mit seiner Schemadarstellung zu erhalten.
Das obige beispiel Azure SQL Table weist ein systeminternes Schema auf. Die Informationen, die auf der Registerkarte Schema der Azure SQL Tabelle angezeigt werden, stammen aus der Azure SQL Spalte selbst.
Wenn Sie ein Spaltenelement auswählen, wird Folgendes angezeigt:
Die Frage ist: Wie hat Microsoft Purview die eigenschaft data_tye aus der Spalte ausgewählt und auf der Registerkarte Schema der Tabelle angezeigt?
Sie können die Typdefinition einer Azure SQL Column abrufen, indem Sie eine GET
Anforderung an den Endpunkt senden:
GET https://{{ENDPOINT}}/catalog/api/atlas/v2/types/typedef/name/{name}
Hinweis
{name} lautet in diesem Fall: azure_sql_column
Hier sehen Sie ein vereinfachtes JSON-Ergebnis:
{
"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
},
...
]
...
}
Hinweis
serviceType ist Azure SQL Datenbank, identisch mit der für die Tabelle.
- schemaAttributes ist auf data_type festgelegt, eines der Attribute dieses Typs.
Azure SQL Table hat schemaElementAttribute verwendet, um auf eine Beziehung zu verweisen, die aus einer Liste von Azure SQL Spalten besteht. Für die Typdefinition einer Spalte sind schemaAttribute definiert .
Auf diese Weise zeigt die Registerkarte Schema in der Tabelle die Attribute an, die in den schemaAttributes der zugehörigen Ressourcen aufgeführt sind.
Erstens, warum möchte jemand eine benutzerdefinierte Typdefinition erstellen?
Es kann Fälle geben, in denen kein integrierter Typ vorhanden ist, der der Struktur der Metadaten entspricht, die Sie in Microsoft Purview importieren möchten.
In diesem Fall muss eine neue Typdefinition definiert werden.
Hinweis
Die Verwendung von integrierten Typen sollte der Erstellung benutzerdefinierter Typen vorgezogen werden, wann immer dies möglich ist.
Nachdem wir nun ein allgemeines Verständnis von Typdefinitionen erhalten haben, lassen Sie uns benutzerdefinierte Typdefinitionen erstellen.
In diesem Tutorial möchten wir eine 1:n-Beziehung zwischen zwei Typen modellieren, die als custom_type_parent und custom_type_child bezeichnet werden.
Ein custom_type_child sollte auf ein übergeordnetes Element verweisen, während ein custom_type_parent auf eine Liste untergeordneter Elemente verweisen kann.
Sie sollten über eine 1:n-Beziehung miteinander verknüpft werden.
Tipp
Hier finden Sie einige Tipps zum Erstellen eines neuen benutzerdefinierten Typs.
- Erstellen Sie die custom_type_parent Typdefinition, indem Sie eine
POST
Anforderung an einen der beiden folgenden Endpunkte senden:
Klassisches Microsoft Purview-Governanceportal:
POST https://{{ENDPOINT}}.purview.azure.com/catalog/api/atlas/v2/types/typedefs
Neues Microsoft Purview-Portal:
POST https://api.purview-service.microsoft.com/catalog/api/atlas/v2/types/typedefs
Mit dem Körper:
{
"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"
}
}
]
}
- Erstellen Sie die custom_type_child Typdefinition, indem Sie eine
POST
Anforderung an einen der beiden folgenden Endpunkte senden:
Klassisches Microsoft Purview-Governanceportal:
POST https://{{ENDPOINT}}.purview.azure.com/catalog/api/atlas/v2/types/typedefs
Neues Microsoft Purview-Portal:
POST https://api.purview-service.microsoft.com/catalog/api/atlas/v2/types/typedefs
Mit dem Körper:
{
"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"
}
}
]
}
- Erstellen Sie eine benutzerdefinierte Typbeziehungsdefinition, indem Sie eine
POST
Anforderung an einen der beiden folgenden Endpunkte senden:
Klassisches Microsoft Purview-Governanceportal:
POST https://{{ENDPOINT}}.purview.azure.com/catalog/api/atlas/v2/types/typedefs
Neues Microsoft Purview-Portal:
POST https://api.purview-service.microsoft.com/catalog/api/atlas/v2/types/typedefs
Mit dem Körper:
{
"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"
}
]
}
- Initialisieren Sie ein neues Medienobjekt vom Typ custom_type_parent , indem Sie eine
POST
Anforderung an einen der beiden folgenden Endpunkte senden:
Klassisches Microsoft Purview-Governanceportal:
POST https://{{ENDPOINT}}.purview.azure.com/catalog/api/atlas/v2/entity
Neues Microsoft Purview-Portal:
POST https://api.purview-service.microsoft.com/catalog/api/atlas/v2/entity
Mit dem Körper:
{
"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"
}
}
}
Speichern Sie die GUID , da Sie sie später benötigen.
- Initialisieren Sie ein neues Medienobjekt vom Typ custom_type_child , indem Sie eine
POST
Anforderung an einen der beiden folgenden Endpunkte senden:
Klassisches Microsoft Purview-Governanceportal:
POST https://{{ENDPOINT}}.purview.azure.com/catalog/api/atlas/v2/entity
Neues Microsoft Purview-Portal:
POST https://api.purview-service.microsoft.com/catalog/api/atlas/v2/entity
Mit dem Körper:
{
"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"
}
}
}
Speichern Sie die GUID , da Sie sie später benötigen.
- Initialisieren Sie eine neue Beziehung vom Typ custom_parent_child_relationship , indem Sie eine
POST
Anforderung an einen der beiden folgenden Endpunkte senden:
Klassisches Microsoft Purview-Governanceportal:
POST https://{{ENDPOINT}}.purview.azure.com/catalog/api/atlas/v2/relationship/
Neues Microsoft Purview-Portal:
POST https://api.purview-service.microsoft.com/catalog/api/atlas/v2/relationship/
Mit folgendem Text:
Hinweis
Die GUID in end1 muss durch die GUID des objekts ersetzt werden, das in Schritt 6.1 erstellt wurde. Die GUID in end2 muss durch die GUID des objekts ersetzt werden, das in Schritt 6.2 erstellt wurde.
{
"typeName": "custom_parent_child_relationship",
"end1": {
"guid": "...",
"typeName": "custom_type_parent"
},
"end2": {
"guid": "...",
"typeName": "custom_type_child"
}
}
Wechseln Sie zu Data Catalog in Microsoft Purview.
Wählen Sie Durchsuchen aus.
Wählen Sie Nach Quelltyp aus.
Wählen Sie Sample-Custom-Types aus.
Wählen Sie die First_parent_object aus:
Wählen Sie die Registerkarte Eigenschaften aus:
Sie können sehen, dass die First_child_object dort verknüpft ist.
Wählen Sie die First_child_object aus:
Wählen Sie die Registerkarte Eigenschaften aus:
Sie können sehen, dass das übergeordnete Objekt dort verknüpft ist.
Auf ähnliche Weise können Sie die Registerkarte Verknüpft auswählen und die Beziehung zwischen den beiden Objekten sehen:
Sie können mehrere untergeordnete Elemente erstellen, indem Sie ein neues untergeordnetes Objekt initialisieren und eine Beziehung initiieren.
Hinweis
QualifiedName ist pro Medienobjekt eindeutig. Daher sollte das zweite untergeordnete Element anders aufgerufen werden, z. B.: custom//custom_type_child:Second_child_object
Tipp
Wenn Sie die First_parent_object werden Sie feststellen, dass die untergeordneten Elemente aufgrund der COMPOSITION-Beziehung , die wir in der Definition ausgewählt haben, ebenfalls entfernt werden.
Es gibt mehrere bekannte Einschränkungen bei der Arbeit mit benutzerdefinierten Typen, die in Zukunft verbessert werden, z. B.:
- Registerkarte "Beziehung" sieht anders aus als integrierte Typen
- Benutzerdefinierte Typen haben keine Symbole
- Hierarchie wird nicht unterstützt
Verwalten von MicrosoftPurview-DATENebenen-REST-APIs für Datenquellen