使用 REST API 创建和获取关系
本教程介绍如何使用 Purview REST API:
- 创建资产和数据资产之间的世系关系。
- 查询世系关系/路径。
本文中引用的 API:
先决条件
使用这些 API 需要数据策展人和数据读取者角色。 请查看本教程,详细了解如何获取访问令牌。
概念
资产
在 Purview 中,我们有两种类型的基本资产:数据集和过程。
- 包含 Azure SQL Table、Table 等数据的数据集资产应继承自 DataSet。
- 处理数据管道、查询、函数等数据的过程资产应继承自 Process。
请参阅资产和类型,了解数据集和过程的类型定义。
关系和世系
在 Microsoft Purview 中,我们定义了三种类型的世系关系:
- dataset_process_inputs:将 DataSet 连接到 Process,这意味着 DataSet 是 Process 的输入
- process_dataset_outputs:将 Process 连接到 DataSet,这意味着 Process 生成 DataSet
- direct_lineage_dataset_dataset:将 DataSet1 连接到 DataSet2,这意味着 DataSet1 是 DataSet2 的上游,但我们不知道它们之间的 Process 到底是什么
示例 1:下面是具有 2 个 DataSet、一个 Process 和两个世系关系的世系示例:
Dataset ---> dataset_process_inputs ---> Process ---> process_dataset_outputs ---> DataSet
示例 2:另一个具有 2 个 DataSet 和一个世系关系的世系示例:
Dataset ---> direct_lineage_dataset_dataset ---> DataSet
创建资产和数据资产之间的世系关系
在以下部分中,我们将 hive_table 作为 DataSet 的示例类型,将 hive_query_process 作为 Process 的示例类型。 我们将使用这两种类型创建资产,并在它们之间创建世系。 可以使用任何其他类型(继承自 DataSet 或 Process)来创建世系。
示例 1
通过 API 创建资产
如果 Microsoft Purview 中尚未创建你想要为其创建世系的资产,可以调用以下 API 来创建这些资产。
API:批量创建资产
任务:创建两个 hive_table 作为数据集(table1 和 table2),每个数据集具有 2 个 hive_column(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 调用会导致创建两个 hive_table (DataSet) 和一个 hive_view_query (Process)。
在 DataSet 和 Process 之间创建世系关系
API:创建关系
任务:根据 table1 创建世系 -> HiveQuery1(即 Dataset -> Process)
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 中查看世系图:
示例 2
创建一个 hive 表 (table3),其中包含两列
API:批量创建资产
任务:创建 table3,其中包含 2 个 hive_column(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"
}
}
}
]
}
使用列映射在 table2 和 table3 之间创建直接世系
API:创建关系
任务:使用列映射根据 table2 创建世系 -> table3(即 Dataset -> Dataset)
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 组合而成)变为:
请注意,table2 直接链接到 table3,在它们之间没有 HiveQuery。
查询世系关系/路径
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 以查找相应的资产/实体类型。
下面是此 API 的示例响应:
可以看到,在上述响应的 entityDefs 中,定义了资产类型。 进一步了解资产的定义,发现资产是继承的数据集类型。
同样,可以发现过程继承自“过程”类型,如下所示:
创建新的自定义类型
如果要创建自定义资产或过程,可以使用以下 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": []
}
任务:创建自定义数据集类型
POST {endpoint}/datamap/api/atlas/v2/types/typedefs
使用正文:
{
"enumDefs": [],
"structDefs": [],
"classificationDefs": [],
"entityDefs": [
{
"name": "MyCustomDataSet",
"superTypes": [
"DataSet"
],
"typeVersion": "1.0",
"attributeDefs": []
}
],
"relationshipDefs": []
}