使用 REST API 创建和获取关系

项目
11/12/2024

本教程介绍如何使用 Purview REST API 来：

在数据资产之间创建资产和世系关系。
查询世系关系/路径。

本文中引用的 API：

先决条件

使用这些 API 需要数据策展人和数据读取者角色。有关如何获取访问令牌的详细信息，请查看本教程。

概念

资产

在 Purview 中，我们有两种类型的基本资产：DataSet 和 Process。

包含数据（如 Azure SQL 表、Oracle 表等）的数据集资产应从 DataSet 继承。
处理数据的流程资产（如数据管道、查询、函数等）应从 Process 继承。

请参阅资产和类型，了解数据集和进程的类型定义。

世系 & 关系

在 Microsoft Purview 中，我们定义了三种类型的世系关系：

dataset_process_inputs：将数据集连接到进程，这意味着数据集是进程的输入
process_dataset_outputs：将进程连接到数据集，这意味着进程生成数据集
direct_lineage_dataset_dataset：将 DataSet1 连接到 DataSet2，这意味着 DataSet1 是 DataSet2 的上游，尽管我们不知道它们之间的进程

示例 1：下面是一个沿袭示例，其中包含 2 个数据集、一个进程和两个世系关系：

数据集---> dataset_process_inputs ---> 处理---> process_dataset_outputs ---> 数据集

示例 2：具有 2 个数据集和一个世系关系的另一个世系示例：

数据集---> direct_lineage_dataset_dataset ---> 数据集

在数据资产之间创建资产和世系关系

在以下部分中，我们将hive_table作为 DataSet 的示例类型，hive_query_process作为 Process 的示例类型。我们将使用这两种类型创建资产，并在它们之间创建世系。可以使用继承自 DataSet 或 Process 的任何其他类型来创建世系。

示例 1

通过 API 创建资产

如果要为其创建世系的资产尚未在 Microsoft Purview 中创建，则可以调用以下 API 来创建这些资产。

API：批量创建资产

任务：创建两个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 调用会导致创建两个hive_tables (数据集) 和一个hive_view_query (进程) 。

在数据集和进程之间创建世系关系

API：创建关系

任务：从表 1 创建世系 -> 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 中检查世系图：

示例 2

创建包含两列的 hive 表 table3

API：批量创建资产

任务：创建表 3，包含 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：创建关系

任务：使用列映射从表 2 -> 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) 变为：

请注意，table2 直接链接到 table3，它们之间没有 HiveQuery。

查询世系关系/路径

API：通过 GUID 获取世系

任务：通过 REST API 获取表 2 的世系

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 中，定义了资产类型 (，例如oracle_table、oracle_view等，) 。进一步了解此示例中资产 (的定义，oracle_view) 显示资产是继承的 DataSet 类型。

同样，可以发现进程 (例如，Oracle_function) 继承自“进程”类型，如下所示：

创建新的自定义类型

如果要创建自定义资产或进程，可以使用以下 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": []
}

通过

使用 REST API 创建和获取关系

先决条件

概念

资产

世系 & 关系

在数据资产之间创建资产和世系关系

示例 1

通过 API 创建资产

在数据集和进程之间创建世系关系

查看世系

示例 2

创建包含两列的 hive 表 table3

使用列映射在表 2 和表 3 之间创建直接世系

查看世系

查询世系关系/路径

其他资源

类型定义

创建新的自定义类型

反馈

其他资源