Definiciones de tipos y cómo crear tipos personalizados

Artículo
06/06/2024

En este tutorial se explica qué son las definiciones de tipos, cómo crear tipos personalizados y cómo inicializar recursos de tipos personalizados en Microsoft Purview.

En este tutorial, aprenderá lo siguiente:

Cómo Usa Microsoft Purview el sistema de tipos de Apache Atlas
Cómo crear un nuevo tipo personalizado
Creación de relaciones entre tipos personalizados
Inicializar nuevas entidades de tipos personalizados

Requisitos previos

Para este tutorial necesitará:

Una cuenta de Azure con una suscripción activa. Si no tiene una, puede crear una cuenta de forma gratuita.
Una cuenta activa de Microsoft Purview (anteriormente Azure Purview). Si no tiene ninguna, consulte la guía para empezar a trabajar con Microsoft Purview de forma gratuita.
Un token de portador para su cuenta de Microsoft Purview. Para establecer un token de portador y llamar a cualquier API, consulte la documentación sobre cómo autenticar las API para Microsoft Purview.
El punto de conexión de Apache Atlas de la cuenta de Microsoft Purview. Será uno de estos dos puntos de conexión, en función del entorno:
- Si usa el portal de gobernanza de Microsoft Purview clásico: https://{{ACCOUNTNAME}}.purview.azure.com/catalog
- Si usa el nuevo portal de Microsoft Purview: https://api.purview-service.microsoft.com/catalog

Nota:

Antes de pasar a la parte práctica del tutorial, las cuatro primeras secciones explicarán qué es un tipo de sistema y cómo se usa en Microsoft Purview. Todas las llamadas a la API REST que se describen más adelante usarán el token de portador y el punto de conexión que se describen en los requisitos previos.

Para ir directamente a los pasos, use estos vínculos:

Creación de definiciones de tipos personalizados
Inicializar recursos de tipos personalizados

¿Qué son los recursos y tipos en Microsoft Purview?

Un recurso es un elemento de metadatos que describe un recurso físico o digital. Los recursos físicos o digitales que se espera que se cataloge como recursos incluyen:

Orígenes de datos como bases de datos, archivos y fuentes de distribución de datos.
Modelos y procesos analíticos.
Directivas y términos empresariales.
Infraestructura como el servidor.

Microsoft Purview proporciona a los usuarios un sistema de tipos flexible para expandir la definición del recurso a fin de incluir nuevos tipos de recursos a medida que sean pertinentes. Microsoft Purview se basa en el sistema de tipos de Apache Atlas. Todos los objetos de metadatos (recursos) administrados por Microsoft Purview se modela mediante definiciones de tipo. Comprender el sistema de tipos es fundamental para crear nuevos tipos personalizados en Microsoft Purview.

Básicamente, un tipo se puede ver como una clase de programación orientada a objetos (OOP):

Define las propiedades que representan ese tipo.
Cada tipo se identifica de forma única por su nombre.
Un tipo puede heredar de un supertType. Se trata de un concepto equivalente como herencia de OOP. Un tipo que extiende un superType heredará los atributos del superType.

Para ver todas las definiciones de tipos en la cuenta de Microsoft Purview, envíe una GET solicitud al punto de conexión Todas las definiciones de tipo :

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

Apache Atlas tiene pocos tipos de sistema predefinidos que se usan normalmente como supertipos.

Por ejemplo:

Referenciable: este tipo representa todas las entidades que se pueden buscar mediante un atributo único denominado qualifiedName.
Recurso: este tipo se extiende desde Referenceable y tiene otros atributos como: nombre, descripción y propietario.
DataSet: este tipo extiende Referenceable y Asset. Conceptualmente, se puede usar para representar un tipo que almacena datos. Se puede esperar que los tipos que extienden DataSet tengan un esquema. Por ejemplo, una tabla SQL.
Linaje: la información de linaje ayuda a comprender el origen de los datos y las transformaciones que pueden haber pasado antes de llegar a un archivo o tabla. El linaje se calcula a través de DataSet y Process: Los conjuntos de datos (entrada de proceso) afectan a otros conjuntos de datos (salida del proceso) a través del proceso.

Ejemplo de una definición de tipo

Para comprender mejor el sistema de tipos, echemos un vistazo a un ejemplo y veamos cómo se define una tabla de Azure SQL.

Para obtener la definición de tipo completa, envíe una GET solicitud al punto de conexión definición de tipo:

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

Sugerencia

La propiedad {name} indica la definición que le interesa. En este caso, debe usar azure_sql_table.

A continuación, puede ver un 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",
    },
  ]
}

En función de la definición de tipo JSON, echemos un vistazo a algunas propiedades:

El campo Categoría describe en qué categoría es su tipo. La lista de categorías admitidas por Apache Atlas se puede encontrar aquí.
El campo ServiceType es útil al examinar los recursos por tipo de origen en Microsoft Purview. El tipo de servicio será un punto de entrada para buscar todos los recursos que pertenecen al mismo tipo de servicio , tal como se define en su definición de tipo. En la captura de pantalla siguiente de la interfaz de usuario de Purview, el usuario limita el resultado a ser las entidades especificadas con Azure SQL Database en serviceType:

Nota:

Azure SQL Database se define con el mismo serviceType que Azure SQL Table.
SuperTypes describe los tipos "primarios" de los que quiere "heredar".
schemaElementsAttributes de las opciones influye en lo que aparece en la pestaña Esquema del recurso en Microsoft Purview.

A continuación, puede ver un ejemplo de cómo se parece la pestaña Esquema para un recurso de tipo Azure SQL Tabla:
relationshipAttributeDefs se calcula a través de las definiciones de tipo de relación. En nuestro JSON, podemos ver que schemaElementsAttributes apunta al atributo de relación denominado columns , que es uno de los elementos de la matriz relationshipAttributeDefs , como se muestra a continuación:
```
...
"relationshipAttributeDefs": [
     ...
     {
       "name": "columns",
       "typeName": "array<azure_sql_column>",
       "isOptional": true,
       "cardinality": "SET",
       "relationshipTypeName": "azure_sql_table_columns",
     },
   ]
```
Cada relación tiene su propia definición. El nombre de la definición se encuentra en el atributo relationshipTypeName . En este caso, es azure_sql_table_columns.
- La cardinalidad de este atributo de relación se establece en *SET, lo que sugiere que contiene una lista de recursos relacionados.
- El recurso relacionado es de tipo azure_sql_column, como visible en el atributo typeName .
En otras palabras, el atributo de relación columns relaciona el Azure SQL Table con una lista de Azure SQL columnas que se muestran en la pestaña Esquema.

Ejemplo de una definición de tipo de relación

Cada relación consta de dos extremos, denominados endDef1 y endDef2.

En el ejemplo anterior, azure_sql_table_columns era el nombre de la relación que caracteriza una tabla (endDef1) y sus columnas (endDef2).

Para la definición completa, puede realizar una GET solicitud al siguiente punto de conexión mediante azure_sql_table_columns como nombre:

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

A continuación, puede ver un 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 es el nombre de la definición de relación. El valor, en este caso , azure_sql_table_columns se usa en el atributo relationshipTypeName de la entidad que tiene esta relación, como puede ver que se hace referencia en json.
relationshipCategory es la categoría de la relación y puede ser COMPOSITION, AGGREGATION o ASSOCIATION como se describe aquí.
enDef1 es el primer extremo de la definición y contiene los atributos:
- type es el tipo de la entidad que esta relación espera como end1.
- name es el atributo que aparecerá en el atributo de relación de esta entidad.
- cardinalidad es SINGLE, SET o LIST.
- isContainer es un valor booleano y se aplica a la categoría de relación de contención. Cuando se establece en true en un extremo, indica que este extremo es el contenedor del otro extremo. Por lo tanto:
  - Solo las relaciones de categoría Composición o Agregación pueden y deben tener en un extremo isContainer establecido en true.
  - La relación de categoría de asociación no debe tener la propiedad isContainer establecida en true en ningún extremo.
endDef2 es el segundo extremo de la definición y describe, de forma similar a endDef1, las propiedades de la segunda parte de la relación.

Pestaña Esquema

¿Qué es schema en Microsoft Purview?

El esquema es un concepto importante que refleja cómo se almacenan y organizan los datos en el almacén de datos. Refleja la estructura de los datos y las restricciones de datos de los elementos que construyen la estructura.

Los elementos del mismo esquema se pueden clasificar de forma diferente (debido a su contenido). Además, puede producirse una transformación diferente (linaje) solo en un subconjunto de elementos. Debido a estos aspectos, Purview puede modelar los elementos de esquema y esquema como entidades, por lo que el esquema suele ser un atributo de relación con la entidad del recurso de datos. Algunos ejemplos de elementos de esquema son: columnas de una tabla, propiedades json del esquema json, elementos xml del esquema xml, etc.

Hay dos tipos de esquemas:

Esquema intrínseco : algunos sistemas son intrínsecos al esquema. Por ejemplo, al crear una tabla SQL, el sistema requiere que defina las columnas que construyen la tabla; en este sentido, el esquema de una tabla se refleja en sus columnas.

Para el almacén de datos con esquema predefinido, Purview usa la relación correspondiente entre el recurso de datos y los elementos de esquema para reflejar el esquema. Este atributo de relación se especifica mediante la palabra clave schemaElementsAttribute en la propiedad options de la definición del tipo de entidad.
Esquema no intrínseco : algunos sistemas no aplican estas restricciones de esquema, pero los usuarios pueden usarlo para almacenar datos estructurales mediante la aplicación de algunos protocolos de esquema a los datos. Por ejemplo, los blobs de Azure almacenan datos binarios y no se preocupan por los datos de la secuencia binaria. Por lo tanto, no es consciente de ningún esquema, pero el usuario puede serializar sus datos con protocolos de esquema como json antes de almacenarlos en el blob. En este sentido, el esquema se mantiene mediante algunos protocolos adicionales y la validación correspondiente aplicada por el usuario.

Para el almacén de datos sin esquema inherente, el modelo de esquema es independiente de este almacén de datos. En estos casos, Purview define una interfaz para el esquema y una relación entre DataSet y esquema, denominada dataset_attached_schemas : esto amplía cualquier tipo de entidad que herede de DataSet para tener un atributo de relación attachedSchema para vincular a su representación de esquema.

Ejemplo de pestaña Esquema

El ejemplo Azure SQL Table de arriba tiene un esquema intrínseco. La información que se muestra en la pestaña Esquema de la tabla de Azure SQL procede de la propia columna Azure SQL.

Al seleccionar un elemento de columna, se vería lo siguiente:

La pregunta es, ¿cómo seleccionó Microsoft Purview la propiedad data_tye de la columna y la mostró en la pestaña Esquema de la tabla?

Puede obtener la definición de tipo de una columna de Azure SQL realizando una GET solicitud al punto de conexión:

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

Nota:

{name} en este caso es: azure_sql_column

Este es un 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
    }, 
  ...
  ]
  ...
}

Nota:

serviceType es Azure SQL Database, igual que para la tabla

schemaAttributes se establece en data_type, que es uno de los atributos de este tipo.

Azure SQL Table usó schemaElementAttribute para apuntar a una relación que consta de una lista de columnas de Azure SQL. La definición de tipo de una columna tiene schemaAttributes definido.

De este modo, la pestaña Esquema de la tabla muestra los atributos enumerados en los schemaAttributes de los recursos relacionados.

Creación de definiciones de tipos personalizados

¿Por qué?

En primer lugar, ¿por qué a alguien le gustaría crear una definición de tipo personalizado?

Puede haber casos en los que no haya ningún tipo integrado que se corresponda con la estructura de los metadatos que desea importar en Microsoft Purview.

En tal caso, debe definirse una nueva definición de tipo.

Nota:

El uso de tipos integrados se debe favorecer sobre la creación de tipos personalizados, siempre que sea posible.

Ahora que hemos obtenido una comprensión de las definiciones de tipos en general, vamos a crear definiciones de tipos personalizadas.

Escenario

En este tutorial, nos gustaría modelar una relación 1:n entre dos tipos, denominados custom_type_parent y custom_type_child.

Un custom_type_child debe hacer referencia a un elemento primario, mientras que un custom_type_parent puede hacer referencia a una lista de elementos secundarios.

Deben vincularse entre sí a través de una relación 1:n.

Sugerencia

Aquí puede encontrar algunas sugerencias al crear un nuevo tipo personalizado.

Creación de definiciones

Cree la definición de tipo custom_type_parent realizando una POST solicitud a uno de los dos puntos de conexión siguientes:

Portal de gobernanza de Microsoft Purview clásico:

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

Nuevo portal de Microsoft Purview:

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

Con el cuerpo:

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

Cree la definición de tipo custom_type_child realizando una POST solicitud a uno de los dos puntos de conexión siguientes:

Portal de gobernanza de Microsoft Purview clásico:

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

Nuevo portal de Microsoft Purview:

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

Con el cuerpo:

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

Cree una definición de relación de tipo personalizada mediante la realización de una POST solicitud a uno de los dos puntos de conexión siguientes:

Portal de gobernanza de Microsoft Purview clásico:

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

Nuevo portal de Microsoft Purview:

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

Con el cuerpo:

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

Inicialice un nuevo recurso de tipo custom_type_parent realizando una POST solicitud a uno de los dos puntos de conexión siguientes:

Portal de gobernanza de Microsoft Purview clásico:

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

Nuevo portal de Microsoft Purview:

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

Con el cuerpo:


{
    "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 el guid , ya que lo necesitará más adelante.

Inicialice un nuevo recurso de tipo custom_type_child realizando una POST solicitud a uno de los dos puntos de conexión siguientes:

Portal de gobernanza de Microsoft Purview clásico:

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

Nuevo portal de Microsoft Purview:

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

Con el cuerpo:

{
   "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 el guid , ya que lo necesitará más adelante.

Inicialice una nueva relación de tipo custom_parent_child_relationship realizando una POST solicitud a uno de los dos puntos de conexión siguientes:

Portal de gobernanza de Microsoft Purview clásico:

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

Nuevo portal de Microsoft Purview:

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

Con el siguiente cuerpo:

Nota:

El guid de end1 debe reemplazarse por el guid del objeto creado en el paso 6.1 El guid de end2 debe reemplazarse por el guid del objeto creado en el paso 6.2.

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

Visualización de los recursos en Microsoft Purview

Vaya a Data Catalog en Microsoft Purview.
Seleccione Examinar.
Seleccione Por tipo de origen.
Seleccione Sample-Custom-Types (Tipos personalizados de ejemplo).
Seleccione el First_parent_object:
Seleccione la pestaña Propiedades :
Puede ver los First_child_object que se vinculan allí.
Seleccione el First_child_object:
Seleccione la pestaña Propiedades :
Puede ver el objeto Primario vinculado allí.
Del mismo modo, puede seleccionar la pestaña Relacionado y verá la relación entre los dos objetos:
Puede crear varios elementos secundarios inicializando un nuevo recurso secundario e inicializando una relación

Nota:

qualifiedName es único por recurso, por lo que se debe llamar al segundo elemento secundario de forma diferente, como: custom//custom_type_child:Second_child_object

Sugerencia

Si elimina el First_parent_object observará que los elementos secundarios también se quitarán, debido a la relación COMPOSITION que elegimos en la definición.

Limitaciones

Hay varias limitaciones conocidas al trabajar con tipos personalizados que se mejorarán en el futuro, como:

La pestaña Relación tiene un aspecto diferente en comparación con los tipos integrados
Los tipos personalizados no tienen iconos
No se admite la jerarquía

Pasos siguientes

Administración de orígenes de datos Api REST del plano de datos de Microsoft Purview

Compartir a través de

Definiciones de tipos y cómo crear tipos personalizados

Requisitos previos

¿Qué son los recursos y tipos en Microsoft Purview?

Ejemplo de una definición de tipo

Ejemplo de una definición de tipo de relación

Pestaña Esquema

¿Qué es schema en Microsoft Purview?

Ejemplo de pestaña Esquema

Creación de definiciones de tipos personalizados

¿Por qué?

Escenario

Creación de definiciones

Inicializar recursos de tipos personalizados

Visualización de los recursos en Microsoft Purview

Limitaciones

Pasos siguientes

Comentarios

Recursos adicionales