Condividi tramite

Esercitazione: Usare le API REST

  • Articolo

Questa esercitazione descrive come usare le API REST del piano dati Microsoft Purview. Chiunque voglia inviare dati a Microsoft Purview, includere Microsoft Purview come parte di un processo automatizzato o creare la propria esperienza utente in Microsoft Purview può usare le API REST per farlo.

Se non si ha una sottoscrizione di Azure, creare un account gratuito prima di iniziare.

Prerequisiti

Creare un'entità servizio (applicazione)

Per consentire a un client API REST di accedere alle API del piano dati di Microsoft Purview, il client deve avere un'entità servizio (applicazione) e un'identità riconosciuta da Microsoft Purview e configurata per l'attendibilità. Quando si effettuano chiamate API REST, l'identità dell'entità servizio verrà usata per l'autorizzazione.

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.

    Screenshot della pagina di registrazione dell'applicazione, con le opzioni precedenti compilate.

  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.

    Screenshot della pagina dell'applicazione nel portale con l'ID applicazione (client) evidenziato.

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

  1. Nel portale di Azure cercare e selezionare Azure Active Directory e quindi selezionare Registrazioni app nel riquadro sinistro.

  2. Selezionare l'entità servizio (applicazione) dall'elenco.

  3. Selezionare Certificati & segreti nel riquadro sinistro.

  4. Selezionare Nuovo segreto client.

  5. Nella pagina Aggiungi un segreto client immettere una descrizione, selezionare un'ora di scadenza in Scadenza e quindi selezionare Aggiungi.

    Nella pagina Segreti client la stringa nella colonna Valore del nuovo segreto è la password. Salvare questo valore.

    Screenshot che mostra un segreto client.

Configurare l'autenticazione usando l'entità servizio

Dopo aver creato la nuova entità servizio, è necessario assegnare i ruoli del piano dati dell'account purview all'entità servizio creata in precedenza. Seguire la procedura seguente per assegnare il ruolo corretto per stabilire l'attendibilità tra l'entità servizio e l'account Purview:

  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 sarà 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 i ruoli seguenti all'entità servizio creata in precedenza per accedere a vari piani dati in Microsoft Purview. Per i passaggi dettagliati, vedere Assegnare ruoli di Azure usando il portale di governance di Microsoft Purview.

    • Ruolo Curatore dati per accedere al piano dati del catalogo.
    • Ruolo Amministratore origine dati per accedere al piano dati di analisi.
    • Raccolta Amministrazione ruolo per accedere al piano dati dell'account e al piano dati dei criteri di metadati.
    • Ruolo Autore criteri per accedere all'API dei criteri DevOps

    Nota

    Solo i membri del ruolo Collection Amministrazione possono assegnare ruoli del piano dati in Microsoft Purview. Per altre informazioni sui ruoli di Microsoft Purview, vedere Controllo di accesso in Microsoft Purview.

Ottenere il token

È possibile 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 sarà 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".
  • risorsa: '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.

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

Passaggi successivi

Gestire le origini datiAPI REST del piano dati Microsoft Purview