set-meta (Manage object metadata)

Usage notes

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

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

• After you set or update object metadata using the set-meta command, you can view the object metadata using the stat command. 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-id <value>]
[--include <value>]
[--exclude <value>]

The following describes the parameters and options:

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
      and headers that start with X-Oss-Meta-

Set or update metadata

In the following examples that do not include the --update option, if you do not specify the header:value#header:value... option, only user-defined metadata that starts with X-Oss-Meta- is retained, and its values are not changed. For HTTP headers, ossutil enters an interactive mode and prompts you to confirm whether to retain them.

• Example 1: Set or update metadata for a single object

  • Set the access control list (ACL) of exampleobject.txt in the examplebucket bucket to private.

    ossutil set-meta oss://examplebucket/exampleobject.txt X-Oss-Object-Acl:private 

  • 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

  • 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 is not changed during the execution of the set-meta command. The change takes effect after the command completes.

    For more information about how to obtain object versions, see ls.

  • Update 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, only the metadata for the specified headers is updated. The values of these headers are replaced, and all other existing metadata on the object remains unchanged. For example, the command updates only the ACL of the exampleobject.txt object to public-read. All other metadata of the object is preserved.

• Example 2: Set or update metadata for multiple objects in the same folder in a batch operation

  When you set or modify metadata for multiple objects in a batch operation, if an error occurs for an object, ossutil records the error message for that object in a report file in the ossutil_output folder. Successfully processed objects are not recorded in the report file.

  • Set metadata for objects that match a specified prefix

    Use the -r option to change the caching behavior (Cache-Control) to no-cache and the ACL (x-oss-object-acl) to private for all objects that match the `src` prefix in the examplebucket bucket.

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

  • Modify metadata for objects that match specified filter conditions

    • Use the -r and -u options to change the storage class to Infrequent Access (IA) for all objects of the .jpg file type in the desfolder/ folder of the examplebucket bucket.

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

    • Use the -r and -u options to change the storage class to Archive Storage for objects in the desfolder/ folder of the examplebucket bucket if their filenames contain abc and their file types are not .jpg or .txt.

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

    Important

    When you use the set-meta command to change the storage class of a Cold Archive or Deep Cold Archive object larger than 100 MB, the operation may fail due to a server timeout. To change the storage class of these objects, use the cp command.

• Example 3: Set or update metadata for multiple objects in the same or different folders

  • Objects in different folders

    To set or update metadata for multiple objects located in different folders within a bucket, follow these steps. For example, exampleobject1.jpg is in the root folder of examplebucket, exampleobject2.png is in the dir1/ folder, and exampleobject3.txt is in the dir2/ folder.

    1. You can write multiple Objects to a local file named localfile.txt to set or update their metadata.

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

    2. Set or update the metadata for the specified objects.

       Use the --object-file option to change the caching behavior (Cache-Control) to no-cache and the ACL (x-oss-object-acl) to private for multiple objects in the examplebucket bucket, 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/

  • Objects in the same folder

    • Method 1

      Refer to the preceding example for objects in different folders to set or update metadata for multiple objects in the same folder.

    • Method 2

      Refer to Example 2 to set or update metadata for multiple objects in the same folder.

• Sample output

  If the operation is successful, the output shows the time elapsed. The following is a sample output:

  0.106852(s) elapsed

Delete custom metadata

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

  Delete the custom metadata that starts with X-Oss-Meta- for the exampleobject.txt object in the examplebucket bucket. The header value must be empty.

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

• Example 2: Delete the custom metadata of multiple objects in a batch operation

  To delete the custom metadata of multiple objects in a batch operation, follow these steps:

  1. Write the names of the objects whose custom metadata you want to delete to a local file named localfile.txt.

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

  2. Delete the custom metadata of the objects.

     Use the --object-file option to delete the custom metadata that starts with X-Oss-Meta- for multiple objects in the examplebucket bucket in a batch operation. The header value must be empty.

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

• Sample output

  If the operation is successful, the output shows the time elapsed. The following is a sample output:

  0.106846(s) elapsed

Common options

To access a bucket in a different region, use -e to specify the endpoint. To access a bucket owned by a different Alibaba Cloud account, use -i for the AccessKey ID and -k for the AccessKey secret.

ossutil set-meta oss://testbucket/testobject.jpg X-Oss-Object-Acl:private  -e oss-cn-shanghai.aliyuncs.com -i yourAccessKeyID  -k yourAccessKeySecret

Common options.