SAS Viya 3.4: Update a Tag Name (Annotations REST API)
In SAS Viya 3.4, you can use tags to add extra information beyond simple metadata to tables, columns, and other objects. In the user interface, these tags can be added to columns automatically when profiling the data or manually added. At this time in the user interface, you can add a new tag name, but there is not currently a way to perform the following actions:
- Search for items that have a designated tag
- Update an existing tag name
- Delete an existing tag name.
However, these actions are available using the Annotations REST API service.
I will demonstrate how the three actions listed above can be performed using the Annotations REST API service in a 3-part series. My previous article covered the first item – search for items that have a designated tag. This entry will focus on how you can update an existing tag name using the Annotations REST API.
Before using the Annotations REST API service, you must first obtain and OAuth token. For more information on this, you can read the following articles:
- Authentication to SAS Viya: a couple of approaches
- Introducing Python-based command-line tools for SAS Viya by Gerry Nelson
Note: Make sure the username you use to retrieve the OAuth token has the necessary permissions to run any of the REST APIs you want to execute.
Once you have your OAuth token, you can then use the Annotation REST API service. In my case, I want to change the tag name from Demo2 to Demo2_Update. First, I need to make a call to search for annotation (tag) with the name of Demo2 to get its ID information by using this call:
GET http://sasviya01.race.sas.com/annotations/annotations/?filter=eq(name,'Demo2')
Header: Content-Type=application/vnd.sas.annotation+json
Header: Accept=application/vnd.sas.collection+json
Header: Authorization= Bearer <ReplaceWithOAuthToken>
Select any image to see a larger version.
Note: You can use many different tools to perform REST API calls. For my demonstration, I am using a tool called Postman.
This returns the following results:
Note: c2a28476-d82a-4ec9-af55-de063cc4d720 is the Annotation ID for the Demo2 tag name.
Now that I have the ID for the tag with name of Demo2, I need to make a call to get its eTag information. The eTag is used to identify the specific version of the tag entry, so it can be updated. This is the call I need to make to get the eTag information for the Demo2 tag:
GET http://sasviya01.race.sas.com/annotations/annotations/c2a28476-d82a-4ec9-af55-de063cc4d720
Header: Content-Type=application/vnd.sas.annotation+json
Header: Accept=application/vnd.sas.annotation+json
Header: Authorization= Bearer <ReplaceWithOAuthToken>
This returns the following results:
The eTag information is in the Headers section of the returned results.
Note: "jqpaybnl" is the eTag for the current version of the Demo2 tag.
Now that I have both the Annotation ID and the eTag information for the Demo2 tag, I can make the call to update its name by using this call:
PUT http://sasviya01.race.sas.com/annotations/annotations/c2a28476-d82a-4ec9-af55-de063cc4d720
Header: Content-Type=application/vnd.sas.annotation+json
Header: Accept=application/vnd.sas.annotation+json
Header: Authorization= Bearer <ReplaceWithOAuthToken>
If-Match: "jqpaybnl"
With the following Body information in the request:
{
"id": "c2a28476-d82a-4ec9-af55-de063cc4d720",
"domain": "SAS.COMMON.TAG",
"name": "Demo2_Update",
"label": "Demo2_Update",
"description": "Updated Tag Name"
}
This returns the following results:
The tag name has now been changed to Demo2_Update. I submit the following request to return all tag names that contain the word "Demo":
GET http://sasviya01.race.sas.com/annotations/annotations/?filter=contains(name,'Demo')
Header: Content-Type=application/vnd.sas.annotation+json
Header: Accept=application/vnd.sas.collection+json
The results returned now show that the two tag names containing the word "Demo" are Demo1 and Demo2_Update.
This concludes the demonstration on how to update an existing tag name using the Annotations REST API. In my next article in this series, I will explore using the Annotations REST API to delete an existing tag name.
For more information on working with tags (annotations) using REST API, you can refer to the documentation.
