類型定義和如何建立自定義類型

發行項
11/13/2024

本教學課程將說明什麼是類型定義、如何建立自定義類型，以及如何在 purview 中初始化自定義類型的資產Microsoft。

在本教學課程中，您將瞭解：

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 呼叫都會使用 持有人令牌 和必要條件中所述的端點。

若要直接跳至步驟，請使用下列連結：

建立自定義類型定義
初始化自定義類型的資產

Purview 中的資產和類型是什麼Microsoft？

資產是描述數位或實體資源的元數據元素。預期要編錄為資產的數位或實體資源包括：

數據源，例如資料庫、檔案和數據摘要。
分析模型和程式。
商務原則和條款。
基礎結構，例如伺服器。

Microsoft Purview 為使用者提供彈性 的類型系統 ，以擴充資產的定義，以在資源變成相關時包含新類型的資源。 Microsoft Purview 依賴來自 Apache Atlas 的類型系統。 Microsoft Purview 所管理) 資產 (所有元數據對象都會使用類型定義進行模型化。了解類型系統是在 Microsoft Purview 中建立新自定義型別的基礎。

基本上，類型可以從面向物件程序設計 (OOP) 中視為類別：

它會定義代表該類型的屬性。
每個類型都會以其名稱唯一識別。
類型可以繼承自 supertType。這是與 OOP 繼承相同的概念。擴充 superType 的類型會繼承 superType 的屬性。

您可以將要求傳送 GET 至 [所有類型定義] 端點，以查看 Microsoft Purview 帳戶中的所有類型定義：

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

Apache Atlas 有幾個預先定義的系統類型，通常用來作為超級類型。

例如：

可參考：此類型代表可以使用稱為 qualifiedName 的唯一屬性來搜尋的所有實體。
資產：此類型可從可參考延伸，並具有其他屬性，例如：名稱、描述和 擁有者。
DataSet：此類型會擴充可參考和資產。在概念上，它可以用來表示儲存數據的類型。擴充 DataSet 的類型應該會有架構。例如，SQL 數據表。
譜系：譜系資訊可協助您了解數據的來源，以及在抵達檔案或數據表之前可能經過的轉換。譜系是透過 DataSet 和 Process 來計算：數據集 (處理程式的輸入) 影響其他某些資料集 (進程) 的輸出。

類型定義的範例

為了進一步瞭解 Type 系統，讓我們看看範例，並查看如何定義 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 支援的類別清單。
在 Purview 中依來源類型瀏覽資產時，ServiceType 欄位非常有用Microsoft。 服務類型會是尋找屬於相同服務類型之所有資產的進入點，如其類型定義中所定義。在 Purview UI 的下列螢幕快照中，使用者會將結果限制為 serviceType中 Azure SQL Database 所指定的實體：

注意事項

Azure SQL 資料庫定義的 serviceType 與數據表 Azure SQL 相同。
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 屬性中的關鍵詞 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 Database，與數據表相同

schemaAttributes 設定為 data_type，這是此類型的其中一個屬性。

Azure SQL 數據表使用 schemaElementAttribute 指向由 Azure SQL 數據行清單所組成的關聯性。數據行的類型定義已定義 schemaAttributes 。

如此一來，數據表中的 [架構] 索引卷標會顯示屬性 (相關資產的 schemaAttributes 中所列的) 。

建立自定義類型定義

為什麼？

首先，為什麼有人想要建立自定義類型定義？

在某些情況下，沒有任何內建類型對應至您想要在 Purview 中匯入之元數據的結構Microsoft。

在這種情況下，必須定義新的型別定義。

注意事項

應盡可能優先使用內建型別，而不是建立自定義類型。

既然我們已經瞭解一般類型的定義，讓我們建立自定義類型定義。

案例

在本教學課程中，我們想要建立兩種類型之間的 1：n 關聯性模型，稱為 custom_type_parent 和 custom_type_child。

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"
   }
}

檢視 Purview Microsoft中的資產

移至 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 關聯性而移除。

限制

使用未來將增強的自訂類型時，有數個已知限制，例如：

關聯性索引標籤看起來與內建類型不同
自定義類型沒有圖示
不支持階層

後續步驟

管理 Purview 數據平面 REST API Microsoft數據源

共用方式為

類型定義和如何建立自定義類型

必要條件

Purview 中的資產和類型是什麼Microsoft？

類型定義的範例

關聯性類型定義的範例

架構索引標籤

什麼是 Microsoft Purview 中的架構？

架構索引標籤的範例

建立自定義類型定義

為什麼？

案例

建立定義

初始化自定義類型的資產

檢視 Purview Microsoft中的資產

限制

後續步驟

意見反應

其他資源

共用方式為

類型定義和如何建立自定義類型

必要條件

Purview 中的 資產 和 類型 是什麼Microsoft？

類型定義的範例

關聯性類型定義的範例

架構索引標籤

什麼是 Microsoft Purview 中的架構？

架構索引標籤的範例

建立自定義類型定義

為什麼？

案例

建立定義

初始化自定義類型的資產

檢視 Purview Microsoft中的資產

限制

後續步驟

意見反應

其他資源

Purview 中的資產和類型是什麼Microsoft？