All Products
Search
Document Center

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

Last Updated:Sep 27, 2023

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

Option

Description

bucketname

The name of the bucket in which the objects whose metadata you want to manage are stored.

prefix

The resources 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 not case-sensitive, 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 that have the X-Oss-Meta- prefix

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

Specifies the objects for which you can configure metadata. If you specify this option, ossutil configures the metadata for all objects whose names contain a specific prefix in the bucket. If you do not specify this option, ossutil configures the metadata only for a specific object.

-f, --force

Specifies that the operation is forcibly performed. The operation is performed without a prompt for confirmation.

--object-file

Configures, updates, or deletes the metadata of multiple objects at a time. To use this option, perform the following steps:

  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 configures, updates, or deletes 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

The snapshots that are generated. If you specify this option, 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 option must be used together with the -r, --recursive or --object-file option.

--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 option applies only to objects in buckets for which versioning is enabled or suspended.

--include

Specifies that the command applies to all objects that meet the specified conditions.

For more information, see set-meta (manage object metadata).

--exclude

Specifies that the command applies to all objects that do not meet the specified conditions.

For more information, see set-meta (manage object metadata).

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

  • 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

Important

If you use the --delete option to delete user metadata, only user metadata that starts with X-Oss-Meta- can be deleted.

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

For example, you can run the following command to configure the metadata of the testobject.jpg object in the testbucket bucket 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 use for the sync command, see View options.