Condividi tramite

Microsoft Purview - Creare derivazione personalizzata con le API REST

  • Articolo

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

Background

La possibilità di mostrare la derivazione tra set di dati è una delle importanti funzionalità della piattaforma di Microsoft Purview. Sistemi come Data Factory, Condivisione dati e Power BI acquisiscono la derivazione dei dati man mano che si spostano. In determinate situazioni, la derivazione generata automaticamente da Microsoft Purview è incompleta o mancante per scopi pratici di visualizzazione e creazione di report aziendali. In questi scenari, i report di derivazione personalizzati sono supportati dagli hook Apache Atlas e dall'API REST.

L'uso delle API REST per creare 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 compilare e segnalare derivazione personalizzata in Microsoft Purview.

Prerequisiti

Scenari

Ci sono due casi d'uso quando la creazione di derivazione personalizzata diventa necessaria:

R. Creare nuove entità create e collegarle alla derivazione

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

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

Per creare le entità A & B, richiamare l'API REST di Microsoft Purview: Entity - Bulk Create or Update - REST API

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)

Risposta API "201 Created" indica che le entità vengono create correttamente e i rispettivi GUID sono contenuti nel codice JSON di output.

Ora che vengono create le entità A & B, passare al passaggio B per collegare le entità nella catena di derivazione usando la stessa API REST.

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

Payload JSON di derivazione personalizzato:

Eseguire l'API POST /entity/bulkEntity - Bulk Create or Update - REST usando il payload come illustrato di seguito:

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 gli asset già esistenti i cui GUID vengono forniti nel codice JSON "inputs". Ad esempio "guid": "24558fd8-9cdc-47de-9310-56a58108bab0" e "27163581-9aca-212a-782a-213612639 abc" si riferisce all'input direzionale della derivazione e "guid": "e33c694a-2c4f-4cae-8c27-06f6f6f60000" si riferisce all'output direzionale della derivazione, che era un asset esistente analizzati automaticamente da Purview. Abbiamo appena creato la derivazione tra i due asset.

Nota

Se gli asset non esistono già, è necessario eseguire l'API di creazione di entità bulk prima di questo passaggio per creare tali entità prima di creare la relazione di derivazione. Il processo di creazione di entità bulk usando l'API POST /entity/bulk e il frammento di codice Python è descritto nel passaggio A.

Risultati dello scenario

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

  • Scenario A: Derivazione compilata personalizzata dagli asset creati tramite API:

    Screenshot che mostra lo scenario A: Derivazione compilata personalizzata dagli asset creati tramite API.

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

    Nota

    Se la derivazione viene creata da entità preesistenti, osservare che il grafo di derivazione preesistente rimane intatto e il nuovo collegamento viene creato e visualizzato anche.

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