Esercitazione: Eseguire l'autenticazione per le API

Questa esercitazione descrive come eseguire l'autenticazione per le API del piano dati Microsoft Purview. Chiunque desideri 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 per farlo.

Prerequisiti

• Per iniziare, è necessario disporre di un account Microsoft Purview esistente. Se non si dispone di un catalogo, vedere la guida introduttiva per la creazione di un account Microsoft Purview.

Creare un'entità servizio (applicazione)

Per consentire a un client API 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, 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 Microsoft Entra ID.

3. Nella pagina Microsoft Entra ID 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. Per Chi può usare questa applicazione o accedere a questa API?, selezionare i tipi di account utente che si prevede di usare questa API.

      Consiglio

      Se si prevede che solo gli utenti del tenant Microsoft Entra ID corrente usino l'API REST, selezionare Account solo in questa directory organizzativa (<solo il nome> del tenant - Tenant singolo). In caso contrario, considerare le altre opzioni.

   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 individuata da:

1. Nel portale di Azure cercare e selezionare Microsoft Entra ID 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.

   

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 Microsoft Entra ID e viene 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.
• Assicurarsi che il software sia aggiornato per l'applicazione in uso per inviare la richiesta POST.

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