Определения типов и создание настраиваемых типов
В этом руководстве объясняется, что такое определения типов, как создавать настраиваемые типы и как инициализировать ресурсы настраиваемых типов в Microsoft Purview.
В этом руководстве вы узнаете:
- Как Microsoft Purview использует систему типов из Apache Atlas
- Создание пользовательского типа
- Создание связей между пользовательскими типами
- Инициализация новых сущностей пользовательских типов
Для работы с этим руководством вам потребуется:
Учетная запись Azure с активной подпиской. Если у вас ее нет, вы можете создать учетную запись бесплатно.
Активная учетная запись Microsoft Purview (ранее Azure Purview). Если у вас ее нет, ознакомьтесь с руководством по началу работы с Microsoft Purview бесплатно.
Токен носителя для учетной записи Microsoft Purview. Сведения о том, как установить токен носителя и вызвать любые API, см. в документации по проверке подлинности API для Microsoft Purview.
Конечная точка Apache Atlas учетной записи Microsoft Purview. Это будет одна из этих двух конечных точек в зависимости от вашей среды:
- Если вы используете классический портал управления Microsoft Purview:
https://{{ACCOUNTNAME}}.purview.azure.com/catalog
- Если вы используете новый портал Microsoft Purview:
https://api.purview-service.microsoft.com/catalog
- Если вы используете классический портал управления Microsoft Purview:
Примечание
Прежде чем перейти к практической части учебника, в первых четырех разделах объясняется, что такое тип системы и как он используется в Microsoft Purview. Все описанные далее вызовы REST API будут использовать токен носителя и конечную точку , описанные в предварительных требованиях.
Чтобы перейти непосредственно к шагам, воспользуйтесь следующими ссылками:
Ресурс — это элемент метаданных, описывающий цифровой или физический ресурс. Цифровые или физические ресурсы, которые должны быть каталогированы как ресурсы, включают:
- Источники данных, такие как базы данных, файлы и канал данных.
- Аналитические модели и процессы.
- Бизнес-политики и условия.
- Инфраструктура, например сервер.
Microsoft Purview предоставляет пользователям гибкую систему типов для расширения определения ресурса, чтобы включить новые типы ресурсов по мере того, как они становятся актуальными. Microsoft Purview использует систему типов из Apache Atlas. Все объекты метаданных (ресурсы), управляемые Microsoft Purview, смоделированы с помощью определений типов. Понимание системы типов имеет основополагающее значение для создания новых настраиваемых типов в Microsoft Purview.
По сути, тип можно рассматривать как класс из объектно-ориентированного программирования (ООП):
- Он определяет свойства, представляющие этот тип.
- Каждый тип однозначно идентифицируется по имени.
- Тип может наследоваться от supertType. Это эквивалентное понятие, как наследование от ООП. Тип, расширяющий superType, наследует атрибуты superType.
Вы можете просмотреть все определения типов в учетной записи Microsoft Purview, отправив запрос к конечной GET
точке Определения всех типов :
GET https://{{ENDPOINT}}/catalog/api/atlas/v2/types/typedefs
Apache Atlas имеет несколько предопределенных системных типов, которые обычно используются в качестве супертипов.
Например:
Ссылка: этот тип представляет все сущности, которые можно искать с помощью уникального атрибута с именем qualifiedName.
Ресурс. Этот тип распространяется на ссылочный и имеет другие атрибуты, такие как имя, описание и владелец.
DataSet: этот тип расширяет возможности ссылок и активов. Концептуально его можно использовать для представления типа, в котором хранятся данные. Типы, расширяющие Набор данных, могут иметь схему. Например, таблица SQL.
Происхождение данных. Сведения о происхождении помогают понять источник данных и преобразования, которые они могли пройти перед поступлением в файл или таблицу. Происхождение вычисляется с помощью набора данных и процесса. Наборы данных (входные данные процесса) влияют на некоторые другие наборы данных (выходные данные процесса) через Процесс.
Чтобы лучше понять систему типов, давайте рассмотрим пример и посмотрим, как определяется таблица Azure SQL.
Полное определение типа можно получить, отправив GET
запрос к конечной точке определения типа:
GET https://{{ENDPOINT}}/catalog/api/atlas/v2/types/typedef/name/{name}
Совет
Свойство {name} указывает, какое определение вас интересует. В этом случае следует использовать azure_sql_table.
Ниже показан упрощенный результат JSON:
{
"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",
},
]
}
На основе определения типа JSON рассмотрим некоторые свойства:
Поле Category описывает, в какой категории относится ваш тип. Список категорий, поддерживаемых Apache Atlas, можно найти здесь.
Поле ServiceType полезно при просмотре ресурсов по типу источника в Microsoft Purview. Тип службы будет точкой входа для поиска всех ресурсов, принадлежащих одному и тому же типу службы, как определено в определении типа. На приведенном ниже снимке экрана пользовательского интерфейса Purview пользователь ограничивает результат сущностями, указанными Azure SQL Database в serviceType:
Примечание
Azure SQL База данных определяется с тем же типом serviceType, что и Azure SQL Table.
SuperTypes описывает "родительские" типы, от которого требуется "наследовать".
schemaElementsAttributes из параметров влияет на то, что отображается на вкладке Схема ресурса в Microsoft Purview.
Ниже приведен пример того, как выглядит вкладка Схема для ресурса типа Azure SQL Table:
relationshipAttributeDefs вычисляются с помощью определений типов связей. В нашем json мы видим, что schemaElementsAttributes указывает на атрибут связи с именем columns , который является одним из элементов из массива relationshipAttributeDefs , как показано ниже:
... "relationshipAttributeDefs": [ ... { "name": "columns", "typeName": "array<azure_sql_column>", "isOptional": true, "cardinality": "SET", "relationshipTypeName": "azure_sql_table_columns", }, ]
У каждой связи есть собственное определение. Имя определения находится в атрибуте relationshipTypeName . В этом случае это azure_sql_table_columns.
- Кратность этого атрибута связи имеет значение *SET, что предполагает, что он содержит список связанных ресурсов.
- Связанный ресурс имеет тип azure_sql_column, как видно в атрибуте typeName .
Другими словами, атрибут связи columns связывает таблицу Azure SQL со списком столбцов Azure SQL, которые отображаются на вкладке Схема.
Каждое отношение состоит из двух концов, называемых endDef1 и endDef2.
В предыдущем примере azure_sql_table_columns было именем связи, которая характеризует таблицу (endDef1) и ее столбцы (endDef2).
Для полного определения можно выполнить запрос к следующей конечнойGET
точке, используя azure_sql_table_columns в качестве имени:
GET https://{{ENDPOINT}}/catalog/api/atlas/v2/types/typedef/name/azure_sql_table_columns
Ниже показан упрощенный результат JSON:
{
"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 — это имя определения связи. Значение, в данном случае azure_sql_table_columns , используется в атрибуте relationshipTypeName сущности, которая имеет эту связь, как вы видите, на него ссылается json.
relationshipCategory — это категория связи, и она может быть либо COMPOSITION, AGGREGATION или ASSOCIATION, как описано здесь.
enDef1 является первым концом определения и содержит атрибуты:
type — это тип сущности, которая ожидается этим отношением как end1.
name — это атрибут, который будет отображаться в атрибуте связи этой сущности.
кратность имеет значение SINGLE, SET или LIST.
isContainer является логическим и применяется к категории отношений хранения. Если задано значение true на одном конце, это означает, что этот конец является контейнером другого конца. Следовательно:
- Только связи категории "Композиция " или "Агрегирование " могут иметь и должны иметь в одном конце значение isContainer , равное true.
- Отношение категории связи не должно иметь значение true в любом конце свойства isContainer .
endDef2 является вторым концом определения и описывает, как и endDef1, свойства второй части связи.
Схема — это важная концепция, отражающая хранение и организацию данных в хранилище данных. Он отражает структуру данных и ограничения данных элементов, создающих структуру.
Элементы в одной схеме можно классифицировать по-разному (из-за их содержимого). Кроме того, различные преобразования (происхождение) могут происходить только с подмножеством элементов. Благодаря этим аспектам Purview может моделировать схему и элементы схемы как сущности, поэтому схема обычно является атрибутом связи с сущностью ресурса данных. Примерами элементов схемы являются столбцы таблицы, свойства json схемы JSON, xml-элементы схемы xml и т. д.
Существует два типа схем:
Встроенная схема . Некоторые системы являются встроенными в схему. Например, при создании таблицы SQL система требует определить столбцы, которые создают таблицу; в этом смысле схема таблицы отражается в ее столбцах.
Для хранилища данных с предопределенной схемой Purview использует соответствующую связь между ресурсом данных и элементами схемы для отражения схемы. Этот атрибут связи задается ключевое слово schemaElementsAttribute в свойстве options определения типа сущности.
Не встроенная схема . Некоторые системы не применяют такие ограничения схемы, но пользователи могут использовать ее для хранения структурных данных, применяя к данным некоторые протоколы схемы. Например, blob-объекты Azure хранят двоичные данные и не заботятся о данных в двоичном потоке. Таким образом, он не знает о какой-либо схеме, но пользователь может сериализовать свои данные с помощью протоколов схемы, таких как JSON, прежде чем хранить их в BLOB-объекте. В этом смысле схема поддерживается некоторыми дополнительными протоколами и соответствующей проверкой, принудительной пользователем.
Для хранилища данных без присущей схемы модель схемы не зависит от этого хранилища данных. В таких случаях Purview определяет интерфейс для схемы и связь между DataSet и схемой, которая называется dataset_attached_schemas . Это расширяет любой тип сущности, наследующийся от DataSet, до атрибута присоединенной связиSchema для связи с их представлением схемы.
Приведенный выше пример таблицы Azure SQL содержит встроенную схему. Сведения, отображаемые на вкладке Схема таблицы Azure SQL, поступают из самих столбцов Azure SQL.
При выборе одного элемента столбца мы увидим следующее:
Вопрос в том, как Microsoft Purview выбрать свойство data_tye из столбца и показать его на вкладке Схема таблицы?
Определение типа столбца Azure SQL можно получить, выполнив GET
запрос к конечной точке:
GET https://{{ENDPOINT}}/catalog/api/atlas/v2/types/typedef/name/{name}
Примечание
{name} в этом случае имеет значение: azure_sql_column
Ниже приведен упрощенный результат JSON:
{
"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
},
...
]
...
}
Примечание
serviceType является Azure SQL Database, то же, что и для таблицы.
- параметр schemaAttributes имеет значение data_type, который является одним из атрибутов этого типа.
Azure SQL таблица использует schemaElementAttribute, чтобы указать на связь, состоящую из списка Azure SQL столбцов. Определение типа столбца содержит свойство schemaAttributes .
Таким образом, вкладка Схема в таблице отображает атрибуты, перечисленные в schemaAttributes связанных ресурсов.
Во-первых, зачем кому-то создавать пользовательское определение типа?
Могут возникать случаи, когда отсутствует встроенный тип, соответствующий структуре метаданных, которые требуется импортировать в Microsoft Purview.
В этом случае необходимо определить новое определение типа.
Примечание
Использование встроенных типов следует по возможности предпочесть созданию пользовательских типов.
Теперь, когда мы получили представление об определениях типов в целом, давайте создадим пользовательские определения типов.
В этом руководстве мы хотели бы смоделировать связь 1:n между двумя типами, называемыми custom_type_parent и custom_type_child.
Custom_type_child должен ссылаться на одного родителя, в то время как custom_type_parent может ссылаться на список дочерних элементов.
Они должны быть связаны друг с другом через связь 1:n.
Совет
Здесь вы найдете несколько советов по созданию нового настраиваемого типа.
- Создайте определение типа custom_type_parent , выполнив
POST
запрос к одной из двух следующих конечных точек:
Классический портал управления Microsoft Purview:
POST https://{{ENDPOINT}}.purview.azure.com/catalog/api/atlas/v2/types/typedefs
Новый портал Microsoft Purview:
POST https://api.purview-service.microsoft.com/catalog/api/atlas/v2/types/typedefs
С текстом:
{
"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"
}
}
]
}
- Создайте определение типа custom_type_child , выполнив
POST
запрос к одной из следующих конечных точек:
Классический портал управления Microsoft Purview:
POST https://{{ENDPOINT}}.purview.azure.com/catalog/api/atlas/v2/types/typedefs
Новый портал Microsoft Purview:
POST https://api.purview-service.microsoft.com/catalog/api/atlas/v2/types/typedefs
С текстом:
{
"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"
}
}
]
}
- Создайте определение настраиваемого отношения типа,
POST
выполнив запрос к одной из следующих конечных точек:
Классический портал управления Microsoft Purview:
POST https://{{ENDPOINT}}.purview.azure.com/catalog/api/atlas/v2/types/typedefs
Новый портал Microsoft Purview:
POST https://api.purview-service.microsoft.com/catalog/api/atlas/v2/types/typedefs
С текстом:
{
"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"
}
]
}
- Инициализация нового ресурса типа custom_type_parent путем
POST
выполнения запроса к одной из двух следующих конечных точек:
Классический портал управления Microsoft Purview:
POST https://{{ENDPOINT}}.purview.azure.com/catalog/api/atlas/v2/entity
Новый портал Microsoft Purview:
POST https://api.purview-service.microsoft.com/catalog/api/atlas/v2/entity
С текстом:
{
"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"
}
}
}
Сохраните guid так, как он понадобится вам позже.
- Инициализация нового ресурса типа custom_type_child путем
POST
выполнения запроса к одной из двух следующих конечных точек:
Классический портал управления Microsoft Purview:
POST https://{{ENDPOINT}}.purview.azure.com/catalog/api/atlas/v2/entity
Новый портал Microsoft Purview:
POST https://api.purview-service.microsoft.com/catalog/api/atlas/v2/entity
С текстом:
{
"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"
}
}
}
Сохраните guid так, как он понадобится вам позже.
- Инициализируйте новое отношение типа custom_parent_child_relationship , выполнив
POST
запрос к одной из двух следующих конечных точек:
Классический портал управления Microsoft Purview:
POST https://{{ENDPOINT}}.purview.azure.com/catalog/api/atlas/v2/relationship/
Новый портал Microsoft Purview:
POST https://api.purview-service.microsoft.com/catalog/api/atlas/v2/relationship/
Со следующим текстом:
Примечание
Guid в end1 должен быть заменен guid объекта, созданного на шаге 6.1. Guid в end2 должен быть заменен guid объекта, созданного на шаге 6.2.
{
"typeName": "custom_parent_child_relationship",
"end1": {
"guid": "...",
"typeName": "custom_type_parent"
},
"end2": {
"guid": "...",
"typeName": "custom_type_child"
}
}
Перейдите к Каталог данных в Microsoft Purview.
Нажмите кнопку Обзор.
Выберите По типу источника.
Выберите Sample-Custom-Types.
Выберите First_parent_object:
Перейдите на вкладку Свойства :
Вы увидите First_child_object , связанные там.
Выберите First_child_object:
Перейдите на вкладку Свойства :
Вы увидите объект Parent, связанный с ней.
Аналогичным образом можно выбрать вкладку Связанные и увидеть связь между двумя объектами:
Можно создать несколько дочерних элементов путем инициализации нового дочернего ресурса и инициализации связи
Примечание
QualifiedName является уникальным для каждого ресурса, поэтому второй дочерний элемент должен вызываться по-другому, например: custom//custom_type_child:Second_child_object
Совет
При удалении First_parent_object вы заметите, что дочерние элементы также будут удалены из-за связи COMPOSITION , выбранной в определении.
Существует несколько известных ограничений при работе с пользовательскими типами, которые будут расширены в будущем, например:
- Вкладка "Связь" выглядит иначе по сравнению со встроенными типами
- Пользовательские типы не имеют значков
- Иерархия не поддерживается