Add a facade method on PurviewClient to support updating and deleting…

… entity tags

a.k.a. labels.

Added sample for creating Purview Tags.

Closes #245

pyapacheatlas/core/client.py

@@ -1729,3 +1729,61 @@ def upload_term(self, term, includeTermHierarchy=True, **kwargs):
             "PurviewClient.glossary.upload_term instead.")
         results = self.glossary.upload_term(term, includeTermHierarchy)
         return results
+
+    def update_entity_tags(self, tags, guid=None, typeName=None, qualifiedName=None, force_update=False):
+        """
+        Update the given tags for one entity. Provide a list of strings that
+        should be added. You can either provide the guid of the entity or
+        the typeName and qualifiedName of the entity. By using force_update
+        set to True you will overwrite the existing entity. force_update
+        set to False will append to the existing entity.
+
+        Note: This is a facade over `update_entity_labels` as MSFT Purview's
+        UI refers to labels as 'tags'.
+
+        :param list(str) tags: The tag(s) that should be appended or set.
+        :param str guid:
+            The guid of the entity to be updated. Optional if using typeName
+            and qualifiedName.
+        :param str typeName:
+            The type name of the entity to be updated. Must also use
+            qualifiedname with typeName. Not used if guid is provided.
+        :param str qualifiedName:
+            The qualified name of the entity to be updated. Must also use
+            typeName with qualifiedName. Not used if guid is provided.
+        :return:
+            A dict containing a message indicating success. Otherwise
+            it will raise an AtlasException.
+        :rtype: dict(str, str)
+        """
+        return super().update_entity_labels(tags, guid, typeName, qualifiedName, force_update)
+
+    def delete_entity_tags(self, tags, guid=None, typeName=None, qualifiedName=None):
+        """
+        Delete the given tags for one entity. Provide a list of strings that
+        should be removed. You can either provide the guid of the entity or
+        the typeName and qualifiedName of the entity.
+
+        If you want to clear out an entity without knowing all the tags, you
+        should consider `update_entity_tags` instead and set
+        force_update to True.
+
+        Note: This is a facade over `delete_entity_labels` as MSFT Purview's
+        UI refers to labels as 'tags'.
+
+        :param list(str) labels: The label(s) that should be removed.
+        :param str guid:
+            The guid of the entity to be updated. Optional if using typeName
+            and qualifiedName.
+        :param str typeName:
+            The type name of the entity to be updated. Must also use
+            qualifiedname with typeName. Not used if guid is provided.
+        :param str qualifiedName:
+            The qualified name of the entity to be updated. Must also use
+            typeName with qualifiedName. Not used if guid is provided.
+        :return:
+            A dict containing a message indicating success. Otherwise
+            it will raise an AtlasException.
+        :rtype: dict(str, str)
+        """
+        return super().delete_entity_labels(tags, guid, typeName, qualifiedName)

samples/CRUD/crud_purview_tags.py

@@ -0,0 +1,75 @@
+import json
+import os
+# PyApacheAtlas packages
+# Connect to Atlas via a Service Principal
+from pyapacheatlas.auth import ServicePrincipalAuthentication
+from pyapacheatlas.core import PurviewClient, AtlasEntity
+from pyapacheatlas.core.typedef import AtlasAttributeDef, AtlasStructDef, TypeCategory
+
+if __name__ == "__main__":
+    """
+    This sample demonstrates creating, updating, and deleting custom tags (a.k.a. label)
+    
+    Note that the `_tags` methods are facades over the `_labels` methods since
+    Microsoft Purview renamed labels to tags in the Microsoft Purview UI.
+    """
+    oauth = ServicePrincipalAuthentication(
+        tenant_id=os.environ.get("TENANT_ID", "YourDefaultTenantId"),
+        client_id=os.environ.get("CLIENT_ID", "YourDefaultClientId"),
+        client_secret=os.environ.get("CLIENT_SECRET", "YourDefaultClientSecretValue")
+    )
+    client = PurviewClient(
+        account_name=os.environ.get("PURVIEW_NAME", "DefaultPurviewAccountName"),
+        authentication=oauth
+    )
+
+    # Create an Entity With Labels/Tags
+    # Note: Rerunning this sample with the same qualified name will not work.
+    # You can't update the labels via the /entity endpoint after the entity
+    # has been created.
+    entity = AtlasEntity(
+        name="MyTableWithTags",
+        typeName="azure_sql_table",
+        qualified_name="mssql://myserver/mydb/myschema/MyTableWithTags",
+        guid="-1",
+        labels= ["a", "b", "c"]
+    )
+    resp = client.upload_entities([entity])
+    guid = resp["guidAssignments"]["-1"]
+
+    print(json.dumps(resp,indent=2))
+    print(json.dumps(client.get_single_entity(guid),indent=2))
+
+    _ = input(">>>Press enter to continue to modifying the labels attributes")
+
+    # Append new custom labels (without overwriting)
+    resp = client.update_entity_tags(labels=['d','e'], 
+        guid=guid, 
+        force_update=False
+    )
+    print(json.dumps(resp,indent=2))
+    print(json.dumps(client.get_single_entity(guid),indent=2))
+
+    _ = input(">>>Press enter to completely overwrite the labels attributes")
+
+    #  Completely overwrite custom labels with a new set of labels
+    # by passing the force_update=True flag
+
+    resp = client.update_entity_tags(
+        labels=['j','k', 'l'], 
+        guid=guid, 
+        force_update=True
+    )
+    print(json.dumps(resp,indent=2))
+    print(json.dumps(client.get_single_entity(guid),indent=2))
+
+    _ = input(">>>Press enter to remove a subset of the label attributes")
+    # Remove one or many Custom Labels
+
+    resp = client.delete_entity_tags(labels=['j','k'], 
+        guid=guid
+    )
+    print(json.dumps(resp,indent=2))
+    print(json.dumps(client.get_single_entity(guid),indent=2))
+
+    print("Completed demonstration of adding, updating, and removing custom labels")