Criar e obter relações com a API REST
Neste tutorial, vai aprender a utilizar as APIs REST do Purview para:
- Crie recursos e relações de linhagem entre os recursos de dados.
- Consultar relações/caminhos de linhagem.
APIs referenciadas neste artigo:
Pré-requisitos
A utilização destas APIs requer funções de Curador de Dados e Leitor de Dados. Veja este tutorial para obter detalhes sobre como obter o token de acesso.
Conceitos
Ativo
No Purview, temos dois tipos de recursos base: Conjunto de Dados e Processo.
- Os Recursos do Conjunto de Dados que contêm dados como SQL do Azure Tabela, Tabela Oracle, etc. devem ser herdados do Conjunto de Dados.
- Os Recursos de Processo que processam dados, como um pipeline de dados, consulta, função, etc. devem ser herdados do Processo.
Veja recursos e tipos para compreender as definições de tipo de Conjuntos de Dados e Processos.
Relações & Linhagem
No Microsoft Purview, definimos três tipos de relações para linhagem:
- dataset_process_inputs: liga o Conjunto de Dados ao Processo, o que significa que o Conjunto de Dados é a entrada do Processo
- process_dataset_outputs: liga o Processo ao Conjunto de Dados, o que significa que o Processo produz o Conjunto de Dados
- direct_lineage_dataset_dataset: liga o DataSet1 ao DataSet2, o que significa que o DataSet1 é o upstream do DataSet2, embora não saibamos exatamente qual é o Processo entre eles
Exemplo 1:eis um exemplo de linhagem com 2 Conjuntos de Dados, um Processo e duas relações de linhagem:
Conjunto de dados ---> dataset_process_inputs ---> Processo ---> process_dataset_outputs ---> DataSet
Exemplo 2:Outro exemplo de linhagem com 2 Conjuntos de Dados e uma relação de linhagem:
Conjunto de dados ---> direct_lineage_dataset_dataset ---> DataSet
Criar recursos e relações de linhagem entre os recursos de dados
Nas secções seguintes, vamos assumir hive_table como um tipo de exemplo para DataSet e hive_query_process como um tipo de exemplo para Processo. Vamos criar recursos com esses dois tipos e criar linhagem entre os mesmos. Pode utilizar qualquer outro tipo, que herda do Conjunto de Dados ou processo para criar linhagem.
Exemplo 1
Criar recursos através da API
Se os recursos para os quais pretende criar linhagem ainda não forem criados no Microsoft Purview, pode chamar a seguinte API para os criar.
Tarefa: crie dois hive_tables como conjuntos de dados - tabela1 e tabela2, cada um com 2 hive_columns - coluna1 e coluna2.
POST {endpoint}/datamap/api/atlas/v2/entity/bulk
Com o 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"
}
}
}
]
}
Tarefa: Criar o recurso de processo "hive_view_query"
POST {endpoint}/datamap/api/atlas/v2/entity/bulk
Com o 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"
}
]
}
As chamadas à API acima resultam na criação de dois hive_tables (Conjuntos de dados) e um hive_view_query(Processo).
Criar relações de linhagem entre Conjuntos de dados e o Processo
API: Criar Relação
Tarefa: Criar linhagem a partir da tabela1 –> HiveQuery1 (ou seja, Conjunto de dados –> Processo)
POST {endpoint}/datamap/api/atlas/v2/relationship
Com o corpo:
{
"typeName": "dataset_process_inputs",
"guid": "-1",
"end1": {
"typeName": "hive_table",
"uniqueAttributes": {
"qualifiedName": "test_lineage.table1"
}
},
"end2": {
"typeName": "Process",
"uniqueAttributes": {
"qualifiedName": "test_lineage.HiveQuery1"
}
}
}
Tarefa: Criar linhagem a partir do HiveQuery1 –> tabela2 (ou seja, Processo –> Conjunto de Dados)
POST {endpoint}/datamap/api/atlas/v2/relationship
Com o corpo:
{
"typeName": "process_dataset_outputs",
"guid": "-2",
"end1": {
"typeName": "Process",
"uniqueAttributes": {
"qualifiedName": "test_lineage.HiveQuery1"
}
},
"end2": {
"typeName": "hive_table",
"uniqueAttributes": {
"qualifiedName": "test_lineage.table2"
}
}
}
Ver linhagem
Assim que os recursos e as relações de linhagem forem criados, pode marcar o gráfico de linhagem no Microsoft Purview:
Exemplo 2
Criar uma tabela do Ramo de Registo, tabela3, com duas colunas
Tarefa: Criar tabela3, com 2 hive_columns, coluna1 e coluna2
POST {endpoint}/datamap/api/atlas/v2/entity/bulk
Com o 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"
}
}
}
]
}
Criar linhagem direta entre a tabela 2 e a tabela 3, com mapeamento de colunas
API: Criar Relação
Tarefa: Criar linhagem a partir da tabela2 –> tabela3 (ou seja, Conjunto de dados -> Conjunto de dados) com mapeamento de colunas
POST {endpoint}/datamap/api/atlas/v2/relationship
Com o 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\"}]"
}
}
Ver linhagem
Agora, o gráfico de linhagem (em conjunto a partir do Exemplo 1 & Exemplo 2 acima) torna-se:
Repare que a tabela2 está diretamente ligada à tabela3, sem um HiveQuery entre elas.
Consultar relações/caminhos de linhagem
Tarefa: Obter linhagem da tabela2 através da API REST
GET {{endpoint}}/api/atlas/v2/lineage/{{guid_of_table2}}?direction=BOTH
Abaixo, pode responder ao payload 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
}
}
}
Outros recursos
Definições de Tipo
Todos os Recursos/Entidades e Relações são definidos no sistema de tipo.
Chame a lista de todas as definições de tipo API para obter definições de tipo atuais na sua instância do Microsoft Purview. Se não tiver a certeza do tipoName a utilizar nas chamadas à API descritas, pode marcar a API de definições de tipo para encontrar o tipo de Elemento/Entidade adequado.
Segue-se uma resposta de exemplo desta API:
Pode ver que nos entityDefs na resposta acima, os tipos de recursos (como oracle_table, oracle_view etc.) estão definidos. Uma análise mais aprofundada da definição do recurso (neste exemplo, oracle_view) mostra que o recurso é do tipo Conjunto de Dados herdado.
Da mesma forma, pode descobrir que um processo (por exemplo, Oracle_function) é herdado do tipo "Processo", conforme mostrado:
Criar Novos Tipos Personalizados
Se quiser criar processos ou recursos personalizados, pode utilizar as seguintes APIs.
API: Criar a API Typedef
Tarefa: Criar um Tipo de Processo Personalizado
POST {endpoint}/datamap/api/atlas/v2/types/typedefs
Com o corpo:
{
"enumDefs": [],
"structDefs": [],
"classificationDefs": [],
"entityDefs": [
{
"name": "MyCustomServiceProcess",
"superTypes": [
"Process"
],
"typeVersion": "1.0",
"attributeDefs": []
}
],
"relationshipDefs": []
}
Tarefa: Criar um Tipo de Conjunto de Dados Personalizado
POST {endpoint}/datamap/api/atlas/v2/types/typedefs
Com o corpo:
{
"enumDefs": [],
"structDefs": [],
"classificationDefs": [],
"entityDefs": [
{
"name": "MyCustomDataSet",
"superTypes": [
"DataSet"
],
"typeVersion": "1.0",
"attributeDefs": []
}
],
"relationshipDefs": []
}