Microsoft Purview - 使用 REST API 生成自定义世系
本文提供在 Microsoft Purview 数据目录中使用 REST API 创建数据世系条目的步骤。 在 Microsoft Purview 中自动生成的世系不完整或缺失的情况下，可以在 Microsoft Purview 门户手动或使用 REST API 自定义世系。 本文重点介绍如何使用 REST API 来克服手动世系已知限制，并提供更多选项。
背景
Microsoft Purview 的一个重要平台功能是能够显示数据集之间的世系。 数据工厂、Data Share 和 Power BI 等系统在数据移动时可捕获数据世系。 在某些情况下，出于实际可视化和/或企业报告目的，Microsoft Purview 自动生成的世系不完整或缺失。 在这些方案中，Apache Atlas 挂钩和 REST API 支持自定义世系报告。
使用 REST API 生成自定义世系，可以克服以下文章中所述的一些手动世系限制：
本文的其余部分介绍了如何使用 Microsoft Purview REST API 在 Microsoft Purview 上生成和报告自定义世系。
先决条件
- 有关如何使用 Purview Python SDK 包的分步指南，请参阅 Purview Python SDK 教程和使用 Python 探索 Purview 的 REST API
- 有关如何使用 Purview REST API 的分步指南，请参阅 Purview Python SDK 教程
方案
生成自定义世系时，有两个用例是必需的：
A. 创建新实体并将其与世系链接
例如，需要报告实体 A 和 B 之间的世系，但 A 和 B 目前不存在。
若要创建实体 A 和 B，请调用 Microsoft Purview REST API：实体 - 批量创建或更新 - REST API
POST https://{accountname}.purview.azure.cn/datamap/api/atlas/v2/entity/bulk?api-version=2023-09-01
sample_entity_json = '{"entity": {"status": "ACTIVE","version": 0,"name": ENTITY_A"}.......{"entity": ........}}'
#Send POST JSON containing entities to be created
CreateOrUpdateEntitesUrl = 'https://<purview_account_name>.purview.azure.cn/datamap/api/atlas/v2/entity/bulk'
EntitiesResponse = requests.post(CreateOrUpdateEntitesUrl, json = json.loads(sample_entity_json) ,headers=headers)
entitiesRes = json.loads(EntitiesResponse.text)
API 响应“201 已创建”表示已成功创建实体，并且其各自的 GUID 包含在输出 JSON 中。
创建实体 A 和 B 后，请移到步骤 B，以使用相同的 REST API 链接世系链中的实体。
B. 将现有实体或世系链接到另一个现有实体或世系
- 如果要链接的实体数不是时间或资源密集型（例如，少于 20-30 个实体），则可以在 Microsoft Purview 门户中手动连接世系。 遵循手动世系用户指南的步骤操作，手动创建世系连接。
- 如果有大量世系需要连接，此过程需要自动化，或者如果使用 Microsoft Purview 门户手动世系不可行，请继续执行链接和生成自定义世系的 API 过程。
自定义世系 JSON 有效负载：
使用有效负载执行 POST /entity/bulk 实体 - 批量创建或更新 - REST API，如下所示：
POST https://{accountname}.purview.azure.cn/datamap/api/atlas/v2/entity/bulk?api-version=2023-09-01
sample_entity_json = '{
"entities": [
{
"status": "ACTIVE",
"version": 1,
"typeName": "Process",
"attributes": {
"inputs": [
{
"guid": "24558fd8-9cdc-47de-9310-56a58108bab0",
“guid”: “27163581-9aca-212a-782a-213612639abc”
}
],
"outputs": [
{
"guid": "e33c694a-2c4f-4cae-8c27-06f6f6f60000"
}
],
"qualifiedName": "cassandra://query",
"name": "query"
}
}
]
}'
#In this code snippet, we send the JSON as POST request containing the two GUIDs as input and "output" GUID as output. This creates lineage with 2 directional inputs and 1 directional output.
#Note: using the same API and SDK code you can create lineage with any number of inputs, any number of processes in between, any number of typedefs and any number of outputs.
#The API/SDK method is the most flexible and versatile menthod of creating lineage.
CreateLineageEntitesUrl = 'https://<purview_account_name>.purview.azure.cn/datamap/api/atlas/v2/entity/bulk'
EntitiesResponse = requests.post(CreateLineageEntitesUrl, json = json.loads(sample_entity_json),headers=headers)
entitiesRes = json.loads(EntitiesResponse.text)
此 JSON 有效负载创建自定义世系。 它适用于已在“输入”JSON 中提供其 GUID 的现有资产。 例如“guid”：“24558fd8-9cdc-47de-9310-56a58108bab0”和“27163581-9aca-212a-782a-213612639abc”是指世系的方向输入和“guid”：“e33c694a-2c4f-4cae-8c27-06f6f6f6f60000”是指世系的方向输出，这是 Purview 自动扫描的现有资产。 我们刚刚创建了两个资产之间的世系。
注意
如果资产尚不存在，则需要在此步骤之前运行批量实体创建 API，才能在创建世系关系之前创建这些实体。 步骤 A 中介绍了使用 POST /entity/bulk API 和 Python 代码片段的批量实体创建过程。
方案结果
API 响应“201 已创建”表示成功创建世系图形链接，并且创建的 GUID 包含在输出 JSON 中。 世系显示在 Microsoft Purview 门户中：
方案 A：通过 API 创建的资产的自定义生成世系：
方案 B：通过 API 链接的预先存在的资产中自定义生成的世系。
注意
如果从预先存在的实体创建世系，则观察预先存在的世系图保持不变，并创建和显示新的链接。
