類型定義以及如何建立自訂類型

本教學課程將說明什麼是類型定義、如何建立自訂類型，以及如何在 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 的類型系統。 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：此型別會擴充 Referenceable 和 Asset。從概念上講，它可以用來表示儲存資料的類型。擴充 DataSet 的類型可以預期具有結構描述。例如，SQL 資料表。
譜系：譜系資訊可協助人們了解資料的來源以及資料在到達檔案或表格之前可能經歷的轉換。譜系是透過 DataSet 和 Process 計算：DataSet (進程的輸入) 影響其他一些 DataSet (透過 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 支援的類別清單，請參閱此處。
ServiceType 欄位在 Microsoft Purview 中依 來源類型流 覽資產時很有用。 服務類型將是尋找屬於相同服務類型的所有資產的進入點 - 如其類型定義上所定義。在下列 Purview UI 螢幕擷取畫面中，使用者會將結果限制為在 serviceType 中使用 Azure SQL 資料庫指定的實體：

注意事項

Azure SQL 資料庫的定義方式與 Azure SQL 資料表相同的 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時，表示這一端是另一端的容器。以：
  - 只有 Composition 或 Aggregation 類別關聯性可以而且應該在一端將 isContainer 設定為 true。
  - 關聯類別關聯性不應在任何結尾將 isContainer 屬性設定為 true。
endDef2 是定義的第二端，與 endDef1 類似，描述關係第二部分的屬性。

結構描述標籤

什麼是 Microsoft Purview 中的架構？

架構是一個重要的概念，它反映了資料在資料存放區中的儲存和組織方式。它反映了資料的結構以及建構結構的元素的資料限制。

相同結構描述上的元素可以因其內容) 而 (以不同的方式分類。此外， (譜系) 的不同轉換可能只發生在元素的子集上。由於這些層面，Purview 可以將架構和架構元素建模 為實體，因此架構通常是數據資產實體的關聯性屬性。結構描述元素的範例包括：表格的列、json 結構描述的 json 屬性 、xml 結構描述的 xml 元素 等。

結構描述有兩種類型：

固有結構描述 — 某些系統是結構描述固有的。例如，當您建立 SQL 表格時，系統會要求您定義建構表格的直欄;從這個意義上說，表格的結構描述由其列反映。

針對具有預先定義架構的資料存放區，Purview 會使用資料資產與架構元素之間的對應關聯性來反映架構。此關聯性屬性是由實體類型定義的選項屬性中的關鍵字 schemaElementsAttribute 指定。
非固有結構描述 - 某些系統不會強制執行此類結構描述限制，但使用者可以透過將一些結構描述協定套用至資料來使用它來儲存結構資料。例如，Azure Blob 會儲存二進位資料，而且不在乎二進位資料流程中的資料。因此，它不知道任何結構描述，但使用者可以在將資料儲存在 blob 中之前，先使用 json 等架構協定序列化其資料。從這個意義上說，模式由一些額外的協議和用戶強制執行的相應驗證來維護。

對於沒有固有結構描述的資料存放區，結構描述模型與此資料存放區無關。針對這類情況，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 資料表使用 schemaElementAttribute 指向由 Azure SQL 資料行清單所組成的關聯性。資料行的類型定義已定義 schemaAttributes 。

如此一來，表格中的結構描述索引標籤會顯示相關資產的 schemaAttributes 中列出的屬性 () 。

建立自訂類型定義

為什麼？

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

在某些情況下，可能沒有內建類型對應至您想要在 Microsoft Purview 中匯入的中繼資料結構。

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

注意事項

盡可能使用內建類型，而不是建立自訂類型。

現在我們已經對類型定義有了一般的了解，讓我們建立自訂類型定義。

案例

在本教學課程中，我們想要建立兩種類型之間的 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 中建立之物件的 guidend2 中的 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：
選取 [屬性] 索引標籤：
您可以看到 Parent 物件正在連結到那裡。
同樣地，您可以選取相關索引標籤，並會看到兩個物件之間的關係：
您可以初始化新的子資產並初始化關係，以建立多個子項

注意事項

qualifiedName 每個資產都是唯一的，因此，第二個子系應該以不同的方式呼叫，例如：custom//custom_type_child：Second_child_object

提示

如果您刪除 First_parent_object 您會注意到，由於我們在定義中選擇的 COMPOSITION 關係，子項也將被刪除。