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

项目
07/02/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.cn/catalog
- 如果使用新的 Microsoft Purview 门户：https://api.purview-service.microsoft.com/catalog

注意

本教程的实践部分之前的四个部分将解释什么是系统类型，以及如何在 Microsoft Purview 中使用系统类型。后续介绍的所有 REST API 调用都将使用先决条件中所述的持有者令牌和终结点。

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

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

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

资产是描述数字或物理资源的元数据元素。预期将编目为资产的数字或物理资源包括：

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

Microsoft Purview 为用户提供灵活的类型系统来扩展资产的定义，以包括相关的新型资源。 Microsoft Purview 依赖于 Apache Atlas 中的类型系统。 Microsoft Purview 管理的所有元数据对象（资产）都是通过类型定义建模的。只有了解类型系统，才能在 Microsoft Purview 中创建新的自定义类型。

从本质上讲，可将类型 (type) 看作面向对象的编程 (OOP) 中的类：

type 定义了表示该类型的属性。
每个类型由其名称唯一标识。
type 可以从 supertType 继承。这种概念等效于 OOP 中的继承。扩展某个 superType 的 type 将继承该 superType 的属性。

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

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

Apache Atlas 具有少量几个预定义的系统类型，它们通常用作超类型。

例如：

可引用：此类型表示可以使用名为 qualifiedName 的唯一属性搜索的所有实体。
资产：此类型扩展自“可引用”类型并具有其他属性，例如：name、description 和 owner。
数据集：此类型扩展“可引用”和“资产”类型。从概念上讲，它可以用来表示一个存储数据的类型。扩展“数据集”的类型预期具有架构。例如，一个 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 支持的类别列表。
在 Microsoft Purview 中按源类型浏览资产时，ServiceType 字段非常有用。服务类型是一个入口点，用于查找属于同一服务类型（在资产类型定义中定义）的所有资产。在以下 Purview UI 屏幕截图中，用户将结果限制为 serviceType 中通过 Azure SQL 数据库指定的实体：

注意

Azure SQL 数据库是使用与 Azure SQL 表相同的 serviceType 定义的。
SuperTypes 描述要从中“继承”的“父”类型。
options 中的 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，这表明它保存了相关资产的列表。
- 相关资产的类型为 typeName 属性中所示的 azure_sql_column。
换言之，columns 关系属性将 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 是将在此实体的关系属性中显示的属性。
- cardinality 可以是 SINGLE、SET 或 LIST。
- isContainer 是一个布尔值，适用于包含关系类别。当一端设置为 true 时，表示这一端是另一端的容器。因此：
  - 只有 Composition 或 Aggregation 类别关系可以而且应该在一端将 isContainer 设置为 true。
  - Association 类别关系不应在任何一端将 isContainer 属性设置为 true。
endDef2 是定义的第二端，与 endDef1 类似，它描述关系的第二个部分的属性。

架构选项卡

Microsoft Purview 中的架构是什么？

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

可以按不同的方式将同一架构中的元素分类（因为其内容不同）。此外，可以仅针对元素的子集进行不同的转换（世系）。由于这些特性，Purview 可以将架构和架构元素建模为实体，因此架构通常是数据资产实体的关系属性。架构元素的示例：表的列、json 架构的 json 属性、xml 架构的 xml 元素等。

有两种类型的架构：

固有架构 - 某些系统是架构所固有的。例如，当你创建 SQL 表时，系统会要求你定义构成该表的列；从这种意义上讲，表的架构由其列反映。

对于使用预定义架构的数据存储，Purview 将利用数据资产与架构元素之间的对应关系来反映架构。此关系属性由实体类型定义的 options 属性中的关键字 schemaElementsAttribute 指定。
非固有架构 - 某些系统不强制实施此类架构限制，但用户可以通过对数据应用某些架构协议，来使用此类架构存储结构数据。例如，Azure Blob 存储二进制数据但不关心二进制流中的数据。因此，它不知道任何架构，但用户可以在 Blob 中存储数据之前使用 JSON 等架构协议将数据序列化。从这种意义上讲，架构是由某些附加协议及用户强制实施的相应验证来维护的。

对于不使用固有架构的数据存储，架构模型独立于此数据存储。对于这种情况，Purview 定义了架构的接口，以及数据集与架构之间的关系（名为 dataset_attached_schemas）- 这扩展了从数据集继承的任何实体类型，使其具有一个用于链接到其架构表示形式的 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 表使用 schemaElementAttribute 指向由 Azure SQL 列列表组成的关系。列的类型定义定义了 schemaAttributes。

这样，表中的“架构”选项卡将显示相关资产的 schemaAttributes 中列出的属性。

创建自定义类型定义

为什么？

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

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

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

注意

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

大致了解类型定义后，接下来让我们创建自定义类型定义。

方案

在本教程中，我们希望为两个类型（名为 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.cn/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.cn/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.cn/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.cn/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.cn/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.cn/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 关系。