型定義とカスタム型の作成方法

[アーティクル]
06/06/2024

このチュートリアルでは、型定義とは何か、カスタム型を作成する方法、および Microsoft Purview でカスタム型の資産を初期化する方法について説明します。

このチュートリアルでは以下を学習します。

Microsoft Purview が Apache Atlas の型システムを使用する方法
新しいカスタム型を作成する方法
カスタム型間のリレーションシップを作成する方法
カスタム型の新しいエンティティを初期化する方法

前提条件

このチュートリアルでは、次のものが必要です。

アクティブなサブスクリプションを持つ Azure アカウント。アカウントをお持ちでない場合は、無料でアカウントを作成できます。
アクティブな Microsoft Purview (旧称 Azure Purview) アカウント。お持ちでない場合は、 Microsoft Purview の使用を無料で開始するためのガイドを参照してください。
Microsoft Purview アカウントへのベアラートークン。ベアラートークンを確立し、すべての API を呼び出すには、 Microsoft Purview の API を認証する方法に関するドキュメントを参照してください。
Microsoft Purview アカウントの Apache Atlas エンドポイント。環境に応じて、次の 2 つのエンドポイントのいずれかになります。
- 従来の Microsoft Purview ガバナンスポータルを使用している場合:https://{{ACCOUNTNAME}}.purview.azure.com/catalog
- 新しい Microsoft Purview ポータルを使用している場合:https://api.purview-service.microsoft.com/catalog

注:

チュートリアルの実践的な部分に進む前に、最初の 4 つのセクションでは、システムの種類と、それが 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: この型は、参照可能と資産を拡張します。概念的には、データを格納する型を表すために使用できます。 DataSet を拡張する型には、スキーマが必要です。たとえば、SQL テーブルです。
系列: 系列情報は、データの配信元と、ファイルまたはテーブルに到着する前に行った可能性のある変換を理解するのに役立ちます。系列は、DataSet と Process: DataSets (プロセスの入力) によって計算され、プロセスを通じて他の DataSets (プロセスの出力) に影響します。

型定義の例

型システムについて理解を深めるために、例を見て、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 Database で指定されたエンティティに制限しています。

注:

Azure SQL Database は、Azure SQL Table と同じ serviceType で定義されます。
SuperTypes では、"継承" する "親" 型について説明します。
オプションの schemaElementsAttributes は、Microsoft Purview の資産の [スキーマ] タブに表示される内容に影響します。

次に、テーブルの種類の資産の [スキーマ] タブがどのように表示されるかAzure SQL例を示します。
relationshipAttributeDefs は、リレーションシップ型の定義を使用して計算されます。 JSON では、 schemaElementsAttributes が columns というリレーションシップ属性を指していることがわかります。これは、次に示すように、 relationshipAttributeDefs 配列の要素の 1 つです。
```
...
"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 と呼ばれる 2 つの端で構成されます。

前の例では、 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 値は、json で参照されているように、このリレーションシップを持つエンティティの relationshipTypeName 属性で使用されます。
relationshipCategory はリレーションシップのカテゴリであり、ここで説明するように COMPOSITION、AGGREGATION、ASSOCIATION のいずれかを指定できます。
enDef1 は定義の最初の末尾であり、属性が含まれています。
- type は、このリレーションシップが end1 と想定するエンティティの型です。
- name は、このエンティティのリレーションシップ属性に表示される属性です。
- カーディナリティ は、SINGLE、SET、LIST のいずれかです。
- isContainer はブール値であり、包含関係カテゴリに適用されます。一方の端で true に設定すると、この端がもう一方の端のコンテナーであることを示します。そこで：
  - コン ポジション または集計カテゴリのリレーションシップのみが、一方の端に isContainer を true に設定できる必要があります。
  - 関連付け カテゴリのリレーションシップには、 isContainer プロパティを true に設定しないでください。
endDef2 は定義の 2 番目の末尾であり、endDef1 と同様に、リレーションシップの 2 番目の部分のプロパティを記述します。

[スキーマ] タブ

Microsoft Purview のスキーマとは

スキーマは、データをデータストアに格納および整理する方法を反映する重要な概念です。これは、データの構造と、構造体を構築する要素のデータ制限を反映します。

同じスキーマ上の要素は、(コンテンツによって) 異なる方法で分類できます。また、異なる変換 (系列) は、要素のサブセットにのみ発生する可能性があります。これらの側面により、Purview はスキーマ要素とスキーマ要素を エンティティとしてモデル化できるため、スキーマは通常、データ資産エンティティに対するリレーションシップ属性です。スキーマ要素の例としては、テーブルの列、json スキーマの json プロパティ 、xml スキーマの xml 要素 などがあります。

スキーマには次の 2 種類があります。

組み込みスキーマ - 一部のシステムはスキーマに組み込まれています。たとえば、SQL テーブルを作成する場合、システムではテーブルを構築する列を定義する必要があります。この意味では、テーブルのスキーマは列によって反映されます。

定義済みのスキーマを持つデータストアの場合、Purview は、データ資産とスキーマ要素の間の対応するリレーションシップを使用してスキーマを反映します。このリレーションシップ属性は、エンティティ型定義の options プロパティで、キーワード (keyword) schemaElementsAttribute によって指定されます。
非組み込みスキーマ - 一部のシステムではこのようなスキーマ制限が適用されませんが、ユーザーは、一部のスキーマプロトコルをデータに適用することで、それを使用して構造データを格納できます。たとえば、Azure BLOB はバイナリデータを格納し、バイナリストリーム内のデータを気にしません。そのため、どのスキーマも認識できませんが、ユーザーは json などのスキーマプロトコルを使用してデータをシリアル化してから BLOB に格納できます。この意味では、スキーマは、いくつかの追加のプロトコルと、ユーザーによって適用される対応する検証によって維持されます。

固有のスキーマのないデータストアの場合、スキーマモデルはこのデータストアに依存しません。このような場合、Purview は、スキーマのインターフェイスと、dataSet とスキーマの間のリレーションシップを定義 します。dataset_attached_schemas と呼ばれます。これにより、DataSet から継承するすべてのエンティティ型が拡張され、スキーマ表現にリンクする attachedSchema リレーションシップ属性が設定されます。

[スキーマ] タブの例

上記のAzure SQL Table の例には、組み込みのスキーマがあります。 Azure SQL テーブルの [スキーマ] タブに表示される情報は、Azure SQL列自体から取得されます。

1 つの列項目を選択すると、次のようになります。

問題は、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 は 、この型の属性の 1 つである data_type に設定されます。

テーブルAzure SQL schemaElementAttribute を使用して、Azure SQL列の一覧で構成されるリレーションシップを指しています。列の型定義には schemaAttributes が定義されています 。

このように、テーブルの [スキーマ] タブには、関連する資産の schemaAttributes に一覧表示されている属性が表示されます。

カスタム型定義を作成する

どうしてでしょうか?

まず、カスタム型定義を作成したいのはなぜですか?

Microsoft Purview でインポートするメタデータの構造に対応する組み込み型がない場合があります。

このような場合は、新しい型定義を定義する必要があります。

注:

可能な限り、カスタム型の作成よりも組み込み型の使用を優先する必要があります。

一般的な型定義について理解を深めたので、カスタム型定義を作成しましょう。

シナリオ

このチュートリアルでは、 custom_type_parent と custom_type_childと呼ばれる 2 つの型間の 1:n リレーションシップをモデル化します。

custom_type_childは 1 つの親を参照する必要があります。一方、custom_type_parentは子の一覧を参照できます。

これらは、1:n リレーションシップを介してリンクする必要があります。

ヒント

ここでは、新しいカスタム型を作成するときのヒントをいくつか紹介します。

定義を作成する

次の 2 つのエンドポイントのいずれかに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"
            }
        }
    ]
 }

次の 2 つのエンドポイントのいずれかに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"
            }
        }
    ]
 }

次の 2 つのエンドポイントのいずれかに 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"
        }
    ]
}

カスタム型の資産を初期化する

次の 2 つのエンドポイントのいずれかに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 を 保存します。

次の 2 つのエンドポイントのいずれかに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 を 保存します。

次の 2 つのエンドポイントのいずれかに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 の [Data Catalog] に移動します。
[ 参照] を選択します。
[ ソースの種類] を選択します。
[ Sample-Custom-Types] を選択します。

$フィルターが Sample-Custom-Types に絞り込まれた [Browse assets]$アセットの参照$ へのData Catalogからのパスを示すスクリーンショット。$
First_parent_objectを選択します。
[ プロパティ ] タブを選択します。
リンクされている First_child_object を確認できます。
First_child_objectを選択します。
[ プロパティ ] タブを選択します。
Parent オブジェクトがそこにリンクされているのを確認できます。
同様に、[ 関連 ] タブを選択すると、2 つのオブジェクト間のリレーションシップが表示されます。
新しい子資産を初期化し、リレーションシップを初期化することで、複数の子を作成できます

注:

qualifiedName は資産ごとに一意であるため、2 番目の子は 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 のスキーマとは