All Products
Search
Document Center

Object Storage Service:set-meta

Last Updated:Aug 19, 2024

Object Storage Service (OSS) uses object metadata to describe an object. 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 objects.

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.

Parameter/Option

Description

bucketname

The name of the bucket.

prefix

The prefix in the names of resources in the bucket, such as directories and objects.

header:value#header:value...

The metadata headers in the form of key-value pairs. Header keys are not case-sensitive, whereas header values are case-sensitive. If you want to configure multiple metadata headers, separate the metadata headers 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 metadata for all objects whose names contain the specified prefix in the bucket. If you do not specify this option, ossutil configures metadata only for the specified object.

-f, --force

Forces the operation without requiring confirmation.

--object-file

Specifies the objects for which you want to configure, update, or delete metadata 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 for which you want to configure, update, or delete metadata in the file. Separate multiple names with line feeds.

  2. Use ossutil to read all object names from the local file for metadata configuration, update or deletion.

Note

If an error occurs on one of the objects, ossutil records the error information about the object in the report file and continues the operation on other objects. Information about the objects for which metadata is configured, updated, or deleted is not recorded in the report file.

--snapshot-path

The path of snapshots. 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, no snapshots are generated again for the objects.

Note

This option must be used together with -r, --recursive or --object-file.

--disable-ignore-error

Specifies that errors during batch operations are not ignored.

--version-id

The version ID of the object whose metadata you want to manage. This option applies only when the versioning status of the bucket is enabled or suspended.

--include

Includes all objects that meet the specified conditions.

For more information, see Options --include and --exclude.

--exclude

Excludes all objects that meet the specified conditions.

For more information, see Options --include and --exclude.

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

  • 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

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

For example, you can run the following command to configure metadata for the testobject.jpg object in the testbucket bucket which is located in the China (Shanghai) region and owned by another Alibaba Cloud 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.