Creación de activos mediante la API REST

Importante

Retirada solo de las funcionalidades de gobierno de datos de Microsoft Purview

Se retirarán el Catálogo unificado de Microsoft Purview y las funcionalidades de gobierno de datos de Microsoft Purview clásico (anteriormente Azure Purview). Microsoft Purview en su conjunto no se retirará. Las capacidades de seguridad y cumplimiento de los datos de Microsoft Purview no se ven afectadas por este anuncio, y Microsoft seguirá invirtiendo en ellas.

Microsoft está consolidando sus capacidades de gobernanza de datos en Microsoft Fabric. Ya no se podrán crear nuevas cuentas de gobierno de datos de Microsoft Purview y las funcionalidades de gobierno de datos existentes permanecerán en modo de mantenimiento hasta el 12 de noviembre de 2027.

Para conocer los plazos de retirada, las instrucciones de transición y los próximos pasos recomendados, consulte el anuncio de retirada de la gobernanza de datos de Microsoft Purview.

En este tutorial, aprenderá a crear activos en el mapa de datos de Microsoft Purview que los usuarios pueden buscar y examinar en el catálogo unificado de Microsoft Purview.

Nota:

Si usa la versión gratuita de Microsoft Purview, solo los usuarios del grupo de roles Conservador de datos podrán acceder a estos activos.

Si ya tiene la entidad de servicio y el token de autenticación, puede pasar directamente a los pasos para crear activos mediante la API REST. De lo contrario, siga esta guía para llamar a la API REST.

Requisitos previos

Creación de una entidad de servicio (aplicación)

Para que un cliente de API de REST acceda a Microsoft Purview para crear entidades, el cliente debe tener una entidad de servicio (aplicación) y una identidad que Microsoft Purview reconozca y esté configurado para confiar.

Los clientes que han usado entidades de servicio existentes (id. de aplicación) han tenido una alta tasa de errores. Por lo tanto, recomendamos crear una nueva entidad de servicio para llamar a las API.

Para crear una nueva entidad de servicio:

  1. Inicie sesión en el portal de Azure.

  2. En el portal, busque y seleccione Microsoft Entra ID.

  3. En la página de Microsoft Entra ID , seleccione Registros de aplicaciones en el panel izquierdo.

  4. Seleccione Nuevo registro.

  5. En la página Registrar una aplicación :

    1. Escriba un nombre para la aplicación (el nombre de la entidad de seguridad de servicio).
    2. Seleccione Solo las cuentas de este directorio organizativo (<solo el nombre> del inquilino: inquilino único).
    3. En URI de redireccionamiento (opcional), seleccione Web y escriba un valor. No es necesario que este valor sea un punto de conexión válido. https://exampleURI.com servirá.
    4. Seleccione Registrar.
  6. En la nueva página de entidad de servicio, copie los valores del nombre para mostrar y el identificador de aplicación (cliente) para guardarlos para más adelante.

    El id. de aplicación es el client_id valor del código de ejemplo.

Para usar la entidad de servicio (aplicación), debe conocer la contraseña de la entidad de servicio:

  1. Seleccione la entidad de servicio (aplicación) en la lista de registros de aplicaciones .
  2. Seleccione Certificados & secretos en el panel izquierdo.
  3. Seleccione Nuevo secreto de cliente.
  4. En la página Agregar un secreto de cliente , escriba una descripción, seleccione una fecha de expiración en Expiración y, a continuación, seleccione Agregar.
  5. En la página Secretos de cliente , la cadena de la columna Valor del nuevo secreto es la contraseña. Guarde este valor.

Configuración de la autenticación mediante una entidad de servicio

Una vez creada la nueva entidad de servicio, debes asignar permisos para que la entidad de servicio pueda acceder a tu cuenta de Microsoft Purview. Los permisos que debes asignar dependen de si usas la experiencia clásica de Microsoft Purview o el nuevo portal de Microsoft Purview.

Seleccione la pestaña correspondiente a la experiencia que está usando.

  1. Vaya al portal de gobierno de Microsoft Purview.

  2. Seleccione el mapa de datos en el menú de la izquierda.

  3. Seleccione Colecciones.

  4. Seleccione la colección raíz en el menú de colecciones. Esta es la colección principal de la lista y tendrá el mismo nombre que tu cuenta de Microsoft Purview.

    Nota:

    También puede asignar el permiso de entidad de servicio a cualquier subcolección, en lugar de a la colección raíz. Sin embargo, todas las API se aplicarán al ámbito de esa colección (y subcolecciones que heredan permisos) y los usuarios que intenten llamar a la API para otra colección obtendrán errores.

  5. Seleccione la pestaña Asignaciones de roles .

  6. Asigne la función Conservador de datos a la entidad de servicio creada anteriormente. Para ver los pasos detallados, consulte Asignación de roles de Azure mediante el portal de gobierno de Microsoft Purview.

Después de asignar los permisos, deberá recopilar el token de autenticación.

  1. Envíe una solicitud POST a la siguiente dirección URL para obtener el token de acceso:

    https://login.microsoftonline.com/{your-tenant-id}/oauth2/token

    Para encontrar su identificador de inquilino, busque Propiedades de inquilino en Azure Portal. El identificador está disponible en la página de propiedades del inquilino.

    Los siguientes parámetros deben pasarse a la URL anterior:

    • client_id: id. de cliente de la aplicación registrada en Microsoft Entra ID y asignado a un rol de plano de datos para la cuenta de Microsoft Purview.
    • client_secret: secreto de cliente creado para la aplicación anterior.
    • grant_type: Debería ser "client_credentials".
    • resource: This should be 'https://purview.azure.net'

    Este es un ejemplo de solicitud POST en PowerShell:

    $tenantID = "12a345bc-67d1-ef89-abcd-efg12345abcde"
    
    $url = "https://login.microsoftonline.com/$tenantID/oauth2/token"
    $params = @{ client_id = "00001111-aaaa-2222-bbbb-3333cccc4444"; client_secret = "abcd~a1234bcd56789012abcdabcd1234abcd"; grant_type = "client_credentials"; resource = ‘https://purview.azure.net’ }
    
    Invoke-WebRequest $url -Method Post -Body $params      -UseBasicParsing | ConvertFrom-Json
    

    Token de respuesta de ejemplo:

    {
        "token_type": "Bearer",
        "expires_in": "86399",
        "ext_expires_in": "86399",
        "expires_on": "1621038348",
        "not_before": "1620951648",
        "resource": "https://purview.azure.net",
        "access_token": "<<access token>>"
    }
    

    Sugerencia

    Si recibe un mensaje de error que dice: El canje de tokens entre orígenes solo se permite para el tipo de cliente "Aplicación de una sola página".

    • Compruebe los encabezados de solicitud y confirme que la solicitud no contiene el encabezado "origin".
    • Confirme que el URI de redireccionamiento está establecido en web en la entidad de servicio.
    • Asegúrate de que el software esté actualizado para la aplicación que estás utilizando para enviar tu solicitud POST.
  2. Use el token de acceso anterior para llamar a las API del plano de datos.

Creación de activos mediante la API REST

Ahora que tiene un token y puede autenticarse, está listo para crear sus activos.

Importante

Los puntos de conexión de dirección URL de solicitud dependen de la experiencia de Microsoft Purview que use: la experiencia clásica de Microsoft Purview o el nuevo portal de Microsoft Purview

Crear activos de Azure

Este es un ejemplo que puede usar para crear las entidades para los recursos de Azure. Este ejemplo cubre una cuenta de Azure Storage, pero puede usarlo para cualquier otro origen de Azure.

Importante

Para usar este ejemplo para sus recursos de Azure, reemplace estos valores en la carga útil:

  • Nombre de tipo
  • Owner
  • nombrecualificado
  • name
  • Id. de experto
  • Información de expertos
  • Id. de propietario
  • Información del propietario
  • Creado por
  • Actualizadopor

URL de la solicitud: https://{accountName}.purview.azure.com/catalog/api/atlas/v2/entity

Método: POST

Autenticación: utiliza el token del paso anterior como tu token de portador.

Ejemplo de carga útil:

{
  "referredEntities": {},
  "entity": {
    "typeName": "azure_storage_account",
    "attributes": {
      "owner": "ExampleOwner",
      "modifiedTime": 0,
      "createTime": 0,
      "qualifiedName": "https://exampleaccount.core.windows.net",
      "name": "ExampleStorageAccount",
      "description": null,
      "publicAccessLevel": null
    },
    "contacts": {
      "Expert": [
        {
          "id": "30435ff9-9b96-44af-a5a9-e05c8b1ae2d2",
          "info": "Example Expert Info"
        }
      ],
      "Owner": [
        {
          "id": " 30435ff9-9b96-44af-a5a9-e05c8b1ae2d2",
          "info": "Example Owner Info"
        }
      ]
    },
    "status": "ACTIVE",
    "createdBy": "ExampleCreator",
    "updatedBy": "ExampleUpdator",
    "version": 0
  }
}

Crear activos multinube

Este es un ejemplo que puede usar para crear las entidades para recursos multinube. En este ejemplo se crea un recurso de Snowflake, pero puede usarlo para cualquier otro origen

Importante

Para usar este ejemplo para sus recursos de Azure, reemplace estos valores en la carga útil:

  • Nombre de tipo
  • Owner
  • nombrecualificado
  • name
  • type
  • Id. de experto
  • Información de expertos
  • Id. de propietario
  • Información del propietario
  • Creado por
  • Actualizadopor

URL de la solicitud: https://{accountName}.purview.azure.com/catalog/api/atlas/v2/entity

Método: POST

Autenticación: utiliza el token del paso anterior como tu token de portador.

Ejemplo de carga útil:

{
  "referredEntities": {},
  "entity": {
    "typeName": "snowflake_table",
    "attributes": {
      "owner": "ExampleOwner",
      "modifiedTime": 0,
      "createTime": 0,
      "qualifiedName": "snowflake://microsoft_partner.east-us-2.azure.snowflakecomputing.com/databases/AZUREPURVIEW_TESTDB/schemas/COMPANY/tables/PROJECT_INFO",
      "name": "PROJECT_INFO",
      "description": null,
      "type": "TABLE"
    },
    "contacts": {
      "Expert": [
        {
          "id": "30435ff9-9b96-44af-a5a9-e05c8b1ae2d2",
          "info": "Example Expert Info"
        }
      ],
      "Owner": [
        {
          "id": "4b27e65f-6a15-4925-a4ef-2e640445079b",
          "info": "Example Owner Info"
        }
      ]
    },
    "status": "ACTIVE",
    "createdBy": "ExampleCreator",
    "updatedBy": "ExampleUpdator",
    "version": 0
  }
}

Pasos siguientes