Creación de recursos mediante la API REST

  • Artículo

En este tutorial, aprenderá a crear recursos en el Mapa de datos de Microsoft Purview que los usuarios pueden buscar y examinar en el Catálogo de datos de Microsoft Purview.

Nota:

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

Si ya tiene la entidad de servicio y el token de autenticación, puede ir directamente a los pasos para crear recursos 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 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é configurada para confiar.

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.

  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.

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 hora 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 la entidad de servicio

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

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

  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 es 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 el rol Data Curator a la entidad de servicio creada anteriormente. Para obtener pasos detallados, consulte Asignación de roles de Azure mediante el portal de gobernanza de Microsoft Purview.

Una vez que haya asignado 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 el identificador de inquilino, busque Propiedades de inquilino en el Azure Portal. El identificador está 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: debe ser "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.

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

Creación de recursos mediante la API REST

Ahora que tiene un token y puede autenticarse, está listo para crear los recursos.

Importante

Los puntos de conexión de url de solicitud dependen de la experiencia de Microsoft Purview que esté usando: la experiencia clásica de Microsoft Purview o el nuevo portal de Microsoft Purview.

Creación de recursos de Azure

Este es un ejemplo que puede usar para crear las entidades para los recursos de Azure. En este ejemplo se trata una cuenta de Azure Storage, pero puede usarla para cualquier otro origen de Azure.

Importante

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

  • Typename
  • Owner
  • qualifiedName
  • name
  • Id. de experto
  • Información de expertos
  • Identificador de propietario
  • Información del propietario
  • Createdby
  • Updatedby

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

Método: POST

Autenticación: use el token del paso anterior como 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
  }
}

Creación de recursos 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 los recursos de Azure, reemplace estos valores en la carga:

  • Typename
  • Owner
  • qualifiedName
  • name
  • type
  • Id. de experto
  • Información de expertos
  • Identificador de propietario
  • Información del propietario
  • Createdby
  • Updatedby

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

Método: POST

Autenticación: use el token del paso anterior como 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
  }
}

Siguientes pasos

Administración de orígenes de datosReferencia de la API REST de entidad de Microsoft Purview