Updated on 2026-09-20 GMT+08:00

Adding Tags to an Object

Function

You can use this command to add tags to an object.

Constraints

To add tags to an object, you must be the object owner or have the required permission (obs:bucket:PutObjectTagging granted using IAM or PutObjectTagging granted using a bucket policy). For details, see Differences Between OBS Permissions Control Methods, Using IAM Roles or Policies to Grant Access to OBS, and Creating a Custom Bucket Policy.

Command Line Structure

Windows

Adding tags to a single object

obsutil object-tagging obs://bucket -method=put -tag key1=value1 -tag keyX=valueX [-tag keyN=valueN] [-versionId=xxx] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]

Adding tags to a set of objects

obsutil object-tagging obs://bucket -method=put -r [-f] [-v] -tag key1=value1 -tag keyX=valueX [-o=xxx] [-j=1] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]

macOS or Linux

Adding tags to a single object

./obsutil object-tagging obs://bucket -method=put -tag key1=value1 -tag keyX=valueX [-tag keyN=valueN] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]

Adding tags to a set of objects

./obsutil object-tagging obs://bucket -method=put -r [-f] [-v] -tag key1=value1 -tag keyX=valueX [-o=xxx] [-j=1] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]

Examples

In Windows, run obsutil object-tagging obs://test-bucket/key -method=put -tag key1=value1 -tag key2=value2 to add tags (the key1/value1 and key2/value2 pairs) to the key object in bucket test-bucket.

obsutil object-tagging obs://test-bucket/key -method=put -tag key1=value1 -tag key2=value2 

Start at 2024-09-30 07:59:28.8675681 +0000 UTC

Put tagging object [key] in the bucket [test-bucket] successfully, cost [570] ms, request id [0000019AB61D183F40171C3A0980ACD3]

Parameter Description

Parameter	Optional or Mandatory	Description
bucket	Mandatory	The bucket name
key	Optional	The name or name prefix of the objects to which you want to add tags
method	Mandatory	The method. Set it to put when you add tags to an object.
tag	Mandatory	The object tag as a key-value pair in the key=value format.
versionId	Optional (additional parameter)	The object version ID you can specify when adding tags to a single object
r	Mandatory for matching a set of objects (additional parameter)	Matches a set of objects based on the specified object name prefix.
f	Optional for matching a set of objects (additional parameter)	Performs operations without asking for confirmation.
j	Optional for matching a set of objects (additional parameter)	The maximum number of concurrent tasks for setting object tags in batches. The default value is the value of defaultJobs in the configuration file. NOTE: The tool ensures that this value is at least 1.
o	Optional (additional parameter)	The folder that stores the result files. After the command finishes, the folder will contain the result files (which may include both a success file and a failure file). By default, this folder is .obsutil_output, a subfolder under the home directory of the user who runs the obsutil command. NOTE: A result file should be named as follows: rm_{succeed\| failed}_report_Time_TaskId.txt. By default, the maximum size of a single result file is 30 MB and up to 1,024 result files can be retained. You can modify these limits by configuring recordMaxLogSize and recordBackups in the configuration file. If there are multiple folders and files and you need to confirm the details of a failed task, refer to the failure result file cp_failed_report_Time_TaskId.txt in the result folder and the log files in the log path.
config	Optional (additional parameter)	The user-defined configuration file for executing the current command. For details about parameters that can be configured, see Configuration Parameters.
e	Optional (additional parameter)	The endpoint
i	Optional (additional parameter)	The user's AK
k	Optional (additional parameter)	The user's SK
t	Optional (additional parameter)	The user's security token

Helpful Links

For details about the API for adding object tags, see Adding Object Tags.
For details about the meanings, causes, and handling methods of error codes that may be returned during the operation, see OBS Error Codes.

Parent topic: Object Commands