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 customize the policies of HTTP requests, and user metadata can be used to identify the purposes or attributes of objects. You can run the set-meta command to set, modify, or delete metadata for uploaded objects.

Note
  • 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 set or update the object metadata by running the set-meta command, you can run the stat command to view the 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]
[--include <value>]
[--version <value>]
[--exclude <value>]

The following table describes the parameters that you can configure when you run this command.

Parameter Description
bucketname The name of the bucket in which the objects whose metadata you want to set or modify are stored.
prefix The resources stored in the bucket, such as directories and objects.
header:value#header:value... Identifies object metadata by using key-value pairs. Headers are case-insensitive, whereas values are case-sensitive. If you want to set multiple sets of metadata, separate each set of metadata with number signs (#). Example: Cache-Control:no-cache#Expires:2022-10-12T00:00:00.000Z.
You can configure the following headers:
Headers:
      Expires(time.RFC3339:2006-01-02T15:04:05Z07:00)
      X-Oss-Object-Acl
      Origin
      X-Oss-Storage-Class
      Content-Encoding
      Cache-Control
      Content-Disposition
      Accept-Encoding
      X-Oss-Server-Side-Encryption
      Content-Type
      Headers prefixed with the X-Oss-Meta-
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 If you specify this parameter, ossutil sets metadata for all objects whose names contain the specified prefix in the bucket. If you do not specify this parameter, ossutil sets metadata only for a specified object.
-f, --force Specifies the command to forcibly run without prompting the user for confirmation.
--version-id The specified version of the object for which you want to set metadata. This parameter applies only to objects in buckets for which versioning is enabled or suspended.
--include Specifies that the command applies to all objects that meet specified conditions.
--exclude Specifies that the command applies to all objects that do not meet specified conditions.

Examples

In the following examples that do not contain --update or --delete, if header:value#header:value... is not specified, only the metadata that starts with X-Oss-Meta- is retained, and the value of the object metadata is not changed. For HTTP headers, ossutil uses the interactive mode to ask you whether to retain these headers.

  • Set or update the metadata of a single object
    • You can 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
    • You can run the following command to set the storage class of an object named exampleobject.txt in a bucket named examplebucket to Standard: 
      ./ossutil set-meta oss://examplebucket/exampleobject.txt X-Oss-Storage-Class:Standard --version-id  CAEQARiBgID8rumR2hYiIGUyOTAyZGY2MzU5MjQ5ZjlhYzQzZjNlYTAyZDE3MDRk

      For more information about how to query the versions of an object, see Is.

    • You can 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.

  • Set or update metadata of multiple objects

    If an error occurs in one of the objects when you set or modify the metadata of multiple objects at the same time, ossutil records the error information of the object in the report object of the ossutil_output directory. Object information of a successful operation is not recorded in the report object.

    • Set object metadata that matches a specified prefix

      The following command provides an example on how to modify the object metadata to change the cache 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 the examplebucket bucket. 

      ./ossutil64 set-meta oss://examplebucket/src Cache-Control:no-cache#X-Oss-Object-Acl:private -r
    • Modify object metadata that meets specified conditions
      • The following command provides an example on how to modify the object metadata 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 the examplebucket bucket. 
        ./ossutil64 set-meta oss://examplebucket/desfolder/ X-Oss-Storage-Class:IA --include "*.jpg" -u -r
      • The following command provides an example on how to modify the object metadata 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 types of the objects are not jpg or txt, and the objects are stored in the desfolder directory of the examplebucket bucket. 
        ./ossutil64 set-meta oss://examplebucket/desfolder/ X-Oss-Storage-Class:Archive --include "*abc*" --exclude "*.jpg" --exclude "*.txt" -u -r
  • Delete the user metadata of a specified object

    You can add --delete to the set-meta command to delete the user metadata that starts with X-Oss-Meta- and whose value is empty for the exampleobject.txt object. The object is in the examplebucket bucket. The object metadata that does not start with X-Oss-Meta- is not deleted after you run the following command: 

    ./ossutil64 set-meta oss://examplebucket/exampleobject.txt X-Oss-Meta-Createdby  --delete

Common options

To use ossutil to manage buckets that are located in different regions, you can use the -e option to use the endpoint of the specified bucket. To use ossutil to manage buckets that are owned by different Alibaba Cloud accounts, you can use the -i option to use the AccessKey ID of the specified account, and use the -k option to use the AccessKey secret of the specified account.

For example, you can run the following command to set the metadata of the testobject.jpg object stored in the examplebucket bucket which is located in the China (Shanghai) region and is 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 command, see Common options.