Microsoft Purview - Creare una derivazione personalizzata con le API REST

Importante

Microsoft Purview Unified Catalog e le funzionalità classiche di governance dei dati di Microsoft Purview (in precedenza Azure Purview) verranno ritirate. Microsoft sta consolidando le proprie funzionalità di governance dei dati in Microsoft Fabric. Non è più possibile creare nuovi account e le funzionalità esistenti rimarranno in modalità di manutenzione fino al 12 novembre 2027. Per le tempistiche di ritiro, le linee guida per la transizione e i passaggi successivi consigliati, vedere l'annuncio relativo al ritiro della governance dei dati di Microsoft Purview.

Nota

Microsoft Purview Data Catalog (versione classica), Data Health Insights (versione classica) e Purview Workflow (versione classica) non accettano più nuovi clienti e questi servizi, in precedenza Azure Purview, sono ora in modalità di supporto tecnico.

Questo articolo illustra la procedura per creare voci di derivazione dei dati usando l'API REST in Microsoft Purview Data Catalog. Negli scenari in cui la derivazione generata automaticamente in Microsoft Purview è incompleta o mancante, la derivazione può essere personalizzata manualmente nel portale di Microsoft Purview o usando le API REST. Questo articolo si concentra sull'uso delle API REST che possono superare le limitazioni note della derivazione manuale e fornire più opzioni.

Background

La possibilità di mostrare la derivazione tra i set di dati è una delle funzionalità importanti della piattaforma Microsoft Purview. Sistemi come Data Factory, Condivisione dati e Power BI acquisiscono la derivazione dei dati man mano che si sposta. In alcune situazioni, la derivazione generata automaticamente di Microsoft Purview è incompleta o mancante ai fini della visualizzazione pratica e della creazione di report aziendali. In questi scenari, la creazione di report di derivazione personalizzata è supportata dagli hook di Apache Atlas e dall'API REST.

L'uso delle API REST per creare la derivazione personalizzata consente di superare alcune delle limitazioni della derivazione manuale, come descritto negli articoli seguenti:

Il resto di questo articolo illustra l'uso delle API REST di Microsoft Purview per creare e segnalare la derivazione personalizzata in Microsoft Purview.

Prerequisiti

Scenari

Esistono due casi d'uso quando diventa necessaria la creazione di una derivazione personalizzata:

R. Creare nuove entità create e collegarle con la derivazione

B. Collegare entità o lignaggio esistenti a un'altra entità o lignaggio esistente

Ad esempio, la derivazione deve essere segnalata tra le entità A & B, ma A & B attualmente non esistono.

Per creare le entità A & B, richiamare l'API REST di Microsoft Purview: Entità - Creazione o aggiornamento in blocco - API REST

POST https://{accountname}.purview.azure.com/datamap/api/atlas/v2/entity/bulk?api-version=2023-09-01
sample_entity_json = '{"entity": {"status": "ACTIVE","version": 0,"name": ENTITY_A"}.......{"entity": ........}}'
#Send POST JSON containing entities to be created
CreateOrUpdateEntitesUrl = 'https://<purview_account_name>.purview.azure.com/datamap/api/atlas/v2/entity/bulk'
EntitiesResponse = requests.post(CreateOrUpdateEntitesUrl, json = json.loads(sample_entity_json) ,headers=headers)
entitiesRes = json.loads(EntitiesResponse.text)

La risposta API "201 Created" indica che le entità sono state create correttamente e che i rispettivi GUID sono contenuti nel JSON di output.

Ora che le entità A & B sono state create, vai al passaggio B per collegare le entità nella catena di derivazione utilizzando la stessa API REST.

  • Se il numero di entità da collegare non richiede tempo o risorse (ad esempio, meno di 20-30 entità), è possibile connettere manualmente la derivazione nel portale di Microsoft Purview. Segui la guida per l'utente della derivazione manuale per la procedura di creazione manuale delle connessioni di derivazione.
  • Se si ha un numero elevato di connessioni di derivazione da effettuare, il processo deve essere automatizzato oppure, se la derivazione manuale usando il portale di Microsoft Purview non è fattibile, procedere con il processo API di collegamento e creazione di derivazione personalizzata.

Payload JSON di derivazione personalizzata:

Esegui l'entità POST /entity/bulk- Creazione o aggiornamento in blocco - API REST utilizzando il payload come illustrato:

POST https://{accountname}.purview.azure.com/datamap/api/atlas/v2/entity/bulk?api-version=2023-09-01
sample_entity_json = '{
  "entities": [
    {
      "status": "ACTIVE",
      "version": 1,
      "typeName": "Process",
      "attributes": {
        "inputs": [
          {
            "guid": "24558fd8-9cdc-47de-9310-56a58108bab0",
            “guid”: “27163581-9aca-212a-782a-213612639abc”
          }
        ],
        "outputs": [
          {
            "guid": "e33c694a-2c4f-4cae-8c27-06f6f6f60000"
          }
        ],
        "qualifiedName": "cassandra://query",
        "name": "query"
      }
    }
  ]
}'

#In this code snippet, we send the JSON as POST request containing the two GUIDs as input and "output" GUID as output. This creates lineage with 2 directional inputs and 1 directional output.
#Note: using the same API and SDK code you can create lineage with any number of inputs, any number of processes in between, any number of typedefs and any number of outputs.
#The API/SDK method is the most flexible and versatile menthod of creating lineage.
 
CreateLineageEntitesUrl = 'https://<purview_account_name>.purview.azure.com/datamap/api/atlas/v2/entity/bulk'
EntitiesResponse = requests.post(CreateLineageEntitesUrl, json = json.loads(sample_entity_json),headers=headers)
entitiesRes = json.loads(EntitiesResponse.text)

Questo payload JSON crea la derivazione personalizzata. Funziona per asset già esistenti i cui GUID sono forniti nel JSON "inputs". Ad esempio, "guid": "24558fd8-9cdc-47de-9310-56a58108bab0" e "27163581-9aca-212a-782a-213612639abc" fanno riferimento all'input direzionale della derivazione e "guid": "e33c694a-2c4f-4cae-8c27-06f6f6f60000" fa riferimento all'output direzionale della derivazione, ovvero una risorsa esistente analizzata automaticamente da Purview. Abbiamo solo creato il lignaggio tra le due risorse.

Nota

Se le risorse non esistono già, devi eseguire l'API di creazione di entità in blocco prima di questo passaggio per creare tali entità prima di creare la relazione di derivazione. Il processo di creazione di entità in blocco utilizzando l'API POST /entity/bulk e lo snippet di codice Python è descritto nel passaggio A.

Risultati dello scenario

La risposta API "201 Created" indica che la creazione del collegamento al grafo di derivazione è riuscita e i GUID creati sono contenuti nel JSON di output. La derivazione viene visualizzata nel portale di Microsoft Purview:

  • Scenario A: derivazione personalizzata da risorse create tramite API:

    Screenshot che mostra lo scenario A: derivazione personalizzata da risorse create tramite API.

  • Scenario B: derivazione personalizzata da asset preesistenti collegati tramite API.

    Nota

    Se la derivazione viene creata da entità preesistenti, osservare che il grafico della derivazione preesistente rimane intatto e che il nuovo collegamento venga creato e visualizzato in aggiunta.

    Screenshot che mostra lo scenario B: derivazione personalizzata da asset preesistenti collegati tramite API.