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.

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 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 parameters that you can configure to run the set-meta command.

Parameter Description
bucketname The name of the bucket in which the objects whose metadata you want to manage are stored.
prefix The resources that are 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 case-insensitive, whereas values are case-sensitive. If you want to configure multiple sets of metadata, separate the sets 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 X-Oss-Meta-
For more information about how to use headers, see Manage object metadata.
--update Updates object metadata. This parameter can be shortened to -u and cannot be used together with --delete.
--delete Deletes object metadata. This parameter cannot be used together with --update.
-r, --recursive If you specify this parameter, ossutil configures the metadata for all objects whose names contain the specified prefix in the bucket. If you do not specify this parameter, ossutil configures the metadata only for a specified object.
-f, --force Specifies the operation that is forcibly performed without prompts.
--object-file This parameter is used to configure, update, or delete the metadata of multiple objects at the same time. You must perform the following steps to use this parameter:
  1. Specify a local TXT or XML file. Then, enter the names of all objects whose metadata you want to configure, update, or delete in the file.
  2. ossutil reads all object names in the local file and then configure, update, or delete object metadata.
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 If you specify this parameter, 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 parameter must be used together with the -r, --recursive or --object-file parameter.
--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 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.

Configure or update object metadata

In the following sample commands that do not contain the --update parameter, if you do not specify the header:value#header:value... parameter, only user metadata that starts with X-Oss-Meta- is retained and the value of user metadata is not modified. 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

    • 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 a specified 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

      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 parameter, 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 specified 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 parameter. 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 parameters. 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 parameters. 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 examplebucket.
        ./ossutil64 set-meta oss://examplebucket/desfolder/ X-Oss-Storage-Class:Archive --include "*abc*" --exclude "*.jpg" --exclude "*.txt" -u -r
      Notice When you run the set-meta command to convert the storage class of a Cold Archive object that is larger than 100 MB in size, the conversion may fail due to server timeout. In this case, we recommend that you use 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 within 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. In this case, you must perform the following steps to configure or update the metadata of the objects:
      1. 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
      2. 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 parameter, 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
  • Returned results

    If the preceding command runs successfully, a command output similar to the following one is returned to indicate the time used to configure or update object metadata:

    0.106852(s) elapsed

Delete user metadata

Notice If you use the --delete parameter to delete user metadata, only user metadata that starts with X-Oss-Meta- can be deleted.
  • Example 1: Delete user metadata of a single object

    The following command provides an example on how to delete 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 user metadata of multiple objects

    You must perform the following steps to delete user metadata of multiple objects at the same time:

    1. 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
    2. Delete 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 parameter.

      ./ossutil64 set-meta oss://examplebucket X-Oss-Meta-Location --delete --object-file localfile.txt --snapshot-path dir/
  • Returned results

    If the preceding command runs successfully, a command output similar to the following one is returned to indicate the 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 stored in testbucket, 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 specify in the sync command, see Common options.