Object Storage Service (OSS) uses object metadata to describe object attributes. Object metadata includes standard HTTP headers and user metadata. HTTP headers can be used to specify custom policies for HTTP requests, and user metadata can be used to identify the purposes or attributes of objects. You can run the set-meta command to configure, modify, or delete the metadata of uploaded objects.
Sample command lines in this topic are based on the 64-bit Linux system. For other systems, replace ./ossutil64 in the commands with the corresponding binary name. For more information, see ossutil.
After you configure or update object metadata by running the set-meta command, you can run the stat command to view object metadata. For more information, see stat.
Command syntax
./ossutil64 set-meta oss://bucketname[/prefix]
[header:value#header:value...]
[--update]
[--delete]
[-r, --recursive]
[-f, --force]
[--object-file, <value>]
[--snapshot-path, <value>]
[--disable-ignore-error]
[--version <value>]
[--include <value>]
[--exclude <value>]
The following table describes the options that you can configure to run the set-meta command.
Option | Description |
bucketname | The name of the bucket in which the objects whose metadata you want to manage are stored. |
prefix | The resources stored in the bucket, such as directories and objects. |
header:value#header:value... | The key-value pairs that are used to identify object metadata. Headers are not case-sensitive, whereas values are case-sensitive. If you want to configure multiple sets of metadata, separate the sets of metadata with number signs (#). Example: You can configure the following headers:
For more information about how to use headers, see Manage object metadata. |
--update | Updates object metadata. This option can be shortened to -u and cannot be used together with --delete. |
--delete | Deletes object metadata. This option cannot be used together with --update. |
-r, --recursive | Specifies the objects for which you can configure metadata. If you specify this option, ossutil configures the metadata for all objects whose names contain a specific prefix in the bucket. If you do not specify this option, ossutil configures the metadata only for a specific object. |
-f, --force | Specifies that the operation is forcibly performed. The operation is performed without a prompt for confirmation. |
--object-file | Configures, updates, or deletes the metadata of multiple objects at a time. To use this option, perform the following steps:
Note If an error occurs when one of the objects is being restored, ossutil records the error information about the object in the report file and configures the metadata of other objects. Information about the objects whose metadata is configured, updated, or deleted is not recorded in the report file. |
--snapshot-path | The snapshots that are generated. If you specify this option, ossutil generates snapshots only for the objects that are involved in this operation. If snapshots have already been generated for the objects that are involved in this operation, this operation is ignored. Note This option must be used together with the -r, --recursive or --object-file option. |
--disable-ignore-error | Specifies that errors are not ignored during batch operations. |
--version-id | The version ID of the object whose metadata you want to manage. This option applies only to objects in buckets for which versioning is enabled or suspended. |
--include | Specifies that the command applies to all objects that meet the specified conditions. For more information, see set-meta (manage object metadata). |
--exclude | Specifies that the command applies to all objects that do not meet the specified conditions. For more information, see set-meta (manage object metadata). |
Configure or update object metadata
In the following sample commands that do not contain the --update option, if you do not specify header:value#header:value..., only user metadata that starts with X-Oss-Meta-
is retained and the value of user metadata is not modified.update span For HTTP headers, ossutil uses the interactive mode to ask you whether to retain these headers.
Example 1: Configure or update the metadata of a single object
Run the following command to set the access control list (ACL) of an object named exampleobject.txt in a bucket named examplebucket to private:
./ossutil64 set-meta oss://examplebucket/exampleobject.txt X-Oss-Object-Acl:private
Run the following command to set the storage class of a specific version of an object named exampleobject.txt in a bucket named examplebucket to Standard:
./ossutil64 set-meta oss://examplebucket/exampleobject.txt X-Oss-Storage-Class:Standard --version-id CAEQARiBgID8rumR2hYiIGUyOTAyZGY2MzU5MjQ5ZjlhYzQzZjNlYTAyZDE3MDRk
Run the following command to set the storage class of a specific version of an object named exampleobject.txt in a bucket named examplebucket to Cold Archive:
./ossutil64 set-meta oss://examplebucket/exampleobject.txt X-Oss-Storage-Class:ColdArchive --version-id CAEQARiBgID8rumR2hYiIGUyOTAyZGY2MzU5MjQ5ZjlhYzQzZjNlYTAyZDE3MDRk
NoteThe storage class does not change when you run the set-meta command. The storage class changes only after you run the command.
For more information about how to query the versions of an object, see Is.
Run the following command to set the ACL of an object named exampleobject.txt in a bucket named examplebucket to public-read:
./ossutil64 set-meta oss://examplebucket/exampleobject.txt X-Oss-Object-Acl:public-read --update
When you use the --update option, only the metadata that matches the specified header of the destination object is updated, and the value of the object header is replaced with that of the specified header. You can leave the value of the specified header empty. If you leave the value empty, the value of the header remains unchanged. In the preceding example, the ACL of the exampleobject.txt object is updated to public-read, and other metadata of the object remains unchanged.
Example 2: Configure or update the metadata of multiple objects in the same directory at the same time
If an error occurs when the metadata of one of the objects is configured or modified, ossutil records the error information about the object in the report file of the ossutil_output directory. Information about the objects whose metadata is configured or updated is not recorded in the report file.
Configure the metadata of objects whose names contain a specific prefix
The following command provides an example on how to change the caching behavior of the objects to no-cache and the ACL of the objects to private by using the -r option. The names of the objects contain the src prefix, and the objects are stored in examplebucket.
./ossutil64 set-meta oss://examplebucket/src Cache-Control:no-cache#X-Oss-Object-Acl:private -r
Modify the metadata of objects that meet the specified conditions
The following command provides an example on how to change the storage class of the objects to Infrequent Access (IA) by using the -r and -u options. The type of the objects is .jpg, and the objects are stored in the desfolder directory of examplebucket.
./ossutil64 set-meta oss://examplebucket/desfolder/ X-Oss-Storage-Class:IA --include "*.jpg" -u -r
The following command provides an example on how to change the storage class of the objects to Archive by using the -r and -u options. The names of the objects contain abc. The type of the objects is not jpg or txt, and the objects are stored in the desfolder directory of examplebucket.
./ossutil64 set-meta oss://examplebucket/desfolder/ X-Oss-Storage-Class:Archive --include "*abc*" --exclude "*.jpg" --exclude "*.txt" -u -r
ImportantWhen you run the set-meta command to convert the storage class of a Cold Archive or Deep Cold Archive object that is larger than 100 MB in size, the conversion may fail due to server timeout. To convert the storage class of a Cold Archive or Deep Cold Archive object that is larger than 100 MB in size, we recommend that you run the cp command.
Example 3: Configure or update the metadata of multiple objects in different directories or in the same directory
Configure or update the metadata of multiple objects in different directories
In this example, you want to configure or update the metadata of the following objects in different directories of a bucket named examplebucket: an object named exampleobject1.jpg in the root directory, an object named exampleobject2.png in the dir1/ directory, and an object named exampleobject3.txt in the dir2/ directory. To configure or update the metadata of the objects, perform the following steps:
Write the names of the objects whose metadata you want to configure or update to a local file named localfile.txt.
exampleobject1.jpg dir1/exampleobject2.png dir2/exampleobject3.txt
Configure or update the metadata of the objects.
The following command provides an example on how to change the caching behavior of the objects to no-cache and the ACL of the objects to private by using the --object-file option, and enable snapshots.
./ossutil64 set-meta oss://examplebucket Cache-Control:no-cache#X-Oss-Object-Acl:private --update --object-file localfile.txt --snapshot-path dir/
Configure or update the metadata of multiple objects in the same directory
Method 1
For more information about how to configure or update the metadata of multiple objects in the same directory, see the operations in different directories in the Example 3: Configure or update the metadata of multiple objects in different directories or in the same directory section of this topic.
Method 2
For more information about how to configure or update the metadata of multiple objects in the same directory, see the Example 2: Configure or update the metadata of multiple objects in the same directory at the same time section of this topic.
Sample response
If the preceding command is successfully run, a command output similar to the following one is returned to indicate the period of time used to configure or update the object metadata:
0.106852(s) elapsed
Delete user metadata
If you use the --delete option to delete user metadata, only user metadata that starts with X-Oss-Meta-
can be deleted.
Example 1: Delete the user metadata of an object
The following command provides an example on how to delete the user metadata that starts with
X-Oss-Meta-
from an object named exampleobject.txt stored in a bucket named examplebucket. You must leave the value of user metadata empty../ossutil64 set-meta oss://examplebucket/exampleobject.txt X-Oss-Meta-Createdby --delete
Example 2: Delete the user metadata of multiple objects at a time
To delete the user metadata of multiple objects at a time, perform the following steps:
Write the names of the objects whose user metadata you want to delete to a local file named localfile.txt.
exampleobject1.jpg dir1/exampleobject2.png dir2/exampleobject3.txt
Delete the user metadata of the objects.
The following command provides an example on how to delete user metadata that starts with
X-Oss-Meta-
from multiple objects in a bucket named examplebucket at the same time by using the --object-file option../ossutil64 set-meta oss://examplebucket X-Oss-Meta-Location --delete --object-file localfile.txt --snapshot-path dir/
Sample response
If the preceding command is successfully run, a command output similar to the following one is returned to indicate the period of time used to delete user metadata:
0.106846(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, you can 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 the metadata of the testobject.jpg object in the testbucket bucket which is located in the China (Shanghai) region and owned by another Alibaba Cloud account:
./ossutil64 set-meta oss://testbucket/testobject.jpg X-Oss-Object-Acl:private -e oss-cn-shanghai.aliyuncs.com -i LTAI4Fw2NbDUCV8zYUzA**** -k 67DLVBkH7EamOjy2W5RVAHUY9H****
For more information about other common options that you can use for the sync command, see View options.