Tutorial: Atlas 2.2 new functionality

In this tutorial, learn to programmatically interact with new Atlas 2.2 APIs with the data map in Microsoft Purview.

Prerequisites

Business metadata APIs

Business metadata is a template that contains custom attributes (key values). You can create these attributes globally and then apply them across multiple typedefs.

Atlas endpoint

For all the requests, you'll need the Atlas endpoint for your Microsoft Purview account.

  1. Find your Microsoft Purview account in the Azure portal
  2. Select the Properties page on the left side menu
  3. Copy the Atlas endpoint value

Screenshot of the properties page for Microsoft Purview with the Atlas endpoint box highlighted.

Create business metadata with attributes

You can send a POST request to the following endpoint:

POST {{endpoint}}/api/atlas/v2/types/typedefs

Tip

The applicableEntityTypes property tells which data types the metadata will be applied to.

Sample JSON:

   {
  "businessMetadataDefs": [
    {
      "category": "BUSINESS_METADATA",
      "createdBy": "admin",
      "updatedBy": "admin",
      "version": 1,
      "typeVersion": "1.1",
      "name": "<Name of Business Metadata>",
      "description": "",
      "attributeDefs": [
        {
          "name": "<Attribute Name>",
          "typeName": "string",
          "isOptional": true,
          "cardinality": "SINGLE",
          "isUnique": false,
          "isIndexable": true,
          "options": {
            "maxStrLength": "50",
            "applicableEntityTypes": "[\"Referenceable\"]"
          }          
        }
      ]
    }
  ]
}

Add or update an attribute to existing business metadata

You can send a PUT request to the following endpoint:

PUT {{endpoint}}/api/atlas/v2/types/typedefs

Sample JSON:

   {
  "businessMetadataDefs": [
    {
      "category": "BUSINESS_METADATA",
      "createdBy": "admin",
      "updatedBy": "admin",
      "version": 1,
      "typeVersion": "1.1",
      "name": "<Name of Business Metadata>",
      "description": "",
      "attributeDefs": [
        {
          "name": "<Attribute Name>",
          "typeName": "string",
          "isOptional": true,
          "cardinality": "SINGLE",
          "isUnique": false,
          "isIndexable": true,
          "options": {
            "maxStrLength": "500",
            "applicableEntityTypes": "[\"Referenceable\"]"
          }          
        },
        {
          "name": "<Attribute Name 2>",
          "typeName": "int",
          "isOptional": true,
          "cardinality": "SINGLE",
          "isUnique": false,
          "isIndexable": true,
          "options": {
            "applicableEntityTypes": "[\"Referenceable\"]"
          }          
        }
      ]
    }
  ]
}

Get a business metadata definition

You can send a GET request to the following endpoint:

GET {endpoint}}/api/atlas/v2/types/typedef/name/{{Business Metadata Name}}

Set a business metadata attribute to an entity

You can send a POST request to the following endpoint:

POST {{endpoint}}/api/atlas/v2/entity/guid/{{GUID}}/businessmetadata?isOverwrite=true

Sample JSON:

{
  "myBizMetaData1": {
        "bizAttr1": "I am myBizMetaData1.bizAttr1",
        "bizAttr2": 123,
  }
 }

Delete a business metadata attribute from an entity

You can send a DELETE request to the following endpoint:

'DELETE' {{endpoint}}/api/atlas/v2/entity/guid/{{GUID}}/businessmetadata?isOverwrite=true

Sample JSON:

{
  "myBizMetaData1": {
    "bizAttr1": ""    
  }
}

Delete a business metadata type definition

You can send a DELETE request to the following endpoint:

DELETE {{endpoint}}/api/atlas/v2/types/typedef/name/{{Business Metadata Name}}

Custom attribute APIs

Custom attributes are key/value pairs that can be directly added to an Atlas entity.

Set a custom attribute to an entity

You can send a POST request to the following endpoint:

POST {{endpoint}}/api/atlas/v2/entity

Sample JSON:

{
    "entity": {
        "typeName": "azure_datalake_gen2_path",
        "attributes": {
           
            "qualifiedName": "<FQN of the asset>",
            "name": "data6.csv"
        },
        "guid": "3ffb28ff-138f-419e-84ba-348b0165e9e0",
        "customAttributes": {
            "custAttr1": "attr1",
            "custAttr2": "attr2"
        }
    }
}

Label APIs

Labels are free text tags that can be applied to any Atlas entity.

Set labels to an entity

You can send a POST request to the following endpoint:

POST {{endpoint}}/api/atlas/v2/entity/guid/{{GUID}}/labels

Sample JSON:

[
  "label1",
  "label2"
]

Delete labels to an entity

You can send a DELETE request to the following endpoint:

DELETE {{endpoint}}/api/atlas/v2/entity/guid/{{GUID}}/labels

Sample JSON:

[
  "label2"
]

Next steps