閱讀英文

共用方式為


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

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

在本教學課程中,您將瞭解:

  • Microsoft Purview 如何從 Apache Atlas 使用類型系統
  • 如何建立新的自定義類型
  • 如何建立自定義類型之間的關聯性
  • 如何初始化自定義類型的新實體

必要條件

在本教學課程中,您將需要:

注意

在移至教學課程的實作部分之前,前四個章節將說明什麼是系統類型,以及它在 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 數據表。

  • 譜系:譜系資訊可協助您了解數據的來源,以及在抵達檔案或數據表之前可能經過的轉換。 譜系是透過 DataSetProcess 來計算:數據集 (處理程式的輸入) 影響其他某些資料集 (進程) 的輸出。

顯示系統類型之間關聯性的圖表。

類型定義的範例

為了進一步瞭解 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 資料庫所指定的實體:

    入口網站的螢幕快照,其中顯示從 資料目錄 到 [流覽至來源類型] 的路徑,以及醒目提示的資產。

    注意

    Azure SQL 資料庫定義的 serviceType數據表 Azure SQL 相同。

  • SuperTypes 描述您想要從中「繼承」的「父系」類型。

  • 來自選項schemaElementsAttributes 會影響在 Microsoft Purview 中資產的 [架構] 索引卷標中顯示的內容。

    您可以在下列範例中看到 [架構] 索引標籤在資料表 Azure SQL 類型資產的外觀:

    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 數據行清單相關聯。

關聯性類型定義的範

每個關聯性都包含兩個端點,稱為 endDef1endDef2

在上一個範例中, 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 資料行本身。

選取一個數據行項目,我們會看到下列專案:

addressID 數據行頁面的螢幕快照,其中已開啟 [屬性] 索引標籤,並醒目提示數據類型。

問題是,Microsoft Purview 如何從數據行中選取 data_tye 屬性,並在數據表的 [架構] 索引標籤中顯示它?

[Azure SQL 數據表] 頁面的螢幕快照,其中已開啟架構頁面。

您可以對端點提出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_parentcustom_type_child

custom_type_child應該參考一個父系,而custom_type_parent可以參考子系列表。

它們應該透過 1:n 關聯性連結在一起。

提示

在這裡 ,您可以在建立新的自定義類型時找到一些秘訣。

建立定義

  1. 對下列兩個端點之一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"
            }
        }
    ]
 }
  1. 對下列兩個端點之一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"
            }
        }
    ]
 }
  1. 對下列兩個端點之一 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"
        }
    ]
}

初始化自定義類型的資產

  1. 對下列兩個端點之一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 ,以供稍後使用。

  1. 對下列兩個端點之一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 ,以供稍後使用。

  1. 對下列兩個端點之一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中的資產

  1. 移至 Microsoft Purview 中的 資料目錄。

  2. 選取 [瀏覽]

  3. 取 [依來源類型]

  4. 取 [Sample-Custom-Types]

    此螢幕快照顯示從 資料目錄 到瀏覽資產的路徑,篩選條件已縮小為 Sample-Custom-Types。

  5. 取First_parent_object

    First_parent_object頁面的螢幕快照。

  6. 選取 [ 屬性] 索引 標籤:

    [屬性] 索引卷標的螢幕快照,其中已醒目提示相關資產,其中顯示一個子資產。

  7. 您可以在該 處看到連結First_child_object

  8. 取First_child_object

    [First_child_object] 頁面的螢幕快照,其中顯示 [概觀] 索引標籤。

  9. 選取 [ 屬性] 索引 標籤:

    屬性頁面的螢幕快照,其中顯示具有單一父資產的相關資產。

  10. 您可以在該處看到 Parent 物件正在連結。

  11. 同樣地,您可以選取 [ 相關] 索 引標籤,並會看到兩個對象之間的關聯性:

    [相關] 索引卷標的螢幕快照,其中顯示子系和父系之間的關聯性。

  12. 您可以藉由初始化新的子資產和初始化關聯性來建立多個子系

    注意

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

    First_parent_object的螢幕快照,其中顯示兩個醒目提示的子資產。

    提示

    如果您刪除 First_parent_object 您會注意到子系也會因為我們在定義中選擇的 COMPOSITION 關聯性而移除。

限制

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

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

後續步驟