Erstellen und Abrufen von Beziehungen mithilfe der REST-API

Artikel
11/12/2024

In diesem Tutorial erfahren Sie, wie Sie Purview-REST-APIs für Folgendes verwenden:

Erstellen von Ressourcen und Herkunftsbeziehungen zwischen den Datenassets
Abfragen von Herkunftsbeziehungen/Pfaden.

APIs, auf die in diesem Artikel verwiesen wird:

Voraussetzungen

Die Verwendung dieser APIs erfordert die Rollen Datenkurator und Datenleseberechtigter. Weitere Informationen zum Abrufen des Zugriffstokens finden Sie in diesem Tutorial .

Konzepte

Objekt

In Purview gibt es zwei Arten von Basisressourcen: DataSet und Process.

DataSet-Ressourcen, die Daten wie Azure SQL Table, Oracle Table usw. enthalten, sollten von DataSet geerbt werden.
Prozessressourcen, die Daten verarbeiten, z. B. eine Datenpipeline, Abfrage, Funktion usw., sollten von Process geerbt werden.

Informationen zu Typdefinitionen von DataSets und Prozessen finden Sie unter Ressourcen und Typen .

Beziehungen & Herkunft

In Microsoft Purview definieren wir drei Arten von Beziehungen für die Herkunft:

dataset_process_inputs: Verbindet DataSet mit Process, d. h., das DataSet ist die Eingabe des Prozesses.
process_dataset_outputs: Verbindet Process mit DataSet, d. h., der Prozess erzeugt das DataSet.
direct_lineage_dataset_dataset: Verbindet DataSet1 mit DataSet2, was bedeutet, dass DataSet1 der Upstream von DataSet2 ist, obwohl wir nicht genau wissen würden, welcher Prozess dazwischen liegt.

Beispiel 1:Hier ist ein Beispiel für die Herkunft mit 2 DataSets, einem Prozess und zwei Herkunftsbeziehungen:

Dataset ---> dataset_process_inputs ---> Process ---> process_dataset_outputs ---> DataSet

Beispiel 2:Ein weiteres Beispiel für die Herkunft mit 2 DataSets und einer Herkunftsbeziehung:

Dataset ---> direct_lineage_dataset_dataset ---> DataSet

Erstellen von Ressourcen und Herkunftsbeziehungen zwischen den Datenassets

In den folgenden Abschnitten nehmen wir hive_table als Beispieltyp für DataSet und hive_query_process als Beispieltyp für Process. Wir erstellen Ressourcen mit diesen beiden Typen und erstellen Zwischenherkunftslinien. Sie können einen beliebigen anderen Typ verwenden, der von DataSet oder Process erbt, um Herkunftslinien zu erstellen.

Beispiel 1

Erstellen von Ressourcen über die API

Wenn die Ressourcen, für die Sie die Herkunft erstellen möchten, noch nicht in Microsoft Purview erstellt wurden, können Sie die folgende API aufrufen, um sie zu erstellen.

API: Massenerstellung von Ressourcen

Aufgabe: Erstellen Sie zwei hive_tables als Datasets – table1 und table2 mit jeweils 2 hive_columns – column1 und column2.

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

Mit dem Körper:

{
  "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"
        }
      }
    }    
  ]
}

Aufgabe: Erstellen der Prozessressource "hive_view_query"

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

Mit dem Körper:

{
  "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"
    }
  ]
}

Die obigen API-Aufrufe führen zur Erstellung von zwei hive_tables(Datasets) und einem hive_view_query(Process).

Erstellen von Herkunftsbeziehungen zwischen Datasets und dem Prozess

API: Erstellen einer Beziehung

Aufgabe: Erstellen einer Herkunft aus Tabelle1 –> HiveQuery1 (d. a. Dataset –> Prozess)

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

Mit dem Körper:

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

Aufgabe: Erstellen der Herkunft aus HiveQuery1 –> Table2 (d. a. Prozess –> Dataset)

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

Mit dem Körper:

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

Datenherkunft anzeigen

Nachdem die Ressourcen- und Herkunftsbeziehungen erstellt wurden, können Sie das Herkunftsdiagramm in Microsoft Purview überprüfen:

Beispiel 2

Erstellen einer Hive-Tabelle (Table3) mit zwei Spalten

API: Massenerstellung von Ressourcen

Aufgabe: Erstellen von Tabelle 3 mit 2 hive_columns, Spalte1 und Spalte2

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

Mit dem Körper:

{
"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"
        }
      }
    }
   ]
}

Erstellen einer direkten Herkunft zwischen Tabelle 2 und Tabelle 3 mit Spaltenzuordnung

API: Erstellen einer Beziehung

Aufgabe: Erstellen der Herkunft aus Tabelle 2 –> Tabelle3 (d. b. Dataset –> Dataset) mit Spaltenzuordnung

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

Mit dem Körper:

{
    "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\"}]"
    }
}

Datenherkunft anzeigen

Das Herkunftsdiagramm (zusammen aus Beispiel 1 & Beispiel 2 oben) lautet nun:

Beachten Sie, dass Tabelle 2 direkt mit Tabelle 3 verknüpft ist, ohne dass eine HiveQuery dazwischen besteht.

Abfragen von Herkunftsbeziehungen/Pfaden

API: Abrufen der Herkunft nach GUID

Aufgabe: Abrufen der Herkunft von Tabelle 2 über die REST-API

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

Im Folgenden können Sie JSON-Antwortnutzlasten ausführen:

{
    "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
        }
    }
}

Weitere Ressourcen

Typdefinitionen

Alle Objekte/Entitäten und Beziehungen werden im Typsystem definiert.

Rufen Sie die API für alle Typdefinitionen auf, um aktuelle Typdefinitionen in Ihrer Microsoft Purview-instance abzurufen. Wenn Sie nicht sicher sind, welcher TypeName in den beschriebenen API-Aufrufen verwendet werden soll, können Sie die Typdefinitions-API überprüfen, um den geeigneten Asset-/Entitätstyp zu finden.

Im Folgenden sehen Sie eine Beispielantwort für diese API:

Sie können sehen, dass in den entityDefs in der obigen Antwort Ressourcentypen (z. B. oracle_table, oracle_view usw.) definiert sind. Ein weiterer Blick auf die Definition des Medienobjekts (in diesem Beispiel oracle_view) zeigt, dass es sich bei dem Medienobjekt um einen geerbten DataSet-Typ handelt.

Ebenso können Sie feststellen, dass ein Prozess (z. B. Oracle_function) wie gezeigt vom Typ "Process" geerbt wird:

Erstellen neuer benutzerdefinierter Typen

Wenn Sie benutzerdefinierte Ressourcen oder Prozesse erstellen möchten, können Sie die folgenden APIs verwenden.

API: Erstellen der Typedef-API

Aufgabe: Erstellen eines benutzerdefinierten Prozesstyps

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

Mit dem Körper:

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

Aufgabe: Erstellen eines benutzerdefinierten DataSet-Typs

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

Mit dem Körper:

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

Freigeben über

Erstellen und Abrufen von Beziehungen mithilfe der REST-API

Voraussetzungen

Konzepte

Objekt

Beziehungen & Herkunft

Erstellen von Ressourcen und Herkunftsbeziehungen zwischen den Datenassets

Beispiel 1

Erstellen von Ressourcen über die API

Erstellen von Herkunftsbeziehungen zwischen Datasets und dem Prozess

Datenherkunft anzeigen

Beispiel 2

Erstellen einer Hive-Tabelle (Table3) mit zwei Spalten

Erstellen einer direkten Herkunft zwischen Tabelle 2 und Tabelle 3 mit Spaltenzuordnung

Datenherkunft anzeigen

Abfragen von Herkunftsbeziehungen/Pfaden

Weitere Ressourcen

Typdefinitionen

Erstellen neuer benutzerdefinierter Typen

Feedback

Zusätzliche Ressourcen