Condividi tramite

Creare e ottenere relazioni usando l'API REST

  • Articolo

Questa esercitazione descrive come usare le API REST Purview per:

  1. Creare asset e relazioni di derivazione tra gli asset di dati.
  2. Eseguire query su relazioni/percorsi di derivazione.

API a cui si fa riferimento in questo articolo:

Prerequisiti

L'uso di queste API richiede ruoli Curatore dati e Lettore dati. Per informazioni dettagliate su come ottenere il token di accesso, vedere questa esercitazione .

Concetti

Risorsa

In Purview sono disponibili due tipi di asset di base: DataSet e Process.

  • Gli asset di set di dati che contengono dati come Azure SQL Tabella, Tabella Oracle e così via devono essere ereditati da DataSet.
  • Gli asset di elaborazione che elaborano i dati, ad esempio una pipeline di dati, una query, una funzione e così via, devono essere ereditati da Process.

Per informazioni sulle definizioni dei tipi di dataset e processi, vedere asset e tipi .

Relazioni & derivazione

In Microsoft Purview vengono definiti tre tipi di relazioni per la derivazione:

  • dataset_process_inputs: connette DataSet a Process, ovvero il DataSet è l'input del processo
  • process_dataset_outputs: connette Process a DataSet, ovvero il processo produce il dataset
  • direct_lineage_dataset_dataset: connette DataSet1 a DataSet2, ovvero DataSet1 è l'upstream di DataSet2, anche se non si sa esattamente quale processo si trova tra di essi

Esempio 1:Ecco un esempio di derivazione con 2 dataset, un processo e due relazioni di derivazione:

Set di> dati --- dataset_process_inputs ---> processo ---> process_dataset_outputs ---> dataset

Screenshot che mostra la derivazione da DataSet a Process to DataSet.

Esempio 2:Altro esempio di derivazione con 2 dataset e una relazione di derivazione:

Set di dati ---> direct_lineage_dataset_dataset ---> DataSet

Screenshot che mostra la derivazione da DataSet a DataSet.

Creare asset e relazioni di derivazione tra gli asset di dati

Nelle sezioni seguenti si prende hive_table come tipo di esempio per DataSet e hive_query_process come tipo di esempio per Process. Verranno creati asset con questi due tipi e verranno create linee di derivazione tra di essi. È possibile usare qualsiasi altro tipo, che eredita da DataSet o Process per creare derivazioni.

Esempio 1

Creare asset tramite API

Se gli asset per cui si vuole creare la derivazione non sono ancora stati creati in Microsoft Purview, è possibile chiamare l'API seguente per crearli.

API: Creazione bulk di asset

Attività: creare due hive_tables come set di dati: table1 e table2, ognuno con 2 hive_columns: column1 e column2.

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

Con il corpo:

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

Attività: Creare l'asset di processo 'hive_view_query'

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

Con il corpo:

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

Le chiamate API precedenti comportano la creazione di due hive_tables (set di dati) e una hive_view_query(processo).

Creare relazioni di derivazione tra set di dati e processo

API: Creare una relazione

Attività: Creare derivazione da table1 -> HiveQuery1 (ovvero Set di dati -> Processo)

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

Con il corpo:

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

Attività: Creare derivazione da HiveQuery1 -> table2 (ovvero Processo -> Set di dati)

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

Con il corpo:

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

Visualizza derivazione

Dopo aver creato gli asset e le relazioni di derivazione, è possibile controllare il grafico di derivazione in Microsoft Purview:

Derivazione DataSet-Process-DataSet.

Esempio 2

Creare una tabella hive, table3, con due colonne

API: Creazione bulk di asset

Attività: Creare la tabella 3 con 2 hive_columns, column1 e column2

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

Con il corpo:

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

Creare derivazione diretta tra la tabella 2 e la tabella 3, con mapping delle colonne

API: Creare una relazione

Attività: Creare derivazione da table2 -> table3 (ovvero Set di dati -> Set di dati) con mapping di colonne

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

Con il corpo:

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

Visualizza derivazione

Ora il grafo di derivazione (insieme all'esempio 1 &'esempio 2 precedente) diventa:

Derivazione da DataSet a DataSet.

Si noti che table2 è direttamente collegato a table3, senza un HiveQuery tra di essi.

Relazioni/percorsi di derivazione delle query

API: Ottenere la derivazione per GUID

Attività: Ottenere la derivazione di table2 tramite l'API REST

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

Di seguito è possibile usare il payload della risposta 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
        }
    }
}

Ulteriori risorse

Definizioni dei tipi

Tutti gli asset/entità e le relazioni sono definiti nel sistema di tipi.

Chiamare elencare tutte le api di definizioni di tipo per ottenere le definizioni di tipo correnti nell'istanza di Microsoft Purview. Se non si è certi di quale typeName usare nelle chiamate API descritte, è possibile controllare l'API delle definizioni dei tipi per trovare il tipo di asset/entità appropriato.

Di seguito è riportata una risposta di esempio di questa API:

Risposta API TypeDef 1.

È possibile notare che negli entityDef nella risposta precedente vengono definiti i tipi di asset , ad esempio oracle_table, oracle_view e così via. Un'ulteriore analisi della definizione dell'asset (in questo esempio, oracle_view) mostra che l'asset è di tipo DataSet ereditato.

Risposta API TypeDef 2.

Analogamente, è possibile notare che un processo (ad esempio, Oracle_function) viene ereditato dal tipo "Processo", come illustrato di seguito:

Risposta API TypeDef 3.

Creare nuovi tipi personalizzati

Se si desidera creare asset o processi personalizzati, è possibile usare le API seguenti.

API: Creare l'API Typedef

Attività: Creare un tipo di processo personalizzato

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

Con il corpo:

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

Attività: Creare un tipo di dataset personalizzato

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

Con il corpo:

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