Compartilhar via

Microsoft Purview – Criar linhagem personalizada com as APIs REST

  • Artigo

Este artigo fornece os passos para criar entradas de linhagem de dados com a API REST no Catálogo de Dados do Microsoft Purview. Em cenários em que a linhagem gerada automaticamente no Microsoft Purview está incompleta ou em falta, a linhagem pode ser personalizada criada manualmente no portal do Microsoft Purview ou através das APIs REST. Este artigo centra-se na utilização de APIs REST que podem ultrapassar as limitações conhecidas da linhagem manual e fornecer mais opções.

Histórico

A capacidade de mostrar a linhagem entre conjuntos de dados é uma das funcionalidades importantes da plataforma do Microsoft Purview. Sistemas como o Data Factory, o Data Share e o Power BI capturam a linhagem de dados à medida que se movem. Em determinadas situações, a linhagem gerada automaticamente pelo Microsoft Purview está incompleta ou em falta para fins práticos de visualização e relatórios empresariais. Nesses cenários, os relatórios de linhagem personalizados são suportados pelos hooks do Apache Atlas e pela API REST.

Utilizar as APIs REST para criar linhagem personalizada permite-lhe ultrapassar algumas das limitações da linhagem manual, conforme descrito nos seguintes artigos:

O resto deste artigo explica a utilização das APIs REST do Microsoft Purview para criar e reportar linhagem personalizada no Microsoft Purview.

Pré-requisitos

Cenários

Existem dois casos de utilização quando a criação de linhagem personalizada se torna necessária:

A. Criar novas entidades criadas e ligá-las à linhagem

B. Ligar entidades ou linhagem existentes a outra entidade ou linhagem existente

Por exemplo, a linhagem tem de ser comunicada entre as entidades A & B, mas A & B não existe atualmente.

Para criar as entidades A & B, invoque a API REST do Microsoft Purview: Entidade – Criar ou Atualizar em Massa – 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)

A Resposta da API "201 Criado" indica que as entidades foram criadas com êxito e os respetivos GUIDs estão contidos no JSON de saída.

Agora que as entidades A & B são criadas, avance para o passo B para ligar as entidades na cadeia de linhagem com a mesma API REST.

  • Se o número de entidades a associar não for intensivo em termos de tempo ou de recursos (por exemplo, menos de 20 a 30 entidades), pode ligar a linhagem manualmente no portal do Microsoft Purview. Siga o manual lineage user guide (Manual lineage user guide ) para obter os passos para criar manualmente ligações de linhagem.
  • Se tiver um elevado número de ligações de linhagem para efetuar, o processo tem de ser automatizado ou, se a linhagem manual que utiliza o portal do Microsoft Purview não for viável, avance para o processo de API de ligação e criação de linhagem personalizada.

Payload JSON de Linhagem Personalizada:

Execute a Entidade POST /entity/bulk– Criação ou Atualização em Massa – API REST com o payload, conforme ilustrado:

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)

Este payload JSON cria a linhagem personalizada. Funciona para recursos já existentes cujos GUIDs são fornecidos no JSON "inputs". Por exemplo, "guid": "24558fd8-9cdc-47de-9310-56a58108bab0" e "27163581-9aca-212a-782a-213612639abc" refere-se à entrada direcional da linhagem e "guid": "e33c694a-2c4f-4cae-8c27-06f6f6f60000" refere-se à saída direcional da linhagem, que era um recurso existente digitalizado automaticamente pelo Purview. Acabámos de criar a linhagem entre os dois recursos.

Observação

Se os recursos ainda não existirem, terá de executar a API de criação de Entidades em Massa antes deste passo para criar essas entidades antes de criar a relação de linhagem. O processo de criação de entidades em massa com o fragmento de código POST /entity/bulk API e Python é descrito no passo A.

Resultados do Cenário

A Resposta da API "201 Criado" indica que a criação de ligações de gráficos de linhagem com êxito e os GUIDs criados estão contidos no JSON de saída. A linhagem é apresentada no portal do Microsoft Purview:

  • Cenário A: linhagem personalizada criada a partir de recursos criados através da API:

    Captura de ecrã a mostrar o Cenário A: Linhagem Personalizada Compilada a partir de recursos criados através da API.

  • Cenário B: linhagem personalizada criada a partir de recursos pré-existentes ligados através da API.

    Observação

    Se a linhagem for criada a partir de entidades pré-existentes, observe que o gráfico de linhagem pré-existente permanece intacto e a nova ligação é criada e apresentada adicionalmente.

    Captura de ecrã a mostrar o Cenário B: Linhagem Personalizada Compilada a partir de recursos pré-existentes ligados através da API.