类型定义以及如何创建自定义类型

项目
11/13/2024

本教程将说明什么是类型定义、如何创建自定义类型以及如何在 Microsoft Purview 中初始化自定义类型的资产。

在本教程中，你将了解：

Microsoft Purview 如何使用 Apache Atlas 中的类型系统
如何创建新的自定义类型
如何在自定义类型之间创建关系
如何初始化自定义类型的新实体

先决条件

本教程需要：

具有活动订阅的 Azure 帐户。如果没有帐户，可以免费创建帐户。
活动Microsoft Purview (以前为 Azure Purview) 帐户。如果没有，请参阅免费Microsoft Purview 入门指南。
Microsoft Purview 帐户的持有者令牌。若要建立持有者令牌并调用任何 API，请参阅有关如何对 Microsoft Purview 的 API 进行身份验证的文档。
Microsoft Purview 帐户的 Apache Atlas 终结点。它将是以下两个终结点之一，具体取决于你的环境：
- 如果使用经典 Microsoft Purview 治理门户： https://{{ACCOUNTNAME}}.purview.azure.com/catalog
- 如果使用新的 Microsoft Purview 门户： https://api.purview-service.microsoft.com/catalog

注意

在转到本教程的动手部分之前，前四部分将说明什么是系统类型，以及如何在 Microsoft Purview 中使用它。进一步描述的所有 REST API 调用都将使用 持有者令牌 和先决条件中所述的 终结点 。

若要直接跳到步骤，请使用以下链接：

创建自定义类型定义
初始化自定义类型的资产

什么是 Microsoft Purview 中的资产和类型？

资产是描述数字或物理资源的元数据元素。应编录为资产的数字或物理资源包括：

数据源，例如数据库、文件和数据馈送。
分析模型和过程。
业务策略和条款。
基础结构，例如服务器。

Microsoft Purview 为用户提供了一个灵活的 类型系统 ，用于扩展资产的定义，以在资源变得相关时包括新类型的资源。 Microsoft Purview 依赖于 Apache Atlas 中的类型系统。 (资产) 由 Purview 管理的所有元数据对象Microsoft都使用类型定义进行建模。了解类型系统是在 Microsoft Purview 中创建新的自定义类型的基础。

从本质上讲，类型可以被视为面向对象的编程 (OOP) 的类：

它定义表示该类型的属性。
每个类型都由其名称唯一标识。
类型可以从 supertType 继承。这是与从 OOP 继承等效的概念。扩展 superType 的类型将继承 superType 的属性。

可以通过向“所有类型定义”终结点发送 GET 请求来查看 Microsoft Purview 帐户中的所有类型定义：

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

Apache Atlas 具有很少通常用作超类型的预定义系统类型。

例如：

可引用：此类型表示可以使用名为 qualifiedName 的唯一属性搜索的所有实体。
资产：此类型从可引用扩展，并具有其他属性，例如 ：名称、说明和 所有者。
数据集：此类型扩展了可引用和资产。从概念上讲，它可用于表示存储数据的类型。扩展 DataSet 的类型应具有架构。例如，SQL 表。
世系：世系信息有助于了解数据的来源以及数据在到达文件或表之前可能经历的转换。世系是通过 DataSet 和 Process 计算的：数据集 (进程输入) 影响其他一些数据集 (进程) 通过 Process 的输出。

类型定义示例

为了更好地了解类型系统，让我们看一个示例，并了解如何定义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 类型定义，我们来看看一些属性：

“类别” 字段描述你的类型所属的类别。可在此处找到 Apache Atlas 支持的类别列表。
在 Microsoft Purview 中按源类型浏览资产时，ServiceType 字段非常有用。 服务类型将是一个入口点，用于查找属于同一服务类型的所有资产（在其类型定义上定义）。在 Purview UI 的以下屏幕截图中，用户将结果限制为使用 serviceType 中的 Azure SQL Database 指定的实体：

注意

Azure SQL使用与 Azure SQL Table 相同的 serviceType 定义数据库。
SuperTypes 描述要从中“继承”的“父”类型。
来自选项的 schemaElementsAttributes 会影响 Microsoft Purview 中资产的“架构”选项卡中显示的内容。

下面可以看到表类型资产的“架构”选项卡外观示例Azure SQL：
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 属性中所示。
换句话说，列关系属性将“Azure SQL表”与“架构”选项卡中显示的Azure SQL列列表相关联。

关系类型定义示例

每个关系由两端组成，称为 endDef1 和 endDef2。

在前面的示例中， azure_sql_table_columns 是关系的名称，该关系 (endDef1) 及其列 (endDef2) 。

对于完整定义，可以使用 azure_sql_table_columns 作为名称向以下终结点发出GET请求：

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。
  - 关联类别关系不应在任何一端将 isContainer 属性设置为 true。
endDef2 是定义的第二端，与 endDef1 类似，描述了关系第二部分的属性。

“架构”选项卡

什么是 Microsoft Purview 中的架构？

架构是一个重要概念，它反映了数据存储中数据的存储和组织方式。它反映了数据结构和构造结构的元素的数据限制。

由于元素的内容) ，同一架构上的元素可以 (进行不同的分类。此外，不同的转换 (世系) 只能发生在元素的子集上。由于这些方面，Purview 可以将架构和架构元素 建模为实体，因此架构通常是数据资产实体的关系属性。架构元素的示例包括：表的列、json 架构的 json 属性 、xml 架构的 xml 元素 等。

有两种类型的架构：

内部架构 - 某些系统是架构固有的。例如，创建 SQL 表时，系统要求你定义构造表的列;从这个意义上说，表的架构由其列反映。

对于具有预定义架构的数据存储，Purview 使用数据资产与架构元素之间的相应关系来反映架构。此关系属性由实体类型定义的 options 属性中的关键字 (keyword) schemaElementsAttribute 指定。
非内部架构 - 某些系统不会强制实施此类架构限制，但用户可以通过对数据应用某些架构协议来使用它来存储结构数据。例如，Azure Blob 存储二进制数据，不关心二进制流中的数据。因此，它不知道任何架构，但用户可以先使用架构协议（如 json）序列化其数据，然后再将其存储在 Blob 中。从这个意义上说，架构由一些额外的协议和用户强制执行的相应验证来维护。

对于没有固有架构的数据存储，架构模型独立于此数据存储。对于此类情况，Purview 定义了架构的接口以及 DataSet 与架构之间的关系，称为 dataset_attached_schemas - 这会将继承自 DataSet 的任何实体类型扩展为具有 attachedSchema 关系属性，以链接到其架构表示形式。

“架构”选项卡的示例

上面的Azure SQL表示例具有内部架构。 Azure SQL表的“架构”选项卡中显示的信息来自Azure SQL列本身。

选择一个列项，将看到以下内容：

问题是，Microsoft Purview 如何从列中选择 data_tye 属性并将其显示在表的“架构”选项卡中？

可以通过向终结点发出GET请求来获取Azure SQL列的类型定义：

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 数据库，与表相同

schemaAttributes 设置为 data_type，这是此类型的属性之一。

Azure SQL Table 使用 schemaElementAttribute 指向由Azure SQL列列表组成的关系。列的类型定义定义了 schemaAttributes 。

通过这种方式，表中的“架构”选项卡显示 () 相关资产的 schemaAttributes 中列出的属性。

创建自定义类型定义

为什么？

首先，为什么有人想要创建自定义类型定义？

在某些情况下，没有与要在 Purview Microsoft 中导入的元数据结构相对应的内置类型。

在这种情况下，必须定义新的类型定义。

注意

应尽可能使用内置类型，而不要创建自定义类型。

现在我们已经大致了解了类型定义，让我们创建自定义类型定义。

应用场景

在本教程中，我们要对两种类型（称为 custom_type_parent 和 custom_type_child ）之间的 1：n 关系建模。

custom_type_child应引用一个父级，而custom_type_parent可以引用子级列表。

它们应通过 1：n 关系链接在一起。

提示

在创建新的自定义类型时，可在此处找到一些提示。

创建定义

通过向以下两个终结点之一POST发出请求来创建custom_type_parent类型定义：

经典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"
            }
        }
    ]
 }

通过向以下两个终结点之一POST发出请求来创建custom_type_child类型定义：

经典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"
        }
    ]
}

初始化自定义类型的资产

通过向以下两个终结点之一POST发出请求，初始化 custom_type_parent 类型的新资产：

经典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 ，因为稍后将需要它。

通过向以下两个终结点之一POST发出请求，初始化 custom_type_child 类型的新资产：

经典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 ，因为稍后将需要它。

通过向以下两个终结点之一POST发出请求，初始化 custom_parent_child_relationship 类型的新关系：

经典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/

使用以下正文：

注意

end1 中的 guid 必须替换为在步骤 6.1 中创建的对象的 guid。 end2 中的 guid 必须替换为步骤 6.2 中创建的对象的 guid

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

查看 Microsoft Purview 中的资产

转到 Microsoft Purview 中的统一目录。
选择“ 浏览”。
选择“ 按源类型”。
选择 “Sample-Custom-Types”。
选择 First_parent_object：
选择“ 属性” 选项卡：
可以看到 链接First_child_object 。
选择 First_child_object：
选择“ 属性” 选项卡：
可以看到父对象正在链接在那里。
同样，可以选择“ 相关 ”选项卡，并会看到这两个对象之间的关系：
可以通过初始化新的子资产并初始化关系来创建多个子级

注意

qualifiedName 对于每个资产是唯一的，因此，第二个子级应以不同的方式调用，例如：custom//custom_type_child：Second_child_object

提示

如果删除 First_parent_object 你会注意到，由于我们在定义中选择的 COMPOSITION 关系，子级也会被删除。

限制

使用将来将增强的自定义类型时，有几个已知限制，例如：

与内置类型相比，“关系”选项卡看起来不同
自定义类型没有图标
不支持层次结构

后续步骤

Microsoft Purview 数据平面 REST API 管理数据源

通过

类型定义以及如何创建自定义类型

先决条件

什么是 Microsoft Purview 中的资产和类型？

类型定义示例

关系类型定义示例

“架构”选项卡

什么是 Microsoft Purview 中的架构？

“架构”选项卡的示例

创建自定义类型定义

为什么？

应用场景

创建定义

初始化自定义类型的资产

查看 Microsoft Purview 中的资产

限制

后续步骤

反馈

其他资源

通过

类型定义以及如何创建自定义类型

先决条件

什么是 Microsoft Purview 中的 资产 和 类型 ？

类型定义示例

关系类型定义示例

“架构”选项卡

什么是 Microsoft Purview 中的 架构 ？

“架构”选项卡的示例

创建自定义类型定义

为什么？

应用场景

创建定义

初始化自定义类型的资产

查看 Microsoft Purview 中的资产

限制

后续步骤

反馈

其他资源

什么是 Microsoft Purview 中的资产和类型？

什么是 Microsoft Purview 中的架构？