How to use the set-props command to set object properties - Object Storage Service

The set-props command sets object properties, including access permissions, storage classes, metadata, and tags.

Precautions

The set-props command calls different API operations depending on the object property that you modify. Ensure that you have the required permissions. For example, calling the PutObjectAcl API operation requires the oss:PutObjectAcl permission. The specific API operations that are called are as follows:

To modify only the object access control list (ACL): The command calls the PutObjectAcl API operation.
To modify only the object tags: The command calls the PutObjectTagging API operation. If the tag modification instruction involves updating existing tags, such as an incremental addition, the system first calls the GetObjectTagging API operation to retrieve the original tags.
To modify the object storage class or metadata: This operation rewrites the object. The command calls the CopyObject API operation or uses the multipart copy flow (InitiateMultipartUpload -> UploadPartCopy -> CompleteMultipartUpload).
To modify multiple properties at the same time: The command selects the most efficient combination of API operations. For example:
- To modify both object permissions and tags: The command calls PutObjectAcl and PutObjectTagging.
- To modify both object permissions and storage class: The command directly calls the CopyObject API operation or the multipart copy API operations (InitiateMultipartUpload -> UploadPartCopy -> CompleteMultipartUpload) to update the permissions and storage class at the same time.

Note

Changing an object's storage class incurs PUT request fees:

For objects no larger than the threshold specified by --bigfile-threshold, ossutil calls CopyObject. The request is billed based on the source object's storage class.
For objects larger than the threshold, ossutil uses multipart copy. Each part calls UploadPartCopy. The request is billed based on the destination object's storage class.
Converting many objects to Deep Cold Archive can incur high PUT request fees. Increase --bigfile-threshold or --part-size to reduce UploadPartCopy requests. When you change an object's storage class, CopyObject supports objects no larger than 1 GB.

For billing rules, see Request fees. For billing and usage guidance for Deep Cold Archive, see Best practices for using Deep Cold Archive.

Command format

ossutil set-props oss://bucket[/prefix] [flags]

Parameter	Type	Description
--acl	string	The access control list (ACL) of the object. Valid values: private: private. public-read: public-read. public-read-write: Public read and write access. default: inherits from the bucket.
--bigfile-threshold	SizeSuffix	The object size threshold for multipart upload, download, or copy. Objects larger than the threshold use multipart copy. Default value: 100 MiB. Supported suffixes: B, K, M, G, T, and P.
--cache-control	string	Specifies the web page caching behavior when the object is downloaded.
--content-disposition	string	Specifies how the object is displayed.
--content-encoding	string	Specifies the encoding format of the object.
--content-type	string	The content type of the object.
-d, --dirs	/	Returns the files and subdirectories in the current directory. It does not recursively display all files in all subdirectories.
--encoding-type	string	The encoding type of the input object name or file name. Valid value: url.
--end-with	string	Sorts objects alphabetically and returns objects that are before or at the specified value.
--exclude	stringArray	The rules to exclude paths or file names.
--exclude-from	stringArray	Reads exclusion rules from a rule file.
--expires	string	Specifies the absolute expiration time for the cached content.
--files-from	stringArray	Reads a list of source file names from a file. Empty lines or commented lines are ignored.
--files-from-raw	stringArray	Reads a list of source file names from a file.
--filter	stringArray	The rules to filter paths or file names.
--filter-from	stringArray	Reads filtering rules from a rule file.
-f, --force	/	Forces the operation without a confirmation prompt.
--include	stringArray	The rules to include paths or file names.
--include-from	stringArray	Reads inclusion rules from a rule file.
-j, --job	int	The number of concurrent tasks. The default value is 3. Important This parameter takes effect only when you specify the `-f`, `--update`, `--size-only`, or `--ignore-existing` parameter.
--list-objects	/	Uses the ListObjects API operation to list objects.
--max-size	SizeSuffix	The maximum size of a file to transfer. The default unit is byte. You can use a suffix: B, K, M, G, T, or P. 1 K (KiB) = 1024 B.
--metadata	strings	Specifies the user metadata of the object in the key=value format. Example: --metadata test=value,test1=value1.
--metadata-directive	string	The instruction to modify metadata. Valid values: replace: Retains only the metadata specified in the command line options. update: Takes the union of the metadata in the command line and the metadata of the object. purge: Clears all metadata. delete: Deletes the metadata specified in the command line options and retains the rest.
--metadata-exclude	stringArray	The rules to exclude object metadata.
--metadata-filter	stringArray	The rules to filter object metadata.
--metadata-filter-from	stringArray	Reads object metadata filtering rules from a rule file.
--metadata-include	stringArray	The rules to include object metadata.
--min-age	Duration	Sets properties only for files modified before the specified time interval. The default unit is second. You can use a unit suffix, such as 1h for 1 hour. Note `--min-age 1h` sets properties only for files modified 1 hour ago or earlier.
--max-age	Duration	Sets properties only for files modified within the specified time interval. The default unit is second. You can use a unit suffix, such as 1h for 1 hour. Note `--max-age 1h` sets properties only for files modified within the last hour.
--min-mtime	Time	Sets properties only for files modified after the specified time. The time must be in UTC format. For example, 2006-01-02T15:04:05. Note `--min-mtime "2006-01-02T15:04:05"` sets properties only for files modified after 15:04:05 UTC on January 2, 2006.
--max-mtime	Time	Sets properties only for files modified before the specified time. The time must be in UTC format. For example, 2006-01-02T15:04:05.
--min-size	SizeSuffix	The minimum size of a file to transfer. The default unit is byte. You can use a suffix: B, K, M, G, T, or P. 1 K (KiB) = 1024 B.
--no-progress	/	Does not display the progress bar.
--page-size	int	The maximum number of objects to list on each page during batch processing. The default value is 1000. The value can range from 1 to 1000.
--parallel	int	The number of concurrent tasks for operations on a single file.
--part-size	SizeSuffix	The part size. By default, ossutil calculates the part size based on the object size. Larger parts reduce the number of `UploadPartCopy` requests. Valid range: 100 KiB to 5 GiB.
-r, --recursive	/	Performs the operation recursively. When you specify this option, the command is applied to all matching objects in the bucket. Otherwise, the command is applied only to the object specified by the path.
--request-payer	string	The payment method for the request. Set this parameter if you use the pay-by-requester mode. Valid value: requester.
--start-after	string	Sorts objects alphabetically and returns objects that are after the specified value.
--storage-class	string	The storage class of the object. Valid values: Standard: Standard. IA: Infrequent Access. Archive: Archive Storage. ColdArchive: Cold Archive. DeepColdArchive: Deep Cold Archive.
--tagging	strings	Specifies the tags of the object in the key=value format. Example: --tagging tag1=value1,tag2=value2.
--tagging-directive	string	The instruction to modify tags. Valid values: replace: Retains only the tags specified in the command line options. update: Takes the union of the tags in the command line and the tags of the object. purge: Clears all tags. delete: Deletes the tags specified in the command line options and retains the rest.
--version-id	string	The version ID of the object.
--list-format	string	The format of the list file. Valid values: plain, inventory.
--list-manifest-from	string	Reads the description of the list file format from a file. This parameter is required when the list file format is `inventory`.

For more information, see Command-line options.

Examples

Set the access permissions of an object to private.

ossutil set-props oss://examplebucket/exampleobject.txt --acl private

Set the storage class of an object to Archive Storage.

ossutil set-props oss://examplebucket/exampleobject.txt --storage-class Archive

Convert objects to Deep Cold Archive in batches and estimate PUT request fees.

For objects no larger than 1 GB, increase the multipart threshold to use CopyObject. The following example sets the threshold to 1 GB:
```
ossutil set-props oss://examplebucket/exampledir/ --storage-class DeepColdArchive --bigfile-threshold 1G -r
```
Objects larger than 1 GB require multipart copy. Increase the part size to reduce UploadPartCopy requests. The following example sets the part size to 1 GiB:
```
ossutil set-props oss://examplebucket/exampledir/ --storage-class DeepColdArchive --part-size 1G -r
```
Estimate the number of UploadPartCopy requests with the following formulas:
```
Parts per object = ceil(object size / part size)
UploadPartCopy requests = number of objects × parts per object
```
For example, converting 1000 objects of 10 GiB each with --part-size 1G generates 10 UploadPartCopy requests per object and 10000 requests in total. UploadPartCopy is billed based on the destination object's storage class. Therefore, estimate this portion of the fee based on the billing rules for Deep Cold Archive PUT requests. Multipart copy also calls InitiateMultipartUpload and CompleteMultipartUpload. Object listing and retries may also incur request fees.

For objects that have the .txt extension, change the content-type to text/plain.

ossutil set-props oss://bucket/prefix --content-type text/plain --include "*.txt" --metadata-directive update -r

Set the tags of an object.

ossutil set-props oss://examplebucket/exampleobject.txt --tagging tag1=value1 --tagging-directive update

Set object properties from a list file.
Note
Each line in the list file represents an object and uses the OSS path format `oss://{bucket}/{key}`. For example, the list.txt file contains the following content:
```
oss://examplebucket/key1
oss://examplebucket/key2
```
```
ossutil set-props list://list.txt 
```
Set object properties from a manifest file.

Note
After you run an inventory task, a `csv.gz` file and a `manifest.json` file are generated in the inventory results. You need to use these two files to set object properties from a manifest file.
```
ossutil set-props list://ca8007fc-4123-493e-9a01-dd1511fbac54.csv.gz --list-format inventory --list-manifest-from manifest.json
```