Object Storage Service:set-meta

Usage notes

• To configure metadata for a single object, you must have the oss:GetObject, oss:PutObject, oss:GetObjectVersion, and oss:GetObjectAcl permissions. To configure metadata for multiple objects at a time, you must have the oss:GetObject, oss:PutObject, oss:GetObjectVersion, and oss:ListObjects permissions. For more information, see Attach a custom policy to a RAM user.

• For ossutil 1.6.16 and later, you can directly use ossutil as the binary name in the command line. You do not need to update the binary name based on the operating system. For ossutil earlier than 1.6.16, you need to update the binary name based on the operating system. For more information, see ossutil command reference.

• 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

ossutil 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 and options in the command syntax.

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 the 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 metadata for a single object

  • Run the following command to set the access control list (ACL) of the exampleobject.txt object in the examplebucket bucket to private:

    ossutil 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 the exampleobject.txt object in the examplebucket bucket to Standard:

    ossutil 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 the exampleobject.txt object in the examplebucket bucket to Cold Archive:

    ossutil set-meta oss://examplebucket/exampleobject.txt X-Oss-Storage-Class:ColdArchive --version-id  CAEQARiBgID8rumR2hYiIGUyOTAyZGY2MzU5MjQ5ZjlhYzQzZjNlYTAyZDE3MDRk

    Note

    The storage class does not change before the set-meta command is complete. The storage class changes only when the command is complete.

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

  • Run the following command to set the ACL of the exampleobject.txt object in the examplebucket bucket to public-read:

    ossutil set-meta oss://examplebucket/exampleobject.txt X-Oss-Object-Acl:public-read --update

    When you use the --update option, the specified header of the object is updated to the specified value. You can leave the value of the specified header empty. If you leave the value of the specified header empty, the original header value 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 metadata for multiple objects in the same directory at the same time

  If an error occurs when the metadata of one of the objects is being configured or modified, ossutil records the error information about the object in the report file in the ossutil_output directory. Information about the objects whose metadata is configured or updated is not recorded in the report file.

  • Configure metadata for objects whose names contain a specific prefix

    The following command changes the caching behavior of the objects with the src prefix in their names in the examplebucket bucket to no-cache and the ACL of the objects to private by using the -r option:

    ossutil set-meta oss://examplebucket/src Cache-Control:no-cache#X-Oss-Object-Acl:private -r                             

  • Modify metadata for objects that meet the specified conditions

    • The following command changes the storage classes of the .jpg objects in the desfolder directory of the examplebucket bucket to Infrequent Access (IA) by using the -r and -u options:

      ossutil set-meta oss://examplebucket/desfolder/ X-Oss-Storage-Class:IA --include "*.jpg" -u -r                                        

    • The following command changes the storage classes of the following objects to Archive by using the -r and -u options: non-JPG and non-TXT objects whose names contain abc in the desfolder directory of examplebucket:

      ossutil 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 change the storage class of a Cold Archive or Deep Cold Archive object that is larger than 100 MB in size, the operation may fail due to server timeout. To change 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 metadata for multiple objects in the same or different directories

  • Configure or update metadata for multiple objects in different directories

    For example, you want to configure or update the metadata of the following objects in different directories of the examplebucket bucket: exampleobject1.jpg in the root directory, exampleobject2.png in the dir1/ directory, and exampleobject3.txt in the dir2/ directory. To configure or update the metadata for the objects, perform the following steps:

    1. Write the names of the objects to the localfile.txt file.

       exampleobject1.jpg
       dir1/exampleobject2.png
       dir2/exampleobject3.txt

    2. Configure or update the metadata for 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.

       ossutil set-meta oss://examplebucket Cache-Control:no-cache#X-Oss-Object-Acl:private --update --object-file localfile.txt --snapshot-path dir/

  • Configure or update metadata for multiple objects in the same directory

    • Method 1

      For more information about how to configure or update metadata for multiple objects in the same directory, see Example 3: Configure or update metadata for multiple objects in the same or different directories.

    • Method 2

      For more information about how to configure or update metadata of multiple objects in the same directory, see Example 2: Configure or update metadata for multiple objects in the same directory at the same time.

• Sample output

  If the preceding command is successfully run, the output similar to following result is returned to indicate the period of time that is consumed to configure or update the object metadata:

  0.106852(s) elapsed

Delete user metadata

• Example 1: Delete the user metadata of a single object

  The following command provides an example on how to delete the user metadata that starts with X-Oss-Meta- for the exampleobject.txt object in the examplebucket bucket. You must leave the value of the user metadata empty.

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

• Example 2: Delete the user metadata of multiple objects at the same time

  To delete the user metadata of multiple objects at the same time, perform the following steps:

  1. Write the names of the objects whose user metadata you want to delete to the localfile.txt file.

     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 the user metadata that starts with X-Oss-Meta- of multiple objects in the examplebucket bucket at the same time by using the --object-file option. The value of the metadata header must be empty.

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

• Sample output

  If the preceding command is successfully run, the output similar to following result is returned to indicate the period of time that is consumed to delete the 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 specify the endpoint of the region in which the bucket is located. If you use ossutil to switch to a bucket that belongs to another Alibaba Cloud account, add the -i option to specify the AccessKey ID of the specified account, and add the -k option to specify the AccessKey secret of the specified account.

ossutil 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 common options, see Common options.