Tagging objects in IBM Cloud Object Storage

Tagging Objects

Managing tags describing your objects can be performed through various interfaces and architectures. Using the Console provides a graphical user interface. Using the command line requires tools like curl and the knowledge of how it interacts with Object Storage.

Before you begin

You need:

• An IBM Cloud® Platform account
• An instance of IBM Cloud Object Storage and a bucket created for this purpose
• An IAM API key with Writer access to your Object Storage bucket or instance
• Either existing or new objects that will have tags applied to them.

Reading tags

Tags are accessible throughout an instance with the proper permissions. While the true organizational power of using tags as an organizational principle scales with you, you can access tags on an individual basis as well.

Log in to the console, selecting your instance of IBM Cloud Object Storage and your bucket where your data is represented. After you've uploaded files to your bucket, you can view and manage your tags right in place. Place the cursor over the ellipses at the end of any row representing your data (stored as an object), and select "Manage your tags" from the options in the menu.

A properly formed and authenticated "GET" request with the ?tagging query parameter is all that is required for accessing the tags for your objects using curl. The examples here use bearer tokens generated using this example. In addition to the bucket identifier and object key, you will also need the correct endpoint. The resulting XML object is also shown, where the "Tag" element will be repeated for each tag assigned to the object. If there are no tags, the response will return XML with an empty element, <TagSet />.

curl 'https://<endpoint>/<bucketname>/<objectname>?tagging' \
-H 'Authorization: bearer <token>' \

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Tagging xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <TagSet>
    <Tag>
      <Key>Example Key</Key>
      <Value>Value Example</Value>
    </Tag>
  </TagSet>
</Tagging>

Of course, before tags can be viewed they must be created, which we will turn to next.

Creating tags

Tags must comply with the following restrictions:

• An object can have a maximum of 10 tags
• For each object, each tag key must be unique, and each tag key can have only one value.
• Minimum key length - 1 Unicode characters in UTF-8
• Maximum key length - 128 Unicode characters in UTF-8
• Maximum key byte size - 256 bytes
• Minimum value length - 0 Unicode characters in UTF-8 (Tag Value can be empty)
• Maximum value length - 256 Unicode characters in UTF-8
• Maximum value byte size - 512 bytes
• A Tag key and value may consist of US Alpha Numeric Characters (a-zA-Z0-9), and spaces representable in UTF-8, and the following symbols: _, ., *, `, -, :
• Tag keys and values are case-sensitive
• ibm: cannot be used as a key prefix for tags

As noted previously, log in to your instance and navigate to the bucket and object you wish to "tag." In the panel that appears when you select "Manage your tags", start by clicking on the "Add tags +" button. Then, you can add tags by typing text into the key and value fields as desired. Add more tags one at a time, by repeating the steps you've just completed.

If you do not click on "save" when completing your changes, a dialog box will remind you of the consequences. That is, changes are discarded unless saved.

As noted previously, you will have to authenticate to add tags to your data. If you have questions about bearer tokens, see this example. Again, note the query string for working with tags: ?tagging.

curl -X "PUT" 'https://<endpoint>/<bucketname>/<objectname>?tagging' \
-H 'Authorization: bearer <token>' \
-H "content-type: text/plain" \
--data "<Tagging><TagSet><Tag><Key>your key</Key><Value>your text</Value></Tag></TagSet></Tagging>"

The example describes as shown a tag with a key of 'source' and a value of 'text' in the XML sent as data in the body of the request. The schema of the XML has to validate upon execution. If you want to add multiple tags, duplicate the 'Tag' node and modify the content of each key and value element to your specifications. There is only one 'TagSet' element for each object, and the 'PUT' command will replace any existing metadata with the values you specified.

curl -X "PUT" "https://s3.test.cloud-object-storage.sample.appdomain.cloud/taggingtest/example-file.csv?tagging" -H "Authorization: bearer ...iOiIyMDIwMTIwNzE0NDkiLCJh..." -H "ibm-service-instance-id: 7nnnnn52-2nn0-nna9-bann-7nnnnn4cc4e7" --data "<Tagging><TagSet><Tag><Key>source</Key><Value>text</Value></Tag></TagSet></Tagging>"

Editing tags

Once your objects have been tagged, over time it may become necessary to modify them.

To edit the tags using the graphic interface, you will have to log into the console and access your objects as described previously. Once you've clicked on the "Manage Tags" option, simply change the contents of the form fields. Remember to press "Save" when complete.

Your requests must be authenticated to tag your data. Also, you will have to programmatically keep any old tags while updating your objects with new information. The example shown repeats the tags from the previous examples while adding a new tag.

Remember that performing "PUT" operations involving tags will overwrite any current tags.

curl -X "PUT" 'https://<endpoint>/<bucketname>/<objectname>?tagging' \
-H 'Authorization: bearer <token>' \
-H "content-type: text/plain" \
--data "<Tagging><TagSet><Tag><Key>source</Key><Value>text</Value></Tag><Tag><Key>source1</Key><Value>text1</Value></Tag></TagSet></Tagging>"

Removing tags

After you have added tags to your objects, it may become necessary to remove them.

To delete the tags using the graphic interface, you will have to log into the console and access your objects as previously described. Again, click on the "Manage tags" option, and in the panel that appears, choose either to "delete all" or delete one tag at a time by clicking on the "trash can" icon in the same row as the tag.

Remember to press "Save" when complete.

You will have to authenticate to delete tags from your data. Simply use the "DELETE" HTTP method with the ?tagging query parameter to delete all tags. If you wish to delete one or more tags while simultaneously keeping one or more tags, use the "edit" instructions to make your changes.

curl -X "DELETE" 'https://<endpoint>/<bucketname>/<objectname>?tagging' \
-H 'Authorization: bearer <token>' \
-H "content-type: text/plain"