Creare asset usando l'API REST

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.

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

• Se non si ha una sottoscrizione di Azure, creare un account gratuito prima di iniziare.
• È necessario disporre di un account Microsoft Purview esistente. In caso contrario, verificare se l'organizzazione ha accesso alla versione gratuita di Microsoft Purview oppure usare questa guida di avvio rapido per creare un account Microsoft Purview.

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.

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.

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.

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

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