Object Storage Service:set-meta (manage object metadata)

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.

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 that have the X-Oss-Meta- prefix

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

    Note

    The 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

    Important

    When 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:

    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 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

• 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:

  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 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.

./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.