Compartilhar via

Escrever definições e como criar tipos personalizados

  • Artigo

Este tutorial explicará quais são as definições de tipo, como criar tipos personalizados e como inicializar recursos de tipos personalizados no Microsoft Purview.

Neste tutorial, irá aprender:

  • Como o Microsoft Purview utiliza o sistema de tipos do Apache Atlas
  • Como criar um novo tipo personalizado
  • Como criar relações entre tipos personalizados
  • Como inicializar novas entidades de tipos personalizados

Pré-requisitos

Para este tutorial, irá precisar de:

Observação

Antes de passar para a parte prática do tutorial, as primeiras quatro secções explicarão o que é um Tipo de Sistema e como é utilizado no Microsoft Purview. Todas as chamadas à API REST descritas irão utilizar o token de portador e o ponto final descritos nos pré-requisitos.

Para avançar diretamente para os passos, utilize estas ligações:

O que são recursos e tipo no Microsoft Purview?

Um recurso é um elemento de metadados que descreve um recurso digital ou físico. Os recursos digitais ou físicos que se espera que sejam catalogados como recursos incluem:

  • Origens de dados, como bases de dados, ficheiros e feeds de dados.
  • Modelos e processos analíticos.
  • Políticas e termos empresariais.
  • Infraestrutura como o servidor.

O Microsoft Purview fornece aos utilizadores um sistema de tipo flexível para expandir a definição do recurso para incluir novos tipos de recursos à medida que se tornam relevantes. O Microsoft Purview baseia-se no Sistema de Tipos do Apache Atlas. Todos os objetos de metadados (recursos) geridos pelo Microsoft Purview são modelados através de definições de tipo. Compreender o Sistema de Tipos é fundamental para criar novos tipos personalizados no Microsoft Purview.

Essencialmente, um Tipo pode ser visto como uma Classe de Programação Orientada para Objetos (OOP):

  • Define as propriedades que representam esse tipo.
  • Cada tipo é identificado exclusivamente pelo respetivo nome.
  • Um tipo pode herdar de um supertType. Este é um conceito equivalente como herança da OOP. Um tipo que expande um superType herdará os atributos do superType.

Pode ver todas as definições de tipo na sua conta do Microsoft Purview ao enviar um GET pedido para o ponto final Todas as Definições de Tipo :

GET https://{{ENDPOINT}}/catalog/api/atlas/v2/types/typedefs

O Apache Atlas tem poucos tipos de sistema predefinidos que são normalmente utilizados como supertipos.

Por exemplo:

  • Referenciado: este tipo representa todas as entidades que podem ser pesquisadas através de um atributo exclusivo chamado qualifiedName.

  • Recurso: este tipo expande-se a partir de Referencial e tem outros atributos, como: nome, descrição e proprietário.

  • Conjunto de Dados: este tipo expande Referenceable (Referencial) e Asset (Recurso). Conceptualmente, pode ser utilizado para representar um tipo que armazena dados. Espera-se que os tipos que expandem o Conjunto de Dados tenham um Esquema. Por exemplo, uma tabela SQL.

  • Linhagem: as informações de linhagem ajudam a compreender a origem dos dados e as transformações que podem ter passado antes de chegarem a um ficheiro ou tabela. A linhagem é calculada através do DataSet e do Processo: os Conjuntos de Dados (entrada do processo) afetam outros Conjuntos de Dados (saída do processo) através do Processo.

Diagrama a mostrar as relações entre os tipos de sistema.

Exemplo de uma definição de Tipo

Para compreender melhor o sistema Type, vamos ver um exemplo e ver como uma Tabela de SQL do Azure é definida.

Pode obter a definição de tipo completa ao enviar um GET pedido para o ponto final de Definição de Tipo:

GET https://{{ENDPOINT}}/catalog/api/atlas/v2/types/typedef/name/{name}

Dica

A propriedade {name} indica em que definição está interessado. Neste caso, deve utilizar azure_sql_table.

Abaixo, pode ver um resultado JSON simplificado:

{
  "category": "ENTITY",
  "guid": "7d92a449-f7e8-812f-5fc8-ca6127ba90bd",
  "name": "azure_sql_table",
  "description": "azure_sql_table",
  "typeVersion": "1.0",
  "serviceType": "Azure SQL Database",
  "options": {
    "schemaElementsAttribute": "columns",
  },
  "attributeDefs": [
    { "name": "principalId", ...},
    { "name": "objectType", ...},
    { "name": "createTime", ...},
    { "name": "modifiedTime", ... }
  ],
  "superTypes": [
    "DataSet",
    "Purview_Table",
    "Table"
  ],
  "subTypes": [],
  "relationshipAttributeDefs": [
    {
      "name": "dbSchema",
      "typeName": "azure_sql_schema",
      "isOptional": false,
      "cardinality": "SINGLE",
      "relationshipTypeName": "azure_sql_schema_tables",
    },
    {
      "name": "columns",
      "typeName": "array<azure_sql_column>",
      "isOptional": true,
      "cardinality": "SET",
      "relationshipTypeName": "azure_sql_table_columns",
    },
  ]
}

Com base na definição do tipo JSON, vamos analisar algumas propriedades:

  • O campo Categoria descreve em que categoria é o seu tipo. Pode encontrar a lista de categorias suportadas pelo Apache Atlas aqui.

  • O campo ServiceType é útil ao navegar em recursos por tipo de origem no Microsoft Purview. O tipo de serviço será um ponto de entrada para localizar todos os recursos que pertencem ao mesmo tipo de serviço , conforme definido na respetiva definição de tipo. Na captura de ecrã abaixo da IU do Purview, o utilizador limita o resultado a ser as entidades especificadas com SQL do Azure Base de Dados no serviceType:

    Captura de ecrã do portal a mostrar o caminho de Catálogo de Dados a Procurar para Por tipo de origem e o recurso realçado.

    Observação

    SQL do Azure Base de Dados é definida com o mesmo serviceTypeque SQL do Azure Tabela.

  • SuperTypes descreve os tipos "principais" dos quais pretende "herdar".

  • schemaElementsAttributes de opções influencia o que aparece no separador Esquema do seu recurso no Microsoft Purview.

    Abaixo, pode ver um exemplo do aspeto do separador Esquema para um elemento do tipo SQL do Azure Tabela:

    Captura de ecrã a mostrar o separador esquema de um elemento de Tabela SQL do Azure.

  • relationshipAttributeDefs são calculados através das definições do tipo de relação. No nosso JSON, podemos ver que schemaElementsAttributes aponta para o atributo de relação denominado colunas , que é um dos elementos da matriz relationshipAttributeDefs , conforme mostrado abaixo:

    ...
"relationshipAttributeDefs": [
     ...
     {
       "name": "columns",
       "typeName": "array<azure_sql_column>",
       "isOptional": true,
       "cardinality": "SET",
       "relationshipTypeName": "azure_sql_table_columns",
     },
   ]

    Cada relação tem a sua própria definição. O nome da definição encontra-se no atributo relationshipTypeName . Neste caso, é azure_sql_table_columns.

    • A cardinalidade deste atributo de relação está definida como *SET, o que sugere que contém uma lista de recursos relacionados.
    • O recurso relacionado é do tipo azure_sql_column, conforme visível no atributo typeName .

    Por outras palavras, o atributo de relação de colunas relaciona o SQL do Azure Tabela com uma lista de colunas de SQL do Azure que aparecem no separador Esquema.

Exemplo de uma definição de Tipo de relação

Cada relação consiste em duas extremidades, denominadas endDef1 e endDef2.

No exemplo anterior, azure_sql_table_columns era o nome da relação que caracteriza uma tabela (endDef1) e as respetivas colunas (endDef2).

Para a definição completa, pode fazer um GET pedido para o seguinte ponto final com azure_sql_table_columns como o nome:

GET https://{{ENDPOINT}}/catalog/api/atlas/v2/types/typedef/name/azure_sql_table_columns

Abaixo, pode ver um resultado JSON simplificado:

{
  "category": "RELATIONSHIP",
  "guid": "c80d0027-8f29-6855-6395-d243b37d8a93",
  "name": "azure_sql_table_columns",
  "description": "azure_sql_table_columns",
  "serviceType": "Azure SQL Database",
  "relationshipCategory": "COMPOSITION",
  "endDef1": {
    "type": "azure_sql_table",
    "name": "columns",
    "isContainer": true,
    "cardinality": "SET",
  },
  "endDef2": {
    "type": "azure_sql_column",
    "name": "table",
    "isContainer": false,
    "cardinality": "SINGLE",
  }
}

  • name é o nome da definição de relação. Neste caso, o valor azure_sql_table_columns é utilizado no atributo relationshipTypeName da entidade que tem esta relação, como pode ver referenciado no json.

  • relationshipCategory é a categoria da relação e pode ser COMPOSIÇÃO, AGREGAÇÃO ou ASSOCIAÇÃO, conforme descrito aqui.

  • enDef1 é o primeiro fim da definição e contém os atributos:

    • type é o tipo da entidade que esta relação espera como end1.

    • name é o atributo que será apresentado no atributo de relação desta entidade.

    • A cardinalidade é SINGLE, SET ou LIST.

    • isContainer é um booleano e aplica-se à categoria de relação de contenção. Quando definido como verdadeiro numa das extremidades, indica que este é o contentor da outra extremidade. Por conseguinte:

      • Apenas as relações da categoria Composição ou Agregação podem e devem ter numa extremidade isContainer definido como verdadeiro.
      • A relação de categoria de associação não deve ter a propriedade isContainer definida como true em qualquer extremidade.

  • endDef2 é a segunda extremidade da definição e descreve, da mesma forma que endDef1, as propriedades da segunda parte da relação.

Separador Esquema

O que é o Esquema no Microsoft Purview?

O esquema é um conceito importante que reflete a forma como os dados são armazenados e organizados no arquivo de dados. Reflete a estrutura dos dados e as restrições de dados dos elementos que constroem a estrutura.

Os elementos no mesmo esquema podem ser classificados de forma diferente (devido ao respetivo conteúdo). Além disso, uma transformação diferente (linhagem) só pode acontecer a um subconjunto de elementos. Devido a estes aspetos, o Purview pode modelar elementos de esquema e esquema como entidades, pelo que o esquema é normalmente um atributo de relação para a entidade do recurso de dados. Exemplos de elementos de esquema são: colunas de uma tabela, propriedades json do esquema json, elementos xml do esquema xml, etc.

Existem dois tipos de esquemas:

  • Esquema Intrínseco – alguns sistemas são intrínsecos ao esquema. Por exemplo, quando cria uma Tabela SQL, o sistema requer que defina as colunas que constroem a tabela; neste sentido, o esquema de uma tabela é refletido pelas respetivas colunas.

    Para o arquivo de dados com esquema predefinido, o Purview utiliza a relação correspondente entre o recurso de dados e os elementos de esquema para refletir o esquema. Este atributo de relação é especificado pelo palavra-chave schemaElementsAttribute na propriedade options da definição do tipo de entidade.

  • Esquema Não Intrínseco – alguns sistemas não impõem essas restrições de esquema, mas os utilizadores podem utilizá-lo para armazenar dados estruturais ao aplicar alguns protocolos de esquema aos dados. Por exemplo, os Blobs do Azure armazenam dados binários e não se importam com os dados no fluxo binário. Portanto, não tem conhecimento de qualquer esquema, mas o utilizador pode serializar os dados com protocolos de esquema como json antes de os armazenar no blob. Neste sentido, o esquema é mantido por alguns protocolos adicionais e validação correspondente imposta pelo utilizador.

    Para o arquivo de dados sem esquema inerente, o modelo de esquema é independente deste arquivo de dados. Para tais casos, o Purview define uma interface para o esquema e uma relação entre o DataSet e o esquema, denominada dataset_attached_schemas – isto expande qualquer tipo de entidade que herda do DataSet para ter um atributo de relação attachedSchema para ligar à representação do esquema.

Exemplo do separador Esquema

O exemplo de Tabela de SQL do Azure acima tem um esquema intrínseco. As informações apresentadas no separador Esquema da Tabela de SQL do Azure são provenientes da própria Coluna SQL do Azure.

Ao selecionar um item de coluna, veríamos o seguinte:

Captura de ecrã da página da coluna addressID com o separador propriedades aberto e o tipo de dados realçado.

A questão é: como é que o Microsoft Purview selecionou a propriedade data_tye da coluna e a mostrou no separador Esquema da tabela?

Captura de ecrã da página SQL do Azure Tabela com a página de esquema aberta.

Pode obter a definição de tipo de uma Coluna SQL do Azure ao fazer um GET pedido para o ponto final:

GET https://{{ENDPOINT}}/catalog/api/atlas/v2/types/typedef/name/{name}

Observação

{name} neste caso é: azure_sql_column

Eis um resultado JSON simplificado:

{
  "category": "ENTITY",
  "guid": "58034a18-fc2c-df30-e474-75803c3a8957",
  "name": "azure_sql_column",
  "description": "azure_sql_column",
  "serviceType": "Azure SQL Database",
  "options": {
    "schemaAttributes": "[\"data_type\"]"
  },
  "attributeDefs": 
  [
    {
      "name": "data_type",
      "typeName": "string",
      "isOptional": false,
      "cardinality": "SINGLE",
      "valuesMinCount": 1,
      "valuesMaxCount": 1,
      "isUnique": false,
      "isIndexable": false,
      "includeInNotification": false
    }, 
  ...
  ]
  ...
}

Observação

serviceType é SQL do Azure Base de Dados, o mesmo que para a tabela

  • schemaAttributes está definido como data_type, que é um dos atributos deste tipo.

SQL do Azure Tabela utilizou schemaElementAttribute para apontar para uma relação que consiste numa lista de colunas SQL do Azure. A definição de tipo de uma coluna tem schemaAttributes definido.

Desta forma, o separador Esquema na tabela apresenta os atributos listados no esquemaAttributes dos recursos relacionados.

Criar definições de tipo personalizado

Por quê?

Primeiro, por que alguém gostaria de criar uma definição de tipo personalizado?

Pode haver casos em que não existe nenhum tipo incorporado que corresponda à estrutura dos metadados que pretende importar no Microsoft Purview.

Nesse caso, tem de ser definida uma nova definição de tipo.

Observação

A utilização de tipos incorporados deve ser favorecida em comparação com a criação de tipos personalizados, sempre que possível.

Agora que compreendemos as definições de tipo em geral, vamos criar definições de tipo personalizado.

Cenário

Neste tutorial, gostaríamos de modelar uma relação 1:n entre dois tipos, denominada custom_type_parent e custom_type_child.

Uma custom_type_child deve referenciar um elemento principal, enquanto um custom_type_parent pode referenciar uma lista de subordinados.

Devem estar ligados através de uma relação 1:n.

Dica

Aqui , pode encontrar algumas sugestões ao criar um novo tipo personalizado.

Criar definições

  1. Crie a definição de tipo de custom_type_parent ao fazer um POST pedido para um dos dois pontos finais seguintes:

Portal de governação clássico do Microsoft Purview:

POST https://{{ENDPOINT}}.purview.azure.com/catalog/api/atlas/v2/types/typedefs

Novo portal do Microsoft Purview:

POST https://api.purview-service.microsoft.com/catalog/api/atlas/v2/types/typedefs

Com o corpo:

 {
    "entityDefs": 
    [
        {
            "category": "ENTITY",
            "version": 1,
            "name": "custom_type_parent",
            "description": "Sample custom type of a parent object",
            "typeVersion": "1.0",
            "serviceType": "Sample-Custom-Types",
            "superTypes": [
                "DataSet"
            ],
            "subTypes": [],
            "options":{
                "schemaElementsAttribute": "columns"
            }
        }
    ]
 }
  1. Crie a definição de tipo de custom_type_child ao fazer um POST pedido para um dos dois pontos finais seguintes:

Portal de governação clássico do Microsoft Purview:

POST https://{{ENDPOINT}}.purview.azure.com/catalog/api/atlas/v2/types/typedefs

Novo portal do Microsoft Purview:

POST https://api.purview-service.microsoft.com/catalog/api/atlas/v2/types/typedefs

Com o corpo:

 {
    "entityDefs": 
    [
        {
            "category": "ENTITY",
            "version": 1,
            "name": "custom_type_child",
            "description": "Sample custom type of a CHILD object",
            "typeVersion": "1.0",
            "serviceType": "Sample-Custom-Types",
            "superTypes": [
                "DataSet"
            ],
            "subTypes": [],
            "options":{
               "schemaAttributes": "data_type"
            }
        }
    ]
 }
  1. Crie uma definição de relação de tipo personalizado ao fazer um POST pedido para um dos dois pontos finais seguintes:

Portal de governação clássico do Microsoft Purview:

POST https://{{ENDPOINT}}.purview.azure.com/catalog/api/atlas/v2/types/typedefs

Novo portal do Microsoft Purview:

POST https://api.purview-service.microsoft.com/catalog/api/atlas/v2/types/typedefs

Com o corpo:

{
    "relationshipDefs": [
        {
            "category": "RELATIONSHIP",
            "endDef1" : {
                "cardinality" : "SET",
                "isContainer" : true,
                "name" : "Children",
                "type" : "custom_type_parent"
            },
            "endDef2" : {
                "cardinality" : "SINGLE",
                "isContainer" : false,
                "name" : "Parent",
                "type" : "custom_type_child"
            },
            "relationshipCategory" : "COMPOSITION",
            "serviceType": "Sample-Custom-Types",
            "name": "custom_parent_child_relationship"
        }
    ]
}

Inicializar recursos de tipos personalizados

  1. Inicialize um novo recurso do tipo custom_type_parent ao fazer um POST pedido para um dos dois pontos finais seguintes:

Portal de governação clássico do Microsoft Purview:

POST https://{{ENDPOINT}}.purview.azure.com/catalog/api/atlas/v2/entity

Novo portal do Microsoft Purview:

POST https://api.purview-service.microsoft.com/catalog/api/atlas/v2/entity

Com o corpo:


{
    "entity": {
        "typeName":"custom_type_parent",
        "status": "ACTIVE",
        "version": 1,
         "attributes":{
            "name": "First_parent_object",
            "description": "This is the first asset of type custom_type_parent",
            "qualifiedName": "custom//custom_type_parent:First_parent_object"
         }

    }
}

Guarde o guid , pois irá precisar dele mais tarde.

  1. Inicialize um novo recurso do tipo custom_type_child ao fazer um POST pedido para um dos dois pontos finais seguintes:

Portal de governação clássico do Microsoft Purview:

POST https://{{ENDPOINT}}.purview.azure.com/catalog/api/atlas/v2/entity

Novo portal do Microsoft Purview:

POST https://api.purview-service.microsoft.com/catalog/api/atlas/v2/entity

Com o corpo:

{
   "entity": {
       "typeName":"custom_type_child",
       "status": "ACTIVE",
       "version": 1,
       "attributes":{
           "name": "First_child_object",
           "description": "This is the first asset of type custom_type_child",
           "qualifiedName": "custom//custom_type_child:First_child_object"
        }
   }
}

Guarde o guid , pois irá precisar dele mais tarde.

  1. Inicialize uma nova relação do tipo custom_parent_child_relationship ao fazer um POST pedido para um dos dois pontos finais seguintes:

Portal de governação clássico do Microsoft Purview:

POST https://{{ENDPOINT}}.purview.azure.com/catalog/api/atlas/v2/relationship/

Novo portal do Microsoft Purview:

POST https://api.purview-service.microsoft.com/catalog/api/atlas/v2/relationship/

Com o seguinte corpo:

Observação

O guid no final1 tem de ser substituído pelo guid do objeto criado no passo 6.1 O guid no final2 tem de ser substituído pelo guid do objeto criado no passo 6.2

{
   "typeName": "custom_parent_child_relationship",
   "end1": {
         "guid": "...",
       "typeName": "custom_type_parent"
   },
   "end2": {
       "guid": "...",
       "typeName": "custom_type_child"
   }
}

Ver os recursos no Microsoft Purview

  1. Aceda a Catálogo de Dados no Microsoft Purview.

  2. Selecione Procurar.

  3. Selecione Por tipo de origem.

  4. Selecione Exemplo-Tipos Personalizados.

    Captura de ecrã a mostrar o caminho do Catálogo de Dados para Procurar recursos com o filtro reduzido a Sample-Custom-Types.

  5. Selecione o First_parent_object:

    Captura de ecrã da página First_parent_object.

  6. Selecione o separador Propriedades :

    Captura de ecrã a mostrar o separador propriedades com os recursos relacionados realçados, com um elemento subordinado.

  7. Pode ver a First_child_object a ser ligada.

  8. Selecione o First_child_object:

    Captura de ecrã da página First_child_object, com o separador descrição geral.

  9. Selecione o separador Propriedades :

    Captura de ecrã a mostrar a página de propriedades, com os recursos relacionados com um único elemento principal.

  10. Pode ver o objeto Principal a ser ligado.

  11. Da mesma forma, pode selecionar o separador Relacionados e verá a relação entre os dois objetos:

    Captura de ecrã a mostrar o separador Relacionados, com a relação entre o menor e o elemento principal.

  12. Pode criar várias crianças ao inicializar um novo elemento subordinado e inititialzar uma relação

    Observação

    O qualifiedName é exclusivo por recurso, pelo que o segundo subordinado deve ser chamado de forma diferente, como: custom//custom_type_child:Second_child_object

    Captura de ecrã a mostrar o First_parent_object, com os dois elementos subordinados realçados.

    Dica

    Se eliminar o First_parent_object irá reparar que as crianças também serão removidas, devido à relação COMPOSIÇÃO que escolhemos na definição.

Limitações

Existem várias limitações conhecidas ao trabalhar com tipos personalizados que serão melhorados no futuro, tais como:

  • O separador Relação tem um aspeto diferente em comparação com os tipos incorporados
  • Os tipos personalizados não têm ícones
  • A hierarquia não é suportada

Próximas etapas

Gerir origens de dadosapIs REST do plano de dados do Microsoft Purview