次の方法で共有

REST API を使用してリレーションシップを作成して取得する

  • [アーティクル]

このチュートリアルでは、Purview REST API を使用して次の操作を行う方法について説明します。

  1. データ資産間の資産と系列関係を作成します。
  2. 系列のリレーションシップ/パスを照会します。

この記事で参照されている API:

前提条件

これらの API を使用するには、 データ キュレーターロールとデータ閲覧者ロールが必要です。 アクセス トークンを取得する方法の詳細については、 このチュートリアル を参照してください。

概念

Asset

Purview には、DataSet と Process という 2 種類の基本資産があります。

  • Azure SQL Table、Oracle Table などのデータを含む DataSet 資産は、DataSet から継承する必要があります。
  • データ パイプライン、クエリ、関数などのデータを処理するプロセス資産は、Process から継承する必要があります。

DataSets とプロセスの型定義については、資産と型を参照してください。

系列 & リレーションシップ

Microsoft Purview では、系列に対して次の 3 種類のリレーションシップを定義します。

  • dataset_process_inputs: DataSet を Process に接続します。つまり、DataSet はプロセスの入力です
  • process_dataset_outputs: プロセスを DataSet に接続します。つまり、プロセスによって DataSet が生成されます。
  • direct_lineage_dataset_dataset: DataSet1 を DataSet2 に接続します。つまり、DataSet1 は DataSet2 のアップストリームですが、それらの間にどのプロセスが含まれているかは正確にはわかりません。

例 1:2 つの DataSet、1 つのプロセス、2 つの系列リレーションシップを持つ系列の例を次に示します。

データセット ---> dataset_process_inputs ---> DataSet ---> process_dataset_outputs ---> プロセス

DataSet から DataSet 系列への処理を示すスクリーンショット。

例 2:2つの DataSet と 1 つの系列関係を持つ系列の別の例:

Dataset ---> direct_lineage_dataset_dataset ---> DataSet

DataSet から DataSet 系列を示すスクリーンショット。

データ資産間の資産と系列関係を作成する

次のセクションでは、DataSet の型の例としてhive_tableを取り、Process の例としてhive_query_processしてみましょう。 これら 2 種類の資産を作成し、それらの間に系列を作成します。 DataSet または Process から継承する他の任意の型を使用して系列を作成できます。

例 1

API を使用して資産を作成する

系列を作成する資産がまだ Microsoft Purview で作成されていない場合は、次の API を呼び出して作成できます。

API: 資産の一括作成

タスク: データセットとして 2 つのhive_tables (table1 と table2) を作成し、それぞれ 2 つのhive_columns - column1 と column2 を使用します。

POST {endpoint}/datamap/api/atlas/v2/entity/bulk

本文の場合:

{
  "entities": [
    {
      "typeName": "hive_table",
      "attributes": {
        "qualifiedName": "test_lineage.table1",
        "name": "table1"
      },
      "relationshipAttributes": {
        "columns": [
          {
            "guid": "-11",
            "typeName": "hive_column"
          },{
            "guid": "-12",
            "typeName": "hive_column"
          }
        ]
      },
      "guid": "-1"
    },
    {
      "typeName": "hive_column",
      "attributes": {
        "qualifiedName": "test_lineage.table1#column1",
        "name": "column1",
        "type": "int"
      },
      "guid": "-11",
      "relationshipAttributes": {
        "table": {
          "guid": "-1",
          "typeName": "hive_table"
        }
      }
    },
    {
      "typeName": "hive_column",
      "attributes": {
        "qualifiedName": "test_lineage.table1#column2",
        "name": "column2",
        "type": "int"
      },
      "guid": "-12",
      "relationshipAttributes": {
        "table": {
          "guid": "-1",
          "typeName": "hive_table"
        }
      }
    },
    {
      "typeName": "hive_table",
      "attributes": {
        "qualifiedName": "test_lineage.table2",
        "name": "table2"
      },
      "relationshipAttributes": {
        "columns": [
          {
            "guid": "-21",
            "typeName": "hive_column"
          },{
            "guid": "-22",
            "typeName": "hive_column"
          }
        ]
      },
      "guid": "-2"
    },
    {
      "typeName": "hive_column",
      "attributes": {
        "qualifiedName": "test_lineage.table2#column1",
        "name": "column1",
        "type": "int"
      },
      "guid": "-21",
      "relationshipAttributes": {
        "table": {
          "guid": "-2",
          "typeName": "hive_table"
        }
      }
    },
    {
      "typeName": "hive_column",
      "attributes": {
        "qualifiedName": "test_lineage.table2#column2",
        "name": "column2",
        "type": "int"
      },
      "guid": "-22",
      "relationshipAttributes": {
        "table": {
          "guid": "-2",
          "typeName": "hive_table"
        }
      }
    }    
  ]
}

タスク: プロセス資産 'hive_view_query' を作成する

POST {endpoint}/datamap/api/atlas/v2/entity/bulk

本文の場合:

{
  "entities": [
    {
      "typeName": "hive_view_query",
      "attributes": {
        "qualifiedName": "test_lineage.HiveQuery1",
        "name": "HiveQuery1",
        "columnMapping": "[{\"DatasetMapping\":{\"Source\":\"test_lineage.table1\",\"Sink\":\"test_lineage.table2\"},\"ColumnMapping\":[{\"Source\":\"column1\",\"Sink\":\"column1\"},{\"Source\":\"column2\",\"Sink\":\"column2\"}]}]"
      },
      "guid": "-1"
    }
  ]
}

上記の API 呼び出しにより、2 つの hive_tables(Datasets) と 1 つの hive_view_query(Process) が作成されます。

データセットとプロセスの間に系列リレーションシップを作成する

API: リレーションシップの作成

タスク: table1 -> HiveQuery1 から系列を作成する (つまり、データセット -> プロセス)

POST {endpoint}/datamap/api/atlas/v2/relationship

本文の場合:

{
        "typeName": "dataset_process_inputs",
        "guid": "-1",
        "end1": {
            "typeName": "hive_table",
            "uniqueAttributes": {
                "qualifiedName": "test_lineage.table1"
            }
        },
        "end2": {
            "typeName": "Process",
            "uniqueAttributes": {
                "qualifiedName": "test_lineage.HiveQuery1"
            }
        }
}

タスク: HiveQuery1 から系列を作成する -> table2 (つまり、Process -> Dataset)

POST {endpoint}/datamap/api/atlas/v2/relationship

本文の場合:

{
        "typeName": "process_dataset_outputs",
        "guid": "-2",
        "end1": {
            "typeName": "Process",
            "uniqueAttributes": {
                "qualifiedName": "test_lineage.HiveQuery1"
            }
        },
        "end2": {
            "typeName": "hive_table",
            "uniqueAttributes": {
                "qualifiedName": "test_lineage.table2"
            }
        }
}

系列を表示する

資産と系列の関係が作成されたら、Microsoft Purview で系列グラフをチェックできます。

DataSet-Process-DataSet 系列。

例 2

2 つの列を含む Hive テーブル table3 を作成する

API: 資産の一括作成

タスク: table3 を作成し、2 hive_columns、column1、column2 を使用します

POST {endpoint}/datamap/api/atlas/v2/entity/bulk

本文の場合:

{
"entities": [
    {
      "typeName": "hive_table",
      "attributes": {
        "qualifiedName": "test_lineage.table3",
        "name": "table3"
      },
      "relationshipAttributes": {
        "columns": [
          {
            "guid": "-31",
            "typeName": "hive_column"
          },{
            "guid": "-32",
            "typeName": "hive_column"
          }
        ]
      },
      "guid": "-3"
    },
    {
      "typeName": "hive_column",
      "attributes": {
        "qualifiedName": "test_lineage.table3#column1",
        "name": "column1",
        "type": "int"
      },
      "guid": "-31",
      "relationshipAttributes": {
        "table": {
          "guid": "-3",
          "typeName": "hive_table"
        }
      }
    },
    {
      "typeName": "hive_column",
      "attributes": {
        "qualifiedName": "test_lineage.table3#column2",
        "name": "column2",
        "type": "int"
      },
      "guid": "-32",
      "relationshipAttributes": {
        "table": {
          "guid": "-3",
          "typeName": "hive_table"
        }
      }
    }
   ]
}

列マッピングを使用して、表 2 と表 3 の間に直接系列を作成する

API: リレーションシップの作成

タスク: 列マッピングを使用して table2 -> table3 (つまり、データセット -> データセット) から系列を作成する

POST {endpoint}/datamap/api/atlas/v2/relationship

本文の場合:

{
    "typeName": "direct_lineage_dataset_dataset",
    "guid": "-1",
    "end1": {
        "typeName": "hive_table",
        "uniqueAttributes": {
            "qualifiedName": "test_lineage.table2"
        }
    },
    "end2": {
        "typeName": " hive_table ",
        "uniqueAttributes": {
            "qualifiedName": "test_lineage.table3"
        }
    },
    "attributes": {
      "columnMapping": "[{\"Source\":\"column1\",\"Sink\":\"column1\"},{\"Source\":\"column2\",\"Sink\":\"column2\"}]"
    }
}

系列を表示する

次に、系列グラフ (上の例 1 & 例 2) が次のようになります。

DataSet から DataSet 系列。

table2 は、それらの間に HiveQuery を使用せずに table3 に直接リンクされていることに注意してください。

系列リレーションシップ/パスのクエリ

API: GUID で系列を取得する

タスク: REST API を使用して table2 の系列を取得する

GET {{endpoint}}/api/atlas/v2/lineage/{{guid_of_table2}}?direction=BOTH

以下では、JSON 応答ペイロードを使用できます。

{
    "baseEntityGuid": "2a12b3ff-5816-4222-833a-035bf82e06e0",
    "lineageDirection": "BOTH",
    "lineageDepth": 3,
    "lineageWidth": -1,
    "childrenCount": -1,
    "guidEntityMap": {
        "16b93b78-8683-4f88-9651-24c4a9d797b0": {
            "typeName": "hive_table",
            "attributes": {
                "temporary": false,
                "lastAccessTime": 0,
                "createTime": 0,
                "qualifiedName": "test_lineage.table3",
                "name": "table3",
                "retention": 0
            },
            "lastModifiedTS": "1",
            "guid": "16b93b78-8683-4f88-9651-24c4a9d797b0",
            "status": "ACTIVE",
            "displayText": "table3",
            "classificationNames": [],
            "meaningNames": [],
            "meanings": [],
            "isIncomplete": false,
            "labels": [],
            "isIndexed": true
        },
        "cb22ba23-47a2-4149-ade6-e3d9642fe592": {
            "typeName": "hive_table",
            "attributes": {
                "temporary": false,
                "lastAccessTime": 0,
                "createTime": 0,
                "qualifiedName": "test_lineage.table1",
                "name": "table1",
                "retention": 0
            },
            "lastModifiedTS": "1",
            "guid": "cb22ba23-47a2-4149-ade6-e3d9642fe592",
            "status": "ACTIVE",
            "displayText": "table1",
            "classificationNames": [],
            "meaningNames": [],
            "meanings": [],
            "isIncomplete": false,
            "labels": [],
            "isIndexed": true
        },
        "bbeacce6-5bde-46f7-8fe4-689cbb36ba51": {
            "typeName": "hive_view_query",
            "attributes": {
                "qualifiedName": "test_lineage.HiveQuery1",
                "name": "HiveQuery1",
                "columnMapping": "[{\"DatasetMapping\":{\"Source\":\"test_lineage.table1\",\"Sink\":\"test_lineage.table2\"},\"ColumnMapping\":[{\"Source\":\"column1\",\"Sink\":\"column1\"},{\"Source\":\"column2\",\"Sink\":\"column2\"}]}]"
            },
            "lastModifiedTS": "1",
            "guid": "bbeacce6-5bde-46f7-8fe4-689cbb36ba51",
            "status": "ACTIVE",
            "displayText": "HiveQuery1",
            "classificationNames": [],
            "meaningNames": [],
            "meanings": [],
            "isIncomplete": false,
            "labels": [],
            "isIndexed": true
        },
        "2a12b3ff-5816-4222-833a-035bf82e06e0": {
            "typeName": "hive_table",
            "attributes": {
                "temporary": false,
                "lastAccessTime": 0,
                "createTime": 0,
                "qualifiedName": "test_lineage.table2",
                "name": "table2",
                "retention": 0
            },
            "lastModifiedTS": "1",
            "guid": "2a12b3ff-5816-4222-833a-035bf82e06e0",
            "status": "ACTIVE",
            "displayText": "table2",
            "classificationNames": [],
            "meaningNames": [],
            "meanings": [],
            "isIncomplete": false,
            "labels": [],
            "isIndexed": true
        }
    },
    "includeParent": false,
    "relations": [
        {
            "fromEntityId": "2a12b3ff-5816-4222-833a-035bf82e06e0",
            "toEntityId": "16b93b78-8683-4f88-9651-24c4a9d797b0",
            "relationshipId": "23df8e3e-b066-40b2-be29-9fd90693c51b",
            "columnMapping": "[{\"Source\":\"column1\",\"Sink\":\"column1\"},{\"Source\":\"column2\",\"Sink\":\"column2\"}]"
        },
        {
            "fromEntityId": "bbeacce6-5bde-46f7-8fe4-689cbb36ba51",
            "toEntityId": "2a12b3ff-5816-4222-833a-035bf82e06e0",
            "relationshipId": "5fe8d378-39cd-4c6b-8ced-91b0152d3014"
        },
        {
            "fromEntityId": "cb22ba23-47a2-4149-ade6-e3d9642fe592",
            "toEntityId": "bbeacce6-5bde-46f7-8fe4-689cbb36ba51",
            "relationshipId": "73e084bf-98a3-45fb-a1e4-c56cc40661b8"
        }
    ],
    "parentRelations": [],
    "widthCounts": {
        "INPUT": {
            "cb22ba23-47a2-4149-ade6-e3d9642fe592": 0,
            "bbeacce6-5bde-46f7-8fe4-689cbb36ba51": 1,
            "2a12b3ff-5816-4222-833a-035bf82e06e0": 1
        },
        "OUTPUT": {
            "16b93b78-8683-4f88-9651-24c4a9d797b0": 0,
            "2a12b3ff-5816-4222-833a-035bf82e06e0": 1
        }
    }
}

その他のリソース

型定義

すべての資産/エンティティとリレーションシップは、タイプ システムで定義されます。

すべての 型定義 API を呼び出して、Microsoft Purview インスタンス内の現在の型定義を取得します。 説明されている API 呼び出しで使用する typeName がわからない場合は、型定義 API をチェックして、適切な Asset/Entity 型を見つけることができます。

この API の応答例を次に示します。

TypeDef API 応答 1。

上記の応答の entityDefs では、資産の種類 (oracle_table、oracle_view など) が定義されていることがわかります。 資産の定義 (この例では、oracle_view) を詳しく見ると、資産が DataSet 型に継承されていることが示されています。

TypeDef API 応答 2。

同様に、次に示すように、プロセス (たとえば、Oracle_function) が "Process" 型から継承されていることがわかります。

TypeDef API 応答 3。

新しいカスタム型を作成する

カスタム資産またはプロセスを作成する場合は、次の API を使用できます。

API: Typedef API を作成する

タスク: カスタム プロセスの種類を作成する

POST {endpoint}/datamap/api/atlas/v2/types/typedefs

本文の場合:

{
  "enumDefs": [],
  "structDefs": [],
  "classificationDefs": [],
  "entityDefs": [
    {
      "name": "MyCustomServiceProcess",
      "superTypes": [
        "Process"
      ],
      "typeVersion": "1.0",
      "attributeDefs": []
    }
  ],
  "relationshipDefs": []
}

タスク: カスタム DataSet 型を作成する

POST {endpoint}/datamap/api/atlas/v2/types/typedefs

本文の場合:

{
  "enumDefs": [],
  "structDefs": [],
  "classificationDefs": [],
  "entityDefs": [
    {
      "name": "MyCustomDataSet",
      "superTypes": [
        "DataSet"
      ],
      "typeVersion": "1.0",
      "attributeDefs": []
    }
  ],
  "relationshipDefs": []
}