Definições de tipo e como criar tipos personalizados

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

Neste tutorial, você aprenderá a:

  • Como o Microsoft Purview usa 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, você precisará de:

Observação

Antes de passar para a parte prática do tutorial, as primeiras quatro seções explicarão o que é um Tipo de Sistema e como ele é usado no Microsoft Purview. Todas as chamadas de API REST descritas mais detalhadamente usarão o token de portador e o ponto de extremidade descritos nos pré-requisitos.

Para ir diretamente para as etapas, use estes links:

O que são ativos e tipos no Microsoft Purview?

Um ativo é um elemento de metadados que descreve um recurso digital ou físico. Os recursos digitais ou físicos que devem ser catalogados como ativos incluem:

  • Fontes de dados, como bancos de dados, arquivos e feed de dados.
  • Modelos e processos analíticos.
  • Políticas e termos de negócios.
  • infraestrutura como o servidor.

O Microsoft Purview fornece aos usuários um sistema de tipos flexível para expandir a definição do ativo para incluir novos tipos de recursos à medida que eles se tornam relevantes. O Microsoft Purview depende do Sistema de Tipos do Apache Atlas. Todos os objetos de metadados (ativos) gerenciados pelo Microsoft Purview são modelados usando definições de tipo. Compreender o Sistema de Tipos é fundamental para criar novos tipos personalizados no Microsoft Purview.

Essencialmente, um Type pode ser visto como uma classe da OOP (Programação Orientada a Objetos):

  • Ele define as propriedades que representam esse tipo.
  • Cada tipo é identificado exclusivamente por seu nome.
  • Um tipo pode herdar de um supertType. Este é um conceito equivalente à herança de OOP. Um tipo que estende um superType herdará os atributos do superType.

Você pode ver todas as definições de tipo em sua conta do Microsoft Purview enviando uma GET solicitação para o ponto de extremidade 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 comumente usados como supertipos.

Por exemplo:

  • Referenciável: esse tipo representa todas as entidades que podem ser pesquisadas usando um atributo exclusivo chamado qualifiedName.

  • Ativo: Este tipo se estende de Referenciável e possui outros atributos, como: nome, descrição e proprietário.

  • DataSet: esse tipo estende Referenciável e Ativo. Conceitualmente, ele pode ser usado para representar um tipo que armazena dados. Pode-se esperar que os tipos que estendem DataSet tenham um Esquema. Por exemplo, uma tabela SQL.

  • Linhagem: As informações de linhagem ajudam a entender a origem dos dados e as transformações pelas quais eles podem ter passado antes de chegar a um arquivo ou tabela. A linhagem é calculada por meio de DataSet e Process: DataSets (entrada do processo) impactam alguns outros DataSets (saída do processo) por meio de Process.

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

Exemplo de uma definição de Tipo

Para entender melhor o sistema de tipos, vamos examinar um exemplo e ver como uma tabela SQL do Azure é definida.

Você pode obter a definição de tipo completa enviando uma GET solicitação para o ponto de extremidade Definição de tipo:

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

Dica

A propriedade {name} informa em qual definição você está interessado. Nesse caso, você deve usar azure_sql_table.

Abaixo, você 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 de tipo JSON, vamos examinar algumas propriedades:

  • O campo Categoria descreve em qual categoria seu tipo está. A lista de categorias compatíveis com o Apache Atlas pode ser encontrada aqui.

  • ServiceType é útil ao procurar ativos por tipo de origem no Microsoft Purview. O tipo de serviço será um ponto de entrada para localizar todos os ativos que pertencem ao mesmo tipo de serviço , conforme definido em sua definição de tipo. Na captura de tela abaixo da interface do usuário do Purview, o usuário limita o resultado para ser as entidades especificadas com o Banco de Dados SQL do Azure em serviceType:

    Captura de tela do portal mostrando o caminho do Catálogo unificado para Procurar até Por tipo de origem e o ativo realçado.

    Observação

    O Banco de Dados SQL do Azure é definido com o mesmo serviceType que a Tabela SQL do Azure.

  • SuperTipos descreve os tipos "pai" dos quais você deseja "herdar".

  • schemaElementsAttributes das opções influencia o que aparece na guia Esquema do seu ativo no Microsoft Purview.

    Abaixo, você pode ver um exemplo de como é a guia Esquema para um ativo do tipo Tabela SQL do Azure:

    Captura de tela da guia de esquema de um ativo de Tabela SQL do Azure.

  • relationshipAttributeDefs são calculados por meio das definições de tipo de relação. Em nosso JSON, podemos ver que schemaElementsAttributes aponta para o atributo de relacionamento chamado colunas - que é um dos elementos do array 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 sua própria definição. O nome da definição é encontrado no atributo relationshipTypeName . Nesse caso, é azure_sql_table_columns.

    • A cardinalidade desse atributo de relação é definida como *SET, o que sugere que ele contém uma lista de ativos relacionados.
    • O ativo relacionado é do tipo azure_sql_column, conforme visível no atributo typeName .

    Em outras palavras, o atributo de relação de colunas relaciona a Tabela SQL do Azure a uma lista de Colunas SQL do Azure que aparecem na guia Esquema.

Exemplo de uma relação Definição de tipo

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

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

Para obter a definição completa, você pode fazer uma GET solicitação para o seguinte ponto de extremidade usando azure_sql_table_columns como nome:

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

Abaixo, você 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 da relação. O valor, neste caso azure_sql_table_columns é usado no atributo relationshipTypeName da entidade que tem esse relacionamento, como você pode ver referenciado no json.

  • relationshipCategory é a categoria da relação e pode ser COMPOSITION, AGGREGATION ou ASSOCIATION, conforme descrito aqui.

  • enDef1 é a primeira extremidade da definição e contém os atributos:

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

    • name é o atributo que aparecerá no atributo de relacionamento dessa entidade.

    • cardinalidade é SINGLE, SET ou LIST.

    • isContainer é um booliano e se aplica à categoria de relação de contenção. Quando definido como true em uma extremidade, indica que essa extremidade é o contêiner da outra extremidade. Portanto:

      • Somente as relações de categoria Composição ou Agregação podem e devem ter em uma extremidade isContainer definido como true.
      • A relação de categoria de associação não deve ter a propriedade isContainer definida como true em nenhuma extremidade.

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

Guia Esquema

O que é Esquema no Microsoft Purview?

Esquema é um conceito importante que reflete como os dados são armazenados e organizados no armazenamento de dados. Ele reflete a estrutura dos dados e as restrições de dados dos elementos que constroem a estrutura.

Elementos no mesmo esquema podem ser classificados de forma diferente (devido ao seu conteúdo). Além disso, diferentes transformações (linhagem) podem acontecer apenas com um subconjunto de elementos. Devido a esses aspectos, o Purview pode modelar esquema e elementos de esquema como entidades, portanto, o esquema geralmente é um atributo de relação com a entidade do ativo de dados. Exemplos de elementos de esquema são: colunas de uma tabela, propriedades json do esquema json, elementos xml do esquema xml etc.

Há dois tipos de esquemas:

  • Esquema Intrínseco - Alguns sistemas são intrínsecos ao esquema. Por exemplo, quando você cria uma tabela SQL, o sistema exige que você defina as colunas que constroem a tabela; Nesse sentido, o esquema de uma tabela é refletido por suas colunas.

    Para o armazenamento de dados com esquema predefinido, o Purview usa a relação correspondente entre o ativo de dados e os elementos do esquema para refletir o esquema. Esse atributo de relação é especificado pela palavra-chave schemaElementsAttributena propriedade options da definição de tipo de entidade.

  • Esquema não intrínseco – alguns sistemas não impõem essas restrições de esquema, mas os usuários podem usá-las para armazenar dados estruturais aplicando 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, ele não tem conhecimento de nenhum esquema, mas o usuário pode serializar seus dados com protocolos de esquema como json antes de armazená-los no blob. Nesse sentido, o esquema é mantido por alguns protocolos extras e validação correspondente imposta pelo usuário.

    Para o armazenamento de dados sem esquema inerente, o modelo de esquema é independente desse armazenamento de dados. Para esses casos, o Purview define uma interface para o esquema e uma relação entre o DataSet e o esquema, chamada dataset_attached_schemas – isso estende qualquer tipo de entidade que herda do DataSet para ter um atributo de relação attachedSchema para vincular à sua representação de esquema.

Exemplo da guia Esquema

O exemplo de tabela SQL do Azure acima tem um esquema intrínseco. As informações que aparecem na guia Esquema da Tabela SQL do Azure vêm da própria Coluna SQL do Azure.

Selecionando um item de coluna, veremos o seguinte:

Captura de tela da página da coluna addressID com a guia de propriedades aberta e o tipo de dados realçado.

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

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

Você pode obter a definição de tipo de uma coluna SQL do Azure fazendo uma GET solicitação para o ponto de extremidade:

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

Observação

{name} neste caso é: azure_sql_column

Aqui está 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 Banco de dados, o mesmo que para a tabela

  • schemaAttributes é definido como data_type, que é um dos atributos desse tipo.

A Tabela SQL do Azure usou schemaElementAttribute para apontar para uma relação que consiste em uma lista de Colunas SQL do Azure. A definição de tipo de uma coluna tem schemaAttributes definidos.

Dessa forma, a guia Esquema na tabela exibe o(s) atributo(s) listado(s) nos schemaAttributes dos ativos relacionados.

Criar definições de tipo personalizadas

Por quê?

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

Pode haver casos em que não há nenhum tipo interno que corresponda à estrutura dos metadados que você deseja importar no Microsoft Purview.

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

Observação

O uso de tipos internos deve ser favorecido em relação à criação de tipos personalizados, sempre que possível.

Agora que entendemos as definições de tipo em geral, vamos criar definições de tipo personalizadas.

Cenário

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

Um custom_type_child deve fazer referência a um dos pais, enquanto um custom_type_parent pode fazer referência a uma lista de filhos.

Eles devem estar ligados através de um relacionamento 1:n.

Dica

Aqui você pode encontrar algumas dicas ao criar um novo tipo personalizado.

Criar definições

  1. Crie a definição do tipo de custom_type_parent fazendo uma POST solicitação para um dos dois pontos de extremidade a seguir:

Portal de governança do Microsoft Purview clássico:

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 do tipo de custom_type_child fazendo uma POST solicitação para um dos dois pontos de extremidade a seguir:

Portal de governança do Microsoft Purview clássico:

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 personalizada fazendo uma POST solicitação para um dos dois pontos de extremidade a seguir:

Portal de governança do Microsoft Purview clássico:

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 ativos de tipos personalizados

  1. Inicialize um novo ativo do tipo custom_type_parent fazendo uma POST solicitação para um dos dois pontos de extremidade a seguir:

Portal de governança do Microsoft Purview clássico:

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

    }
}

Salve o GUID , pois você precisará dele mais tarde.

  1. Inicialize um novo ativo do tipo custom_type_child fazendo uma POST solicitação para um dos dois pontos de extremidade a seguir:

Portal de governança do Microsoft Purview clássico:

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

Salve o GUID , pois você precisará dele mais tarde.

  1. Inicialize uma nova relação do tipo custom_parent_child_relationship fazendo uma POST solicitação para um dos dois pontos de extremidade a seguir:

Portal de governança do Microsoft Purview clássico:

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 em end1 deve ser substituído pelo guid do objeto criado na etapa 6.1 O guid em end2 deve ser substituído pelo guid do objeto criado na etapa 6.2

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

Exibir os ativos no Microsoft Purview

  1. Vá para o Catálogo unificado no Microsoft Purview.

  2. Selecione Procurar.

  3. Selecione Por tipo de origem.

  4. Selecione Sample-Custom-Types.

    Captura de tela mostrando o caminho do Catálogo unificado para Procurar ativos com o filtro restrito a Sample-Custom-Types.

  5. Selecione o First_parent_object:

    Captura de tela da página First_parent_object.

  6. Selecione a guia Propriedades :

    Captura de tela da guia de propriedades com os ativos relacionados destacados, mostrando um ativo filho.

  7. Você pode ver o First_child_object sendo vinculado lá.

  8. Selecione o First_child_object:

    Captura de tela da página First_child_object, mostrando a guia visão geral.

  9. Selecione a guia Propriedades :

    Captura de tela da página de propriedades, mostrando os ativos relacionados com um único ativo pai.

  10. Você pode ver o objeto Pai sendo vinculado lá.

  11. Da mesma forma, você pode selecionar a guia Relacionado e verá a relação entre os dois objetos:

    Captura de tela da guia Relacionado, mostrando a relação entre o filho e o pai.

  12. Você pode criar vários filhos inicializando um novo ativo filho e iniciando uma relação

    Observação

    O qualifiedName é exclusivo por ativo, portanto, o segundo filho deve ser chamado de forma diferente, como: custom//custom_type_child:Second_child_object

    Captura de tela do First_parent_object, mostrando os dois ativos filho realçados.

    Dica

    Se você excluir o First_parent_object notará que os filhos também serão removidos, devido à relação COMPOSITION que escolhemos na definição.

Limitações

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

  • A guia Relações parece diferente em comparação com tipos internos
  • Os tipos personalizados não têm ícones
  • Não há suporte para hierarquia

Próximas etapas

Gerenciar fontes de dadosAPIs REST do plano de dados do Microsoft Purview

  • Last updated on