Compartir a través de

Tutorial: Uso de las API REST

  • Artículo

En este tutorial, aprenderá a usar las API REST del plano de datos de Microsoft Purview. Cualquier persona que quiera enviar datos a Microsoft Purview, incluir Microsoft Purview como parte de un proceso automatizado o crear su propia experiencia de usuario en Microsoft Purview puede usar las API REST para hacerlo.

Si no tiene una suscripción de Azure, cree una cuenta gratuita antes de empezar.

Requisitos previos

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

Para que un cliente de API REST acceda a las API del plano de datos de Microsoft Purview, el cliente debe tener una entidad de servicio (aplicación) y una identidad que Microsoft Purview reconozca y esté configurada para confiar. Cuando realice llamadas a la API REST, se usará la identidad de esa entidad de servicio para la autorización.

Los clientes que han usado entidades de servicio existentes (identificadores de aplicación) han tenido una alta tasa de errores. Por lo tanto, se recomienda 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 Azure Active Directory.

  3. En la página Azure Active Directory, 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 servicio).
    2. Seleccione Solo cuentas en este directorio organizativo (<solo nombre> del inquilino: inquilino único).
    3. En URI de redirección (opcional), seleccione Web y escriba un valor. Este valor no tiene que ser un punto de conexión válido. https://exampleURI.com lo hará.
    4. Seleccione Registrar.

    Captura de pantalla de la página de registro de la aplicación, con las opciones anteriores rellenadas.

  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 más adelante.

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

    Captura de pantalla de la página de la aplicación en el portal con el identificador de aplicación (cliente) resaltado.

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

  1. En el Azure Portal, busque y seleccione Azure Active Directory y, a continuación, seleccione Registros de aplicaciones en el panel izquierdo.

  2. Seleccione la entidad de servicio (aplicación) en la lista.

  3. Seleccione Certificados & secretos en el panel izquierdo.

  4. Seleccione Nuevo secreto de cliente.

  5. En la página Agregar un secreto de cliente , escriba una descripción, seleccione una hora de expiración en Expiración y, a continuación, seleccione Agregar.

    En la página Secretos de cliente , la cadena de la columna Valor del nuevo secreto es la contraseña. Guarde este valor.

    Captura de pantalla que muestra un secreto de cliente.

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

Una vez creada la nueva entidad de servicio, debe asignar los roles de plano de datos de la cuenta de Purview a la entidad de servicio creada anteriormente. Siga los pasos siguientes para asignar el rol correcto para establecer la confianza entre la entidad de servicio y la cuenta de Purview:

  1. Vaya al portal de gobernanza de Microsoft Purview.

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

  3. Seleccione Colecciones.

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

    Nota:

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

  5. Seleccione la pestaña Asignaciones de roles .

  6. Asigne los siguientes roles a la entidad de servicio creada anteriormente para acceder a varios planos de datos en Microsoft Purview. Para obtener pasos detallados, consulte Asignación de roles de Azure mediante el portal de gobernanza de Microsoft Purview.

    • Rol de conservador de datos para acceder al plano de datos del catálogo.
    • Rol administrador del origen de datos para acceder al plano de datos de examen.
    • Rol de Administración de recopilación para acceder al plano de datos de la cuenta y al plano de datos de la directiva de metadatos.
    • Rol de autor de directivas para acceder a la API de directivas de DevOps

    Nota:

    Solo los miembros del rol de Administración colección pueden asignar roles de plano de datos en Microsoft Purview. Para obtener más información sobre los roles de Microsoft Purview, consulte Access Control en Microsoft Purview.

Obtener token

Puede enviar 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 el identificador de inquilino, busque Propiedades de inquilino en el Azure Portal. El identificador estará disponible en la página de propiedades del inquilino.

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

  • client_id: id. de cliente de la aplicación registrada en Azure Active Directory y se asigna 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: debe ser "client_credentials".
  • resource: 'https://purview.azure.net'

Esta es una solicitud POST de ejemplo en PowerShell:

$tenantID = "12a345bc-67d1-ef89-abcd-efg12345abcde"

$url = "https://login.microsoftonline.com/$tenantID/oauth2/token"
$params = @{ client_id = "a1234bcd-5678-9012-abcd-abcd1234abcd"; 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 página única".

  • 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.
  • Si usa una aplicación como Postman, asegúrese de que el software está actualizado.

Use el token de acceso anterior para llamar a las API del plano de datos.

Siguientes pasos

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