Condividi tramite

Creare asset usando l'API REST

  • Articolo

In questa esercitazione si apprenderà come creare asset nel Microsoft Purview Data Map in cui gli utenti sono in grado di cercare e esplorare il Microsoft Purview Data Catalog.

Nota

Se si usa la versione gratuita di Microsoft Purview, solo gli utenti del gruppo di ruoli curatore dati potranno accedere a questi asset.

Se si dispone già dell'entità servizio e del token di autenticazione, è possibile passare direttamente alla procedura per creare gli asset usando l'API REST. In caso contrario, seguire questa guida per chiamare l'API REST.

Prerequisiti

Creare un'entità servizio (applicazione)

Per consentire a un client API REST di accedere a Microsoft Purview per creare entità, il client deve avere un'entità servizio (applicazione) e un'identità riconosciuta da Microsoft Purview e configurata per l'attendibilità.

I clienti che hanno usato entità servizio esistenti (ID applicazione) hanno avuto un tasso elevato di errori. È pertanto consigliabile creare una nuova entità servizio per chiamare le API.

Per creare una nuova entità servizio:

  1. Accedere al portale di Azure.

  2. Nel portale cercare e selezionare Azure Active Directory.

  3. Nella pagina Azure Active Directory selezionare Registrazioni app nel riquadro sinistro.

  4. Selezionare Nuova registrazione.

  5. Nella pagina Registra un'applicazione :

    1. Immettere un nome per l'applicazione (il nome dell'entità servizio).
    2. Selezionare Account solo in questa directory dell'organizzazione (<solo nome> del tenant - Tenant singolo).
    3. Per URI di reindirizzamento (facoltativo) selezionare Web e immettere un valore. Questo valore non deve essere un endpoint valido. https://exampleURI.com farà.
    4. Selezionare Registra.

  6. Nella nuova pagina dell'entità servizio copiare i valori del nome visualizzato e dell'ID applicazione (client) da salvare per un secondo momento.

    L'ID applicazione è il client_id valore nel codice di esempio.

Per usare l'entità servizio (applicazione), è necessario conoscere la password dell'entità servizio:

  1. Selezionare l'entità servizio (applicazione) nell'elenco Registrazioni app.
  2. Selezionare Certificati & segreti nel riquadro sinistro.
  3. Selezionare Nuovo segreto client.
  4. Nella pagina Aggiungi un segreto client immettere una descrizione, selezionare un'ora di scadenza in Scadenza e quindi selezionare Aggiungi.
  5. Nella pagina Segreti client la stringa nella colonna Valore del nuovo segreto è la password. Salvare questo valore.

Configurare l'autenticazione usando l'entità servizio

Dopo aver creato la nuova entità servizio, è necessario assegnare le autorizzazioni in modo che l'entità servizio possa accedere all'account Microsoft Purview. Le autorizzazioni che è necessario assegnare dipendono dall'uso dell'esperienza classica di Microsoft Purview o del nuovo portale di Microsoft Purview.

Selezionare la scheda per l'esperienza in uso.

  1. Passare al portale di governance di Microsoft Purview.

  2. Selezionare la mappa dati nel menu a sinistra.

  3. Selezionare Raccolte.

  4. Selezionare la raccolta radice nel menu raccolte. Questa è la raccolta principale nell'elenco e avrà lo stesso nome dell'account Microsoft Purview.

    Nota

    È anche possibile assegnare l'autorizzazione dell'entità servizio a qualsiasi sotto-raccolta anziché alla raccolta radice. Tuttavia, tutte le API avranno l'ambito per tale raccolta (e le sottoraccolte che ereditano le autorizzazioni) e gli utenti che tentano di chiamare l'API per un'altra raccolta riceveranno errori.

  5. Selezionare la scheda Assegnazioni di ruolo .

  6. Assegnare il ruolo Curatore dati all'entità servizio creata in precedenza. Per i passaggi dettagliati, vedere Assegnare ruoli di Azure usando il portale di governance di Microsoft Purview.

Dopo aver assegnato le autorizzazioni, sarà necessario raccogliere il token di autenticazione.

  1. Inviare una richiesta POST all'URL seguente per ottenere il token di accesso:

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

    È possibile trovare l'ID tenant cercando Proprietà tenant nel portale di Azure. L'ID è disponibile nella pagina delle proprietà del tenant.

    È necessario passare i parametri seguenti all'URL precedente:

    • client_id: ID client dell'applicazione registrata in Azure Active Directory e assegnato a un ruolo del piano dati per l'account Microsoft Purview.
    • client_secret: segreto client creato per l'applicazione precedente.
    • grant_type: deve essere "client_credentials".
    • resource: deve essere 'https://purview.azure.net'

    Ecco una richiesta POST di esempio in 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 di risposta di esempio:

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

    Consiglio

    Se viene visualizzato un messaggio di errore che indica che il riscatto del token tra origini è consentito solo per il tipo client "Applicazione a pagina singola".

    • Controllare le intestazioni della richiesta e verificare che la richiesta non contenga l'intestazione 'origin'.
    • Verificare che l'URI di reindirizzamento sia impostato sul Web nell'entità servizio.
    • Se si usa un'applicazione come Postman, assicurarsi che il software sia aggiornato.

  2. Usare il token di accesso precedente per chiamare le API del piano dati.

Creare asset usando l'API REST

Ora che si dispone di un token e si può eseguire l'autenticazione, si è pronti per creare gli asset.

Importante

Gli endpoint URL della richiesta dipendono dall'esperienza di Microsoft Purview in uso: l'esperienza classica di Microsoft Purview o il nuovo portale di Microsoft Purview

Creare asset di Azure

Ecco un esempio che è possibile usare per creare le entità per le risorse di Azure. Questo esempio illustra un account di archiviazione di Azure, ma è possibile usarlo per qualsiasi altra origine Di Azure.

Importante

Per usare questo esempio per le risorse di Azure, sostituire questi valori nel payload:

  • Typename
  • Proprietario
  • qualifiedName
  • Nome
  • ID esperto
  • Informazioni sull'esperto
  • ID proprietario
  • Informazioni sul proprietario
  • Createdby
  • Updatedby

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

Metodo: POST

Autenticazione: usare il token del passaggio precedente come token di connessione.

Esempio di payload:

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

Creare asset multicloud

Ecco un esempio che è possibile usare per creare le entità per le risorse multicloud. Questo esempio crea una risorsa Snowflake, ma è possibile usarla per qualsiasi altra origine

Importante

Per usare questo esempio per le risorse di Azure, sostituire questi valori nel payload:

  • Typename
  • Proprietario
  • qualifiedName
  • Nome
  • tipo
  • ID esperto
  • Informazioni sull'esperto
  • ID proprietario
  • Informazioni sul proprietario
  • Createdby
  • Updatedby

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

Metodo: POST

Autenticazione: usare il token del passaggio precedente come token di connessione.

Esempio di payload:

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

Passaggi successivi

Informazioni di riferimento sulle API REST per la gestione delle origini datidi Microsoft Purview Entity