Compartir a través de

Creación y obtención de relaciones mediante la API REST

  • Artículo

En este tutorial, aprenderá a usar las API REST de Purview para:

  1. Cree recursos y relaciones de linaje entre los recursos de datos.
  2. Consultar las relaciones o rutas de acceso de linaje.

API a las que se hace referencia en este artículo:

Requisitos previos

El uso de estas API requiere roles de conservador de datos y lector de datos. Consulte este tutorial para obtener más información sobre cómo obtener el token de acceso.

Conceptos

Recurso

En Purview, tenemos dos tipos de recursos base: DataSet y Process.

  • Los recursos de DataSet que contienen datos como Azure SQL Table, Oracle Table, etc., deben heredarse de DataSet.
  • Los recursos de proceso que procesan datos, como una canalización de datos, una consulta, una función, etc., se deben heredar de Process.

Consulte recursos y tipos para comprender las definiciones de tipos de datasets y procesos.

Relaciones & linaje

En Microsoft Purview, definimos tres tipos de relaciones para el linaje:

  • dataset_process_inputs: conecta DataSet con Process, lo que significa que dataset es la entrada del proceso.
  • process_dataset_outputs: conecta Process a DataSet, lo que significa que Process genera el DataSet.
  • direct_lineage_dataset_dataset: conecta DataSet1 a DataSet2, lo que significa que DataSet1 es el elemento ascendente de DataSet2, aunque no sabríamos exactamente qué proceso está entre ellos.

Ejemplo 1:este es un ejemplo de linaje con 2 conjuntos de datos, un proceso y dos relaciones de linaje:

Conjunto de datos ---> proceso de dataset_process_inputs ---> ---> process_dataset_outputs ---> conjunto de datos

Captura de pantalla en la que se muestra dataset to process to DataSet lineage (Conjunto de datos para procesar al linaje del conjunto de datos).

Ejemplo 2:Otro ejemplo de linaje con 2 conjuntos de datos y una relación de linaje:

Conjunto de datos ---> direct_lineage_dataset_dataset ---> Conjunto de datos

Captura de pantalla que muestra el linaje de DataSet a DataSet.

Creación de recursos y relaciones de linaje entre los recursos de datos

En las secciones siguientes, vamos a tomar hive_table como un tipo de ejemplo para DataSet y hive_query_process como un tipo de ejemplo para Process. Crearemos recursos con esos dos tipos y crearemos linajes entre ellos. Puede usar cualquier otro tipo, que herede de DataSet o Process para crear linajes.

Ejemplo 1

Creación de recursos a través de la API

Si los recursos para los que desea crear linaje aún no se crean en Microsoft Purview, puede llamar a la siguiente API para crearlos.

API: Creación masiva de recursos

Tarea: cree dos hive_tables como conjuntos de datos: table1 y table2, cada uno con 2 hive_columns: column1 y column2.

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

Con el cuerpo:

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

Tarea: Cree el recurso de proceso "hive_view_query"

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

Con el cuerpo:

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

Las llamadas API anteriores dan como resultado la creación de dos hive_tables (conjuntos de datos) y una hive_view_query(Process).

Creación de relaciones de linaje entre conjuntos de datos y el proceso

API: Crear relación

Tarea: Crear linaje a partir de table1 -> HiveQuery1 (es decir, Conjunto de datos -> Proceso)

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

Con el cuerpo:

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

Tarea: Crear linaje a partir de HiveQuery1-> table2 (es decir, Proceso -> Conjunto de datos)

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

Con el cuerpo:

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

Ver linaje

Una vez creados los recursos y las relaciones de linaje, puede comprobar el gráfico de linaje en Microsoft Purview:

Linaje DataSet-Process-DataSet.

Ejemplo 2

Creación de una tabla de Hive, table3, con dos columnas

API: Creación masiva de recursos

Tarea: Cree table3, con 2 hive_columns, column1 y column2.

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

Con el cuerpo:

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

Creación de linaje directo entre la tabla 2 y la tabla 3, con asignación de columnas

API: Crear relación

Tarea: Crear linaje a partir de table2 -> table3 (es decir, Conjunto de datos -> Conjunto de datos) con asignación de columnas

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

Con el cuerpo:

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

Ver linaje

Ahora el gráfico de linaje (junto con el ejemplo 1 & ejemplo 2 anterior) se convierte en:

Linaje de DataSet a DataSet.

Tenga en cuenta que table2 está directamente vinculado a table3, sin una hiveQuery entre ellos.

Relaciones o rutas de acceso de linaje de consulta

API: Obtener linaje por GUID

Tarea: Obtención del linaje de table2 a través de la API REST

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

A continuación, puede obtener una carga de respuesta 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
        }
    }
}

Otros recursos

Definiciones de tipos

Todos los recursos, entidades y relaciones se definen en el sistema de tipos.

Llame a la API de todas las definiciones de tipos para obtener las definiciones de tipo actuales en la instancia de Microsoft Purview. Si no está seguro de qué typeName usar en las llamadas API descritas, puede comprobar la API de definiciones de tipo para encontrar el tipo de recurso o entidad adecuado.

A continuación se muestra una respuesta de ejemplo de esta API:

Respuesta de API typeDef 1.

Puede ver que en entityDefs de la respuesta anterior, se definen tipos de recursos (como oracle_table, oracle_view, etc.). Una vista más detallada de la definición del recurso (en este ejemplo, oracle_view) muestra que el recurso se hereda del tipo DataSet.

Respuesta de API typeDef 2.

De forma similar, puede encontrar que un proceso (por ejemplo, Oracle_function) se hereda del tipo "Process" como se muestra:

Respuesta de API typeDef 3.

Creación de nuevos tipos personalizados

Si desea crear recursos o procesos personalizados, puede usar las siguientes API.

API: Creación de typedef API

Tarea: Crear un tipo de proceso personalizado

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

Con el cuerpo:

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

Tarea: Crear un tipo de conjunto de datos personalizado

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

Con el cuerpo:

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