Run the object-tagging command to manage object tags - Object Storage Service

Object Storage Service (OSS) allows you to use tags to classify objects. You can manage objects that have the same tag. For example, you can specify the validity period of the objects or convert the storage class of the objects that have the same tag. You can run the object-tagging command to add, modify, query, or delete object tags.

Usage notes

To add or modify an object tag, you must have the oss:PutObjectTagging permission. To query object tags, you must have the oss:GetObjectTagging permission. To delete an object tag, you must have the oss:DeleteObjectTagging permission. For more information, see Attach a custom policy to a RAM user.

For ossutil 1.6.16 and later, you can directly use ossutil as the binary name in the command line. You do not need to update the binary name based on the operating system. For ossutil earlier than 1.6.16, you need to update the binary name based on the operating system. For more information, see ossutil command reference.
For more information about object tags, see Add tags to an object.

Command syntax

ossutil object-tagging oss://bucketname[/prefix][key#value]
--method <value>
[--encoding-type <value>]
[-r, --recursive]
[--payer <value>]
[--version-id <value>]

The following table describes the parameters and options in the syntax.

Parameter/Option	Description
bucketname	The name of the bucket.
prefix	The prefix in the names of resources, such as directories and objects.
key	The key of the tag. A tag is a key-value pair. You can add up to 10 tags to each object. The tags of the same object must have unique tag keys. The key of a tag must comply with the following requirements: The key of a tag is up to 128 characters in length and is case-sensitive. The key of a tag can contain letters, digits, spaces, and the following special characters: +=._:/
value	The value of the tag. The value of a tag must comply with the following requirements: The value of a tag is up to 256 characters in length and is case-sensitive. The value of a tag can contain letters, digits, spaces, and the following special characters: +=._:/
--method	The type of the request. Valid values: put: adds tags to an object or modifies the tags of an object. get: queries the tags of an object. delete: deletes the tags of an object.
--encoding-type	The method used to encode the prefix that follows `oss://bucket_name`. Valid value: url. If you do not specify this option, the prefix is not encoded.
-r, --recursive	If you specify this option in the command, ossutil configures tagging for all objects whose names contain the prefix specified by the prefix parameter. If you do not specify this option in the command, ossutil configures tagging only for the specified object.
--version-id	The version ID of the object. This parameter applies only to a versioning-enabled or versioning-suspended bucket.
--payer	The payer of the request. If you want the requester who accesses the resources in the specified path to pay the fees that are generated by the operation, such as traffic and request fees, set this parameter to requester.

Add or modify object tags

Only the owner of a bucket and RAM users that have the PutObjectTagging permission can add tags to objects in the bucket or modify the tags of objects in the bucket.

The following examples show how to add and modify tags of an object:

Important

If the specified object does not have a tag that has the same key as the one specified in the command, the tag is added to the object. If the specified object has an existing tag that has the same key as the one specified in the command, the existing tag is overwritten.

You can run the following command to configure a tag whose key is tagkey and whose value is tagvalue for an object named exampleobject.txt in a bucket named examplebucket:
```
ossutil object-tagging --method put oss://examplebucket/exampleobject.txt tagkey#tagvalue
```
You can run the following command to configure the following tags for an object named exampleobject.png in a bucket named examplebucket: tagkey1#tagvalue1 and tagkey2#tagvalue2.
```
ossutil object-tagging --method put oss://examplebucket/exampleobject.txt tagkey1#tagvalue1 tagkey2#tagvalue2
```
You can run the following command to configure the following tags for objects whose names contain the "test" prefix in a bucket named examplebucket: tagkey3#tagvalue3, tagkey4#tagvalue4, and tagkey5#tagvalue5.
```
ossutil object-tagging --method put oss://examplebucket/test -r tagkey3#tagvalue3 tagkey4#tagvalue4 tagkey5#tagvalue5
```
You can run the following command to configure a tag whose key is tagkey6 and whose value is tagvalue6 for the specified version of an object named exampleobject.txt in a bucket named examplebucket:
```
ossutil object-tagging --method put oss://examplebucket/exampleobject.txt tagkey6#tagvalue6 --version-id CAEQARiBgID8rumR2hYiIGUyOTAyZGY2MzU5MjQ5ZjlhYzQzZjNlYTAyZDE3****
```
For more information about how to list all versions of an object, see Is.
After the preceding sample commands are successful, the following similar output is returned to indicate the time used to configure tagging:
```
0.106852(s) elapsed
```

Query object tags

Only the owner of a bucket and RAM users that have the GetObjectTagging permission can query the tags of objects in the bucket.

The following examples show how to query the tags of objects:

Query the tags of an object

You can run the following command to query the tags of an object named exampleobject.txt in a bucket named examplebucket:

ossutil object-tagging --method get oss://examplebucket/exampleobject.txt

The following output shows that exampleobject.txt has a tag whose key is tagkey and whose value is tagvalue.

object index   tag index      tag key   tag value       object
---------------------------------------------------------------------------
1              0              "tagkey"  "tagvalue"      oss://examplebucket/exampleobject.txt

0.068156(s) elapsed

Query the tags of multiple objects

You can run the following command to query the tags of all objects whose names contain the "test" prefix in a bucket named examplebucket:

ossutil object-tagging --method get oss://examplebucket/test -r

The following output shows that objects whose names contain the "test" prefix have the following tags: tagkey3#tagvalue3, tagkey4#tagvalue4, and tagkey5#tagvalue5.

object index   tag index      tag key   tag value       object
---------------------------------------------------------------------------
1              0              "tagkey3" "tagvalue3"     oss://examplebucket/test
1              1              "tagkey4" "tagvalue4"     oss://examplebucket/test
1              2              "tagkey5" "tagvalue5"     oss://examplebucket/test

0.093040(s) elapsed

Delete object tags

Only the owner of a bucket and RAM users that have the DeleteObjectTagging permission can delete the tags of objects in the bucket.

The following examples show how to delete the tags of objects:

Delete the tags of an object
You can run the following command to delete the tags of an object named exampleobject.txt in a bucket named examplebucket:
```
ossutil object-tagging --method delete oss://examplebucket/exampleobject.txt
```
Delete the tags of multiple objects
You can run the following command to delete the tags of all objects whose names contain the "test" prefix in a bucket named examplebucket:
```
ossutil object-tagging --method delete oss://examplebucket/test -r
```
If the preceding commands are successful, output similar to the following result is returned to indicate the time used to delete tags:
```
0.148970(s) elapsed
```

Common options

If you use ossutil to switch to a bucket that is located in another region, add the -e option to the command to specify the endpoint of the region in which the specified bucket is located. If you use ossutil to switch to a bucket that belongs to another Alibaba Cloud account, add the -i option to the command to specify the AccessKey ID of the specified account, and add the -k option to the command to specify the AccessKey secret of the specified account.

For example, you can run the following command to configure a tag whose key is tagkey7 and whose value is tagvalue7 for an object named example.png in a bucket named testbucket, which is located in the China (Shanghai) region and owned by another Alibaba Cloud account:

ossutil object-tagging --method put oss://testbucket/exampletest.png tagkey7#tagvalue7 -e oss-cn-shanghai.aliyuncs.com -i LTAI4Fw2NbDUCV8zYUzA****  -k 67DLVBkH7EamOjy2W5RVAHUY9H****

For more information about common options, see Common options.