使用 REST API 建立和取得關聯性

發行項
11/12/2024

在本教學課程中，您將瞭解如何使用 Purview REST API 來：

建立數據資產之間的資產和譜系關聯性。
查詢譜系關聯性/路徑。

本文中參考的 API：

必要條件

使用這些 API 需要數據編者和數據讀取者角色。如需如何取得存取令牌的詳細資訊，請參閱本教學課程。

概念

資產

在 Purview 中，我們有兩種類型的基底資產：DataSet 和 Process。

包含數據的數據集資產，例如 Azure SQL 數據表、Oracle 數據表等，應繼承自 DataSet。
處理數據的處理資產，例如數據管線、查詢、函數等，都應該繼承自 Process。

請參閱資產和類型，以了解數據集和進程的類型定義。

歷程 & 關聯性

在 Microsoft Purview 中，我們會定義歷程的三種關聯性類型：

dataset_process_inputs：將DataSet連接到 Process，這表示DataSet是進程的輸入
process_dataset_outputs：將 Process 連接到 DataSet，這表示進程會產生 DataSet
direct_lineage_dataset_dataset：將 DataSet1 連線到 DataSet2，這表示 DataSet1 是 DataSet2 的上游，雖然我們無法確切知道兩者之間有哪一個進程

範例 1：以下是具有 2 個數據集、一個進程和兩個譜系關聯性的譜系範例：

數據集---dataset_process_inputs --->>處理 --- process_dataset_outputs --->> DataSet

範例 2：另一個具有 2 個數據集和一個譜系關聯性的譜系範例：

dataset --- direct_lineage_dataset_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：建立關聯性

工作：從 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"
            }
        }
}

檢視譜系

建立資產和譜系關聯性之後，您可以在 Purview 中檢查Microsoft歷程圖：

範例 2

建立具有兩個數據行的hive數據表 table3

API：大量建立資產

工作：建立具有 2 hive_columns、column1 和 column2 的數據表3

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 一起 (歷程圖表) 會變成：

請注意，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 的範例回應：

您可以在上述回應的 entityDef 中看到，已定義資產類型 (例如oracle_table、oracle_view等 ) 。在此範例中進一步查看資產 (的定義，oracle_view) 会显示资产是继承的 DataSet 類型。

同樣地，您可以發現進程 (例如，Oracle_function) 继承自 “Process” 類型，如下所示：

建立新的自定義類型

如果您想要建立自定義資產或程式，您可以使用下列 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 之間建立直接譜系

檢視譜系

查詢譜系關聯性/路徑

其他資源

類型定義

建立新的自定義類型

意見反應

其他資源