Help Center/ Object Storage Service/ User Guide/ Object Management/ Object Management/ Configuring, Editing, and Viewing Object Metadata
Updated on 2025-09-26 GMT+08:00
View PDF
Share

Configuring, Editing, and Viewing Object Metadata

Scenarios

Object metadata is a set of name-value pairs that describe an object and is used for object management. OBS has two types of metadata: system-defined object metadata and user-defined object metadata. System-defined metadata includes the object's creation date, size, and storage class. User-defined metadata is the metadata that you can set for an object to identify the purpose or properties of the object.

You can configure metadata for an object when uploading it or edit the metadata after the object is uploaded.

Metadata Introduction

System-defined Object Metadata

There are two types of system-defined metadata: system-controlled and user-controlled.

  • System-controlled: metadata that is controlled by the system and cannot be edited by users, for example, LastModified
  • User-controlled: metadata whose value you can control. For example, if you use an OBS bucket to host a static web page and you might want to redirect requests for the hosted page to another page or an external URL, you can configure WebsiteRedirectLocation for the page. In this case, OBS stores the redirection value as system metadata that you can control. Table 1 lists the metadata items that you can control.
Table 1 OBS metadata

Metadata

Description

Changeable by User or Not

ContentDisposition

Controls how a browser handles the content it receives. Especially during file downloads, this metadata directs the browser to either display the file inline or prompt the user to download it to their device, optionally with a specified filename. The metadata values can be:

  • ContentDisposition: inline: The file content is displayed for preview.

    If the bucket does not have a user-defined domain name, the ContentDisposition: inline setting for the object will be ignored. OBS will forcibly return the ContentDisposition: attachment header.

  • ContentDisposition: attachment: The file is downloaded to the browser's specified path with its original filename.
  • ContentDisposition: attachment; filename="testfile.xls": The file is downloaded to the browser's specified path with the filename testfile.xls.
NOTE:

If the file name contains special characters, it may be escaped when the file is downloaded to the local device. To ensure that the file name is correctly displayed in different browsers, you can use URL encoding or RFC 5987 encoding. The following gives some examples:

  • URL encoding: ContentDisposition: attachment; filename="test file.xls"; filename="test%20file.xls"
  • RFC 5987 encoding: ContentDisposition: attachment; filename="test file.xls"; filename*=UTF-8''test%20file.xls

For more information, see the definition of ContentDisposition in the HTTP protocol.

Yes

ContentLanguage

States the language or languages intended for the audience. The metadata values can be:

  • ContentLanguage: zh-CN: simplified Chinese
  • Content-Language: en-US: English
  • Content-Language: fr-FR: French
  • Content-Language: es-ES: Spanish
NOTE:

Separated multiple languages with commas (,), for example, Content-Language: en-US, fr-FR.

For more information, see the definition of ContentLanguage in the HTTP protocol.

Yes

WebsiteRedirectLocation

Redirects requests for an object to another object or an external URL. If redirection is configured for an object, the response returned upon a request for that object will include the WebsiteRedirectLocation header to tell the URL to which the request should be redirected. The redirection is implemented using static website hosting.

The format is WebsiteRedirectLocation: <url>, where <url> indicates the target URL of redirection.

OBS only supports redirection for objects in a bucket's root directory. Redirection for objects in the bucket's folders is not supported.

For example, you can redirect requests for an object by doing as follows:

  1. Configure the WebsiteRedirectLocation metadata for object testobject.html in the root directory of bucket testbucket and set the metadata value to http://www.example.com.
  2. Configure static website hosting for bucket testbucket, and set object testobject.html as the default homepage.
  3. Access object testobject.html through the URL provided on the static website hosting page. The access will be redirected to http://www.example.com.

Yes

ContentEncoding

Specifies the content encoding format when an object is downloaded. This metadata tells a client to decode objects according to their encoding format, so that the content can be correctly displayed or processed. The value options are as follows:

  • Standard:
    • identity: The content is not encoded.
    • gzip: The content is compressed using GNU zip (gzip). gzip is the most common algorithm that can be used for all kinds of data.
    • compress: The content is compressed using Lempel-Ziv-Welch (LZW). LZW is rarely used.
    • deflate: The content is compressed using an algorithm in zlib format. zlib uses DEFLATE internally and is rarely used.
    • exi: The content is compressed using Efficient XML Interchange (EXI). EXI is only used for XML data.
    • pack200-gzip: The content is compressed using Java Pack200 and then gzip. This compression method is specially designed for Java Archive (JAR) files.
  • Others:
    • br: The content is compressed using Brotli. Most browsers support this algorithm.
    • bzip2: The content is compressed using bzip2. This algorithm has an excellent compression ratio, but a slow compression speed.
    • lzma: The content is compressed using Lempel–Ziv–Markov chain algorithm (LZMA). This algorithm has an excellent compression ratio, but a slow compression speed.
    • peerdist: The content is distributed using PDP.
    • sdch: The content is compressed using Shared Dictionary Compression for HTTP (SDCH). This algorithm uses a shared dictionary for efficient compression.
    • xpress: The content is compressed using Xpress. This algorithm is rarely used and is used in specific scenarios.
    • xz: The content is compressed using XZ. XZ uses LZMA2 internally, and has an excellent compression ratio, but a slow compression speed.

Yes

CacheControl

Specifies the caching behavior for a web page when an object is downloaded. The value options are as follows:

  • Cacheability:
    • public: Content related to requests or responses can be stored in any cache, including private and shared caches.
    • private: Content related to requests or responses can only be stored in private caches.
    • no-cache: The cache does not store any content related to requests or responses.
    • only-if-cached: Only resources in the cache are accepted. No revalidation is performed.
  • Expiration time:
    • max-age=<seconds>: It sets the maximum amount of time that a client considers a resource fresh.
    • s-maxage=<seconds>: It sets the maximum amount of time that a shared cache can store a resource before it must revalidate the resource.
    • max-stale[=<seconds>]: It sets how long a client can tolerate expired resources.
    • min-fresh=<seconds>: It sets the minimum amount of time that a client considers a resource fresh.
    • stale-while-revalidate=<seconds>: The cache continues to use the cached resource after the resource expires, and revalidates the resource freshness in the background.
    • stale-if-error=<seconds>: The cache uses the cached resource when there is a network error or the revalidation fails.
  • Revalidation and reload:
    • must-revalidate: The cache must revalidate resources after they expire.
    • proxy-revalidate: It is similar to must-revalidate, but it applies only to shared caches.
    • immutable: Resources will not change during their cache lifetime. The cache can use the cached resources indefinitely without revalidation.
  • Others:

    no-store: The client does not store any requests or responses.

    no-transform: The cache server does not modify resources. The cache server may compress resources or convert their format to optimize transmission.

Yes

Expires

Specifies the cache expiration time (GMT).

Yes

ContentType

Specifies the object type. It determines the format and encoding method a browser will use to read the file. For details, see Table 2.

Yes

Date

Specifies the current date and time. Example: WED, 01 Jul 2015 04:19:21 GMT

No

Content-Length

Specifies the object size.

Unit: byte

No

Last-Modified

Specifies the date and time when an object was first uploaded or last modified. Example: WED, 01 Jul 2015 04:19:21 GMT

In a multipart upload, the object's creation date is when the multipart upload started.

No

ETag

Base64-encoded 128-bit MD5 digest of an object. ETag is the unique identifier of the object content. It reflects whether the object content is changed. For example, if the ETag value is A when an object is uploaded but is B when the object is downloaded, it means that the object content has been changed.

The ETag value is a hash of the object.

No

x-obs-tagging-count

The number of tags associated with an object. For example, x-obs-tagging-count:1 indicates that the object has one tag.

No

x-obs-version-id

The object version ID. When versioning is enabled for a bucket, OBS assigns a version ID to each object in the bucket. For more information, see Versioning.

No

x-obs-storage-class

The storage class of an object. The value can be:

  • STANDARD: the Standard storage class
  • WARM: the Infrequent Access storage class
  • COLD: the Archive storage class
  • DEEP_ARCHIVE: the Deep Archive storage class

Yes

For more information about object metadata, see Object Metadata.

Object Metadata Content-Type

When you access an object through a web browser, the browser uses the object's Content-Type to determine how to handle and display the object. You can change an object's Content-Type based on its file name extension.

  • If you upload an object by calling an API, specify the value of Content-Type.
  • If you upload an object through OBS Console, OBS automatically matches the Content-Type value based on the file name extension of the object.
  • If the value of Content-Type does not match the file name extension, the file name extension will change after the file is downloaded.
Table 2 Common Content-Type values

File Name Extension

Content-Type

File Name Extension

Content-Type

.* (binary stream, unknown file type)

application/octet-stream

.7z

application/x-7z-compressed

.001

application/x-001

.301

application/x-301

.323

text/h323

.906

application/x-906

.907

drawing/907

.a11

application/x-a11

.acp

audio/x-mei-aac

.ai

application/postscript

.aif

audio/aiff

.aifc

audio/aiff

.aiff

audio/aiff

.anv

application/x-anv

.asa

text/asa

.asf

video/x-ms-asf

.asp

text/asp

.asx

video/x-ms-asf

.au

audio/basic

.avi

video/avi

.awf

application/vnd.adobe.workflow

.biz

text/xml

.bmp

application/x-bmp

.bot

application/x-bot

.c4t

application/x-c4t

.c90

application/x-c90

.cal

application/x-cals

.cat

application/vnd.ms-pki.seccat

.cdf

application/x-netcdf

.cdr

application/x-cdr

.cel

application/x-cel

.cer

application/x-x509-ca-cert

.cg4

application/x-g4

.cgm

application/x-cgm

.cit

application/x-cit

.class

java/*

.cml

text/xml

.cmp

application/x-cmp

.cmx

application/x-cmx

.cot

application/x-cot

.crl

application/pkix-crl

.crt

application/x-x509-ca-cert

.csi

application/x-csi

.css

text/css

.cut

application/x-cut

.dbf

application/x-dbf

.dbm

application/x-dbm

.dbx

application/x-dbx

.dcd

text/xml

.dcx

application/x-dcx

.der

application/x-x509-ca-cert

.dgn

application/x-dgn

.dib

application/x-dib

.dll

application/x-msdownload

.doc

application/msword

.dot

application/msword

.drw

application/x-drw

.dtd

text/xml

.dwf

Model/vnd.dwf

.dwf

application/x-dwf

.dwg

application/x-dwg

.dxb

application/x-dxb

.dxf

application/x-dxf

.edn

application/vnd.adobe.edn

.emf

application/x-emf

.eml

message/rfc822

.ent

text/xml

.epi

application/x-epi

.eps

application/x-ps

.eps

application/postscript

.etd

application/x-ebx

.exe

application/x-msdownload

.fax

image/fax

.fdf

application/vnd.fdf

.fif

application/fractals

.fo

text/xml

.frm

application/x-frm

.g4

application/x-g4

.gbr

application/x-gbr

.

application/x-

.gif

image/gif

.gl2

application/x-gl2

.gp4

application/x-gp4

.hgl

application/x-hgl

.hmr

application/x-hmr

.hpg

application/x-hpgl

.hpl

application/x-hpl

.hqx

application/mac-binhex40

.hrf

application/x-hrf

.hta

application/hta

.htc

text/x-component

.htm

text/html

.html

text/html

.htt

text/webviewhtml

.htx

text/html

.icb

application/x-icb

.ico

image/x-icon

.ico

application/x-ico

.iff

application/x-iff

.ig4

application/x-g4

.igs

application/x-igs

.iii

application/x-iphone

.img

application/x-img

.ins

application/x-internet-signup

.isp

application/x-internet-signup

.IVF

video/x-ivf

.java

java/*

.jfif

image/jpeg

.jpe

image/jpeg

.jpe

application/x-jpe

.jpeg

image/jpeg

.jpg

image/jpeg

.jpg

application/x-jpg

.js

application/x-javascript

.jsp

text/html

.la1

audio/x-liquid-file

.lar

application/x-laplayer-reg

.latex

application/x-latex

.lavs

audio/x-liquid-secure

.lbm

application/x-lbm

.lmsff

audio/x-la-lms

.ls

application/x-javascript

.ltr

application/x-ltr

.m1v

video/x-mpeg

.m2v

video/x-mpeg

.m3u

audio/mpegurl

.m4e

video/mpeg4

.mac

application/x-mac

.man

application/x-troff-man

.math

text/xml

.mdb

application/msaccess

.mdb

application/x-mdb

.mfp

application/x-shockwave-flash

.mht

message/rfc822

.mhtml

message/rfc822

.mi

application/x-mi

.mid

audio/mid

.midi

audio/mid

.mil

application/x-mil

.mml

text/xml

.mnd

audio/x-musicnet-download

.mns

audio/x-musicnet-stream

.mocha

application/x-javascript

.movie

video/x-sgi-movie

.mp1

audio/mp1

.mp2

audio/mp2

.mp2v

video/mpeg

.mp3

audio/mp3

.mp4

video/mp4

.mpa

video/x-mpg

.mpd

application/vnd.ms-project

.mpe

video/x-mpeg

.mpeg

video/mpg

.mpg

video/mpg

.mpga

audio/rn-mpeg

.mpp

application/vnd.ms-project

.mps

video/x-mpeg

.mpt

application/vnd.ms-project

.mpv

video/mpg

.mpv2

video/mpeg

.mpw

application/vnd.ms-project

.mpx

application/vnd.ms-project

.mtx

text/xml

.mxp

application/x-mmxp

.net

image/pnetvue

.nrf

application/x-nrf

.nws

message/rfc822

.odc

text/x-ms-odc

.out

application/x-out

.p10

application/pkcs10

.p12

application/x-pkcs12

.p7b

application/x-pkcs7-certificates

.p7c

application/pkcs7-mime

.p7m

application/pkcs7-mime

.p7r

application/x-pkcs7-certreqresp

.p7s

application/pkcs7-signature

.pc5

application/x-pc5

.pci

application/x-pci

.pcl

application/x-pcl

.pcx

application/x-pcx

.pdf

application/pdf

.pdf

application/pdf

.pdx

application/vnd.adobe.pdx

.pfx

application/x-pkcs12

.pgl

application/x-pgl

.pic

application/x-pic

.pko

application/vnd.ms-pki.pko

.pl

application/x-perl

.plg

text/html

.pls

audio/scpls

.plt

application/x-plt

.png

image/png

.png

application/x-png

.pot

application/vnd.ms-powerpoint

.ppa

application/vnd.ms-powerpoint

.ppm

application/x-ppm

.pps

application/vnd.ms-powerpoint

.ppt

application/vnd.ms-powerpoint

.ppt

application/x-ppt

.pr

application/x-pr

.prf

application/pics-rules

.prn

application/x-prn

.prt

application/x-prt

.ps

application/x-ps

.ps

application/postscript

.ptn

application/x-ptn

.pwz

application/vnd.ms-powerpoint

.r3t

text/vnd.rn-realtext3d

.ra

audio/vnd.rn-realaudio

.ram

audio/x-pn-realaudio

.ras

application/x-ras

.rat

application/rat-file

.rdf

text/xml

.rec

application/vnd.rn-recording

.red

application/x-red

.rgb

application/x-rgb

.rjs

application/vnd.rn-realsystem-rjs

.rjt

application/vnd.rn-realsystem-rjt

.rlc

application/x-rlc

.rle

application/x-rle

.rm

application/vnd.rn-realmedia

.rmf

application/vnd.adobe.rmf

.rmi

audio/mid

.rmj

application/vnd.rn-realsystem-rmj

.rmm

audio/x-pn-realaudio

.rmp

application/vnd.rn-rn_music_package

.rms

application/vnd.rn-realmedia-secure

.rmvb

application/vnd.rn-realmedia-vbr

.rmx

application/vnd.rn-realsystem-rmx

.rnx

application/vnd.rn-realplayer

.rp

image/vnd.rn-realpix

.rpm

audio/x-pn-realaudio-plugin

.rsml

application/vnd.rn-rsml

.rt

text/vnd.rn-realtext

.rtf

application/msword

.rtf

application/x-rtf

.rv

video/vnd.rn-realvideo

.sam

application/x-sam

.sat

application/x-sat

.sdp

application/sdp

.sdw

application/x-sdw

.sit

application/x-stuffit

.slb

application/x-slb

.sld

application/x-sld

.slk

drawing/x-slk

.smi

application/smil

.smil

application/smil

.smk

application/x-smk

.snd

audio/basic

.sol

text/plain

.sor

text/plain

.spc

application/x-pkcs7-certificates

.spl

application/futuresplash

.spp

text/xml

.ssm

application/streamingmedia

.sst

application/vnd.ms-pki.certstore

.stl

application/vnd.ms-pki.stl

.stm

text/html

.sty

application/x-sty

.svg

text/xml

.swf

application/x-shockwave-flash

.tdf

application/x-tdf

.tg4

application/x-tg4

.tga

application/x-tga

.tif

image/tiff

.tif

application/x-tif

.tiff

image/tiff

.tld

text/xml

.top

drawing/x-top

.torrent

application/x-bittorrent

.tsd

text/xml

.txt

text/plain

NOTE:

If you want to preview a TXT file online, set Content-Type to text/plain;charset=UTF-8 to avoid garbled characters.

.uin

application/x-icq

.uls

text/iuls

.vcf

text/x-vcard

.vda

application/x-vda

.vdx

application/vnd.visio

.vml

text/xml

.vpg

application/x-vpeg005

.vsd

application/vnd.visio

.vsd

application/x-vsd

.vss

application/vnd.visio

.vst

application/vnd.visio

.vst

application/x-vst

.vsw

application/vnd.visio

.vsx

application/vnd.visio

.vtx

application/vnd.visio

.vxml

text/xml

.wav

audio/wav

.wax

audio/x-ms-wax

.wb1

application/x-wb1

.wb2

application/x-wb2

.wb3

application/x-wb3

.wbmp

image/vnd.wap.wbmp

.wiz

application/msword

.wk3

application/x-wk3

.wk4

application/x-wk4

.wkq

application/x-wkq

.wks

application/x-wks

.wm

video/x-ms-wm

.wma

audio/x-ms-wma

.wmd

application/x-ms-wmd

.wmf

application/x-wmf

.wml

text/vnd.wap.wml

.wmv

video/x-ms-wmv

.wmx

video/x-ms-wmx

.wmz

application/x-ms-wmz

.wp6

application/x-wp6

.wpd

application/x-wpd

.wpg

application/x-wpg

.wpl

application/vnd.ms-wpl

.wq1

application/x-wq1

.wr1

application/x-wr1

.wri

application/x-wri

.wrk

application/x-wrk

.ws

application/x-ws

.ws2

application/x-ws

.wsc

text/scriptlet

.wsdl

text/xml

.wvx

video/x-ms-wvx

.xdp

application/vnd.adobe.xdp

.xdr

text/xml

.xfd

application/vnd.adobe.xfd

.xfdf

application/vnd.adobe.xfdf

.xhtml

text/html

.xlsx

application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

.xls

application/x-xls

.xlw

application/x-xlw

.xml

text/xml

.xpl

audio/scpls

.xq

text/xml

.xql

text/xml

.xquery

text/xml

.xsd

text/xml

.xsl

text/xml

.xslt

text/xml

.xwd

application/x-xwd

.x_b

application/x-x_b

.sis

application/vnd.symbian.install

.sisx

application/vnd.symbian.install

.x_t

application/x-x_t

.ipa

application/vnd.iphone

.apk

application/vnd.android.package-archive

.xap

application/x-silverlight-app

.zip

application/zip

.rar

application/x-rar-compressed

User-defined Object Metadata

You can add user-defined metadata headers that start with x-obs-meta- for easy object management. When you retrieve an object or query its metadata, any user-defined metadata added will appear in the response.

  • An object's checksum and its associated algorithm are stored as part of the object metadata. Metadata provides additional information about an object and is not included in the actual object content.
  • When you use a KMS key to encrypt an object, KMS encrypts only the actual content of the object. If you use OBS server-side encryption to encrypt an object, both the object's actual content and checksum are encrypted. The encrypted checksum is then stored in the object metadata. For more information about server-side encryption, see Server-Side Encryption Overview.
  • A checksum (the x-obs-meta-md5chksum user-defined metadata) is used to verify data integrity and consistency. It is usually calculated using an algorithm (for example, MD5).

User-defined object metadata must meet the following requirements:

  • All user-defined metadata is limited to 8 KB in size. The size of user-defined metadata is the sum of the number of bytes in the UTF-8 encoding of each key and value.
  • User-defined metadata keys are case insensitive, but OBS stores them in lowercase. The user-defined metadata values are case sensitive.

    Example:

    1
2
3
4
5
6
7
    		 
    PUT /key HTTP/1.1
Host: bucket01.obs.myhuaweicloud.com
x-obs-meta-Test1: Test Meta1

HEAD /Key HTTP/1.1
Host: bucket01.obs.myhuaweicloud.com
x-obs-meta-test1: Test Meta1
  • Both user-defined metadata keys and their values must conform to US-ASCII. If non-ASCII or unrecognizable characters are necessary, they must be encoded or decoded in URL or Base64 on the client side. The server side does not perform any decoding.

Constraints

  • In a versioning-enabled bucket, you can only configure metadata for the latest version of an object, but not for historical versions.
  • Metadata cannot be configured for Archive or Deep Archive objects.
  • The total size of user-defined metadata is limited to 8 KB.
  • For the permissions required to configure, edit, or view object metadata, see Object Actions.

Configuring Object Metadata

You can use OBS Console, APIs, SDKs, or obsutil to configure object metadata.

Using OBS Console

  1. In the navigation pane of OBS Console, choose Object Storage.
  2. In the bucket list, click the bucket you want to operate. The Objects page is displayed.
  3. Click the required object name to go to the object details page.
  4. On the Metadata tab, click Add and specify metadata information. For more information, see Metadata Introduction.

    Figure 1 Adding metadata

  5. Click OK.

Using APIs

Modifying Object Metadata

Using SDKs

Java

Python

C

Go

BrowserJS

.NET

Android

iOS

PHP

Node.js

Using the CLI Tool - obsutil

Command Line Structure

  • In Windows
    • Setting properties of a single object 
      obsutil chattri obs://bucket/key [-meta=aaa:bbb#ccc:ddd] [-sc=xxx] [-acl=xxx] [-aclXml=xxx] [-versionId=xxx] [-fr] [-o=xxx] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]
    • Setting properties of objects in batches 
      obsutil chattri obs://bucket[/key] -r [-f] [-v] [-meta=aaa:bbb#ccc:ddd] [-sc=xxx] [-acl=xxx] [-aclXml=xxx] [-o=xxx] [-j=1] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]
  • In Linux or macOS
    • Setting properties of a single object 
      ./obsutil chattri obs://bucket/key [-meta=aaa:bbb#ccc:ddd] [-sc=xxx] [-acl=xxx] [-aclXml=xxx] [-versionId=xxx] [-fr] [-o=xxx] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]
    • Setting properties of objects in batches 
      ./obsutil chattri obs://bucket[/key] -r [-f] [-v] [-meta=aaa:bbb#ccc:ddd] [-sc=xxx] [-acl=xxx] [-aclXml=xxx] [-o=xxx] [-j=1] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]

Examples

  • Take the Windows OS as an example, run the obsutil chattri obs://bucket-test/key -acl=public-read command to set the access permission to an object to public read. 
    obsutil chattri obs://bucket-test/key -acl=public-read
Start at 2024-09-30 08:17:15.5572914 +0000 UTC

Set the acl of object [key] in the bucket [bucket-test] to [public-read] successfully, request id [04050000016836DDFA73B2B5320E2651]
  • Take the Windows OS as an example, run the obsutil chattri obs://bucket-test -r -f -acl=public-read command to set the access permission to all objects in the bucket to public read. 
    obsutil chattri obs://bucket-test -r -f -acl=public-read
Start at 2024-09-30 08:18:03.105373 +0000 UTC

[------------------------------------------------] 100.00% tps:155.15 5/5 233ms
Succeed count:   5         Failed count:    0
Metrics [max cost:177 ms, min cost:53 ms, average cost:102.40 ms, average tps:20.41]
Task id: 9d7f73ff-f747-4fdd-9b2a-815ba2dc3b07

Parameter Description

Parameter

Optional or Mandatory

Description

bucket

Mandatory

The name of the bucket to which an object belongs

key

Mandatory when setting properties of an object.

Optional when setting properties of objects in batches.

The name of the object whose properties are to be set, or the name prefix of objects whose properties are to be set in batches

If this parameter is left blank during batch operation, properties of all objects in the bucket are set.

meta

Optional (additional parameter)

The standard or user-defined metadata that can be specified for an object when setting properties of the object

  • Standard metadata includes Content-Type, Content-Encoding, Cache-Control, Content-Disposition, Content-Language and Expires.
  • User-defined metadata must be in the format of key:value. Multiple user-defined metadata items are separated by number signs (#), for example, key1:value1#key2:value2#key3:value3, which indicates that the object whose properties are set contains three groups of user-defined metadata: key1:value1, key2:value2, and key3:value3.

This parameter must be used together with direct.

direct

Optional (additional parameter)

The metadata operation indicator

The value can be:

  • REPLACE_NEW: The existing metadata value is replaced with a new one, the metadata lacking a value is assigned one, and the metadata not specified keeps unchanged.
  • REPLACE: The metadata is replaced with the header included in the current request and the metadata not specified is deleted.

This parameter must be used together with meta.

sc

Optional (additional parameter)

The storage class of an object. Possible values are:

  • standard: Standard storage class. It features low access latency and high throughput, and is applicable to storing frequently accessed data (multiple accesses per month) or data that is smaller than 1 MB.
  • warm: Infrequent Access storage class. It is ideal for storing infrequently accessed (less than 12 times a year) data, but when needed, the access has to be fast.
  • cold: Archive storage class. It provides secure, durable, and inexpensive storage for rarely-accessed (once a year) data.
  • deep-archive: Deep Archive storage class (under limited beta testing). It is suitable for storing data that is barely (once every few years) accessed. This storage class costs less than the Archive storage class, but takes longer time (usually several hours) to restore data.

For an object whose storage class is cold, restore the object first and then specify its storage class. To restore an object, see Restoring Objects from the Archive Storage.

acl

Optional (additional parameter)

The predefined access control policy of an object. Possible values are:

  • private
  • public-read
  • public-read-write
  • bucket-owner-full-control

aclXml

Optional (additional parameter)

The bucket's access control policy, in XML format. The format is as follows:

<AccessControlPolicy>
    <Owner>
        <ID>ownerid</ID>
    </Owner>
    <AccessControlList>
        <Grant>
            <Grantee>
                <ID>userid</ID>
            </Grantee>
            <Permission>[WRITE|WRITE_ACP|READ|READ_ACP|FULL_CONTROL]</Permission>
        </Grant>
        <Grant>
            <Grantee>
                <Canned>Everyone</Canned>
            </Grantee>
            <Permission>[WRITE|WRITE_ACP|READ|READ_ACP|FULL_CONTROL]</Permission>
        </Grant>
    </AccessControlList>
</AccessControlPolicy>
  • Owner: Optional. Specify the object owner's ID.
  • In AccessControlList, the Grant field contains the authorized users. Grantee specifies the IDs of authorized users. Canned specifies the authorized user group (currently, only Everyone is supported).
  • The following permissions can be granted:
    • WRITE: the write permission
    • WRITE_ACP: the write permission for the ACL
    • READ: the read permission
    • READ_ACP: the read permission for the ACL
    • FULL_CONTROL: the full control permission

Because angle brackets (<) and (>) are unavoidably included in the parameter value, you must use quotation marks to enclose them for escaping when running the command. Use single quotation marks for Linux or macOS and double quotation marks for Windows.

fs

Optional (additional parameter)

Whether the method of listing parallel file systems is applied. If you are listing parallel file systems, you are recommended to add this parameter.

  • After this parameter is enabled, marker and limit will be ignored. Then, the size of the bucket, parallel file system, or directory will be calculated.
  • This parameter is only supported by obsutil 5.5.12 and later.
  • With this method, the listing time required varies largely depending on the directory structures.

versionId

Optional when setting properties of an object (additional parameter)

The version ID of the object whose properties are to be set

fr

Optional when setting properties of an object (additional parameter)

Generates an operation result file when setting properties of an object.

f

Optional when setting properties of objects in batches (additional parameter)

Runs in force mode.

r

Mandatory when setting properties of objects in batches (additional parameter)

Sets properties of objects in batches based on a specified object name prefix.

v

Optional when setting properties of objects in batches (additional parameter)

Sets properties of versions of objects in batches based on a specified object name prefix.

o

Optional (additional parameter)

The folder that stores the result files. After the command is executed, result files (including success and failure files) will be created in the specified folder.

The default value is .obsutil_output, a subfolder in the user's home directory where obsutil commands are executed.

  • A result file should be named as follows: cp_{succeed | failed | warning}_report_time_TaskId.txt.
  • By default, the maximum size of a single result file is 30 MB. You can set the maximum size by configuring recordMaxLogSize in the configuration file.
  • By default, the maximum number of result files that can be retained is 1,024. You can set the maximum number by configuring recordBackups in the configuration file.
  • If there are multiple folders and files and you need to confirm the details of a failed task, refer to the failure result file chattri_failed_report_time_TaskId.txt in the result folder and the log files in the log path.

j

Optional when setting properties of objects in batches (additional parameter)

The maximum number of concurrent tasks for setting object properties in batches. The default value is the value of defaultJobs in the configuration file.

NOTE:

The value is ensured to be greater than or equal to 1.

config

Optional (additional parameter)

The user-defined configuration file for executing the current command. To learn the parameters that can be configured in this file, see Configuration Parameters.

e

Optional (additional parameter)

The endpoint

i

Optional (additional parameter)

The user's AK

k

Optional (additional parameter)

The user's SK

t

Optional (additional parameter)

The user's security token

Only one from acl, sc, or aclXml can be set for each command.

Response

Field

Description

Parallel

The parameter -p in the request

Jobs

The parameter -j in the request

Threshold

The parameter -threshold in the request

PartSize

The parameter -ps in the request

Exclude

The parameter -exclude in the request

Include

The parameter -include in the request

TimeRange

The parameter -timeRange in the request

VerifyLength

The parameter -vlength in the request

VerifyMd5

The parameter -vmd5 in the request

CheckpointDir

The parameter -cpd in the request

OutputDir

The parameter -o in the request

ArcDir

The parameter -arcDir in the request

Succeed count

The number of successful tasks

Failed count

The number of failed tasks

Skip count

The number of tasks that are skipped during incremental upload, download, or copy, and synchronous upload, download, or copy.

NOTE:

Skipped tasks are recorded into successful tasks.

Warning count

The number of tasks that are executed successfully but contain warnings.

NOTE:
  • The task for which a warning is generated may be a failure or a success, which needs to be further determined according to the corresponding result list.
  • The number of tasks that generate warnings is independent of the number of successful or failed tasks. The total number of tasks is the number of successful tasks plus the number of failed tasks.

Succeed bytes

The number of bytes that are successfully uploaded or downloaded.

max cost

The maximum duration of all tasks, in ms

min cost

The minimum duration of all tasks, in ms

average cost

The average duration of all tasks, in ms

average tps

The average number of tasks completed per second

Task id

The unique ID of an operation, which is used to search for the result file generated for a batch task

Editing Object Metadata

You can use OBS Console, APIs, SDKs, or obsutil to edit object metadata.

Using OBS Console

  1. In the navigation pane of OBS Console, choose Object Storage.
  2. In the bucket list, click the bucket you want to operate. The Objects page is displayed.
  3. Click the required object name to go to the object details page.
  4. On the Metadata tab, click Edit in the Operation column of the metadata to be edited.

    Figure 2 Editing the object metadata

  5. Change the metadata value and click OK. For more information, see Metadata Introduction.

Using APIs

Modifying Object Metadata

Using SDKs

Java

Python

C

Go

BrowserJS

.NET

Android

iOS

PHP

Node.js

Using the CLI Tool - obsutil

Command Line Structure

  • In Windows
    • Setting properties of a single object 
      obsutil chattri obs://bucket/key [-meta=aaa:bbb#ccc:ddd] [-sc=xxx] [-acl=xxx] [-aclXml=xxx] [-versionId=xxx] [-fr] [-o=xxx] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]
    • Setting properties of objects in batches 
      obsutil chattri obs://bucket[/key] -r [-f] [-v] [-meta=aaa:bbb#ccc:ddd] [-sc=xxx] [-acl=xxx] [-aclXml=xxx] [-o=xxx] [-j=1] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]
  • In Linux or macOS
    • Setting properties of a single object 
      ./obsutil chattri obs://bucket/key [-meta=aaa:bbb#ccc:ddd] [-sc=xxx] [-acl=xxx] [-aclXml=xxx] [-versionId=xxx] [-fr] [-o=xxx] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]
    • Setting properties of objects in batches 
      ./obsutil chattri obs://bucket[/key] -r [-f] [-v] [-meta=aaa:bbb#ccc:ddd] [-sc=xxx] [-acl=xxx] [-aclXml=xxx] [-o=xxx] [-j=1] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]

Examples

  • Take the Windows OS as an example, run the obsutil chattri obs://bucket-test/key -acl=public-read command to set the access permission to an object to public read. 
    obsutil chattri obs://bucket-test/key -acl=public-read
Start at 2024-09-30 08:17:15.5572914 +0000 UTC

Set the acl of object [key] in the bucket [bucket-test] to [public-read] successfully, request id [04050000016836DDFA73B2B5320E2651]
  • Take the Windows OS as an example, run the obsutil chattri obs://bucket-test -r -f -acl=public-read command to set the access permission to all objects in the bucket to public read. 
    obsutil chattri obs://bucket-test -r -f -acl=public-read
Start at 2024-09-30 08:18:03.105373 +0000 UTC

[------------------------------------------------] 100.00% tps:155.15 5/5 233ms
Succeed count:   5         Failed count:    0
Metrics [max cost:177 ms, min cost:53 ms, average cost:102.40 ms, average tps:20.41]
Task id: 9d7f73ff-f747-4fdd-9b2a-815ba2dc3b07

Parameter Description

Parameter

Optional or Mandatory

Description

bucket

Mandatory

The name of the bucket to which an object belongs

key

Mandatory when setting properties of an object.

Optional when setting properties of objects in batches.

The name of the object whose properties are to be set, or the name prefix of objects whose properties are to be set in batches

If this parameter is left blank during batch operation, properties of all objects in the bucket are set.

meta

Optional (additional parameter)

The standard or user-defined metadata that can be specified for an object when setting properties of the object

  • Standard metadata includes Content-Type, Content-Encoding, Cache-Control, Content-Disposition, Content-Language and Expires.
  • User-defined metadata must be in the format of key:value. Multiple user-defined metadata items are separated by number signs (#), for example, key1:value1#key2:value2#key3:value3, which indicates that the object whose properties are set contains three groups of user-defined metadata: key1:value1, key2:value2, and key3:value3.

This parameter must be used together with direct.

direct

Optional (additional parameter)

The metadata operation indicator

The value can be:

  • REPLACE_NEW: The existing metadata value is replaced with a new one, the metadata lacking a value is assigned one, and the metadata not specified keeps unchanged.
  • REPLACE: The metadata is replaced with the header included in the current request and the metadata not specified is deleted.

This parameter must be used together with meta.

sc

Optional (additional parameter)

The storage class of an object. Possible values are:

  • standard: Standard storage class. It features low access latency and high throughput, and is applicable to storing frequently accessed data (multiple accesses per month) or data that is smaller than 1 MB.
  • warm: Infrequent Access storage class. It is ideal for storing infrequently accessed (less than 12 times a year) data, but when needed, the access has to be fast.
  • cold: Archive storage class. It provides secure, durable, and inexpensive storage for rarely-accessed (once a year) data.
  • deep-archive: Deep Archive storage class (under limited beta testing). It is suitable for storing data that is barely (once every few years) accessed. This storage class costs less than the Archive storage class, but takes longer time (usually several hours) to restore data.

For an object whose storage class is cold, restore the object first and then specify its storage class. To restore an object, see Restoring Objects from the Archive Storage.

acl

Optional (additional parameter)

The predefined access control policy of an object. Possible values are:

  • private
  • public-read
  • public-read-write
  • bucket-owner-full-control

aclXml

Optional (additional parameter)

The bucket's access control policy, in XML format. The format is as follows:

<AccessControlPolicy>
    <Owner>
        <ID>ownerid</ID>
    </Owner>
    <AccessControlList>
        <Grant>
            <Grantee>
                <ID>userid</ID>
            </Grantee>
            <Permission>[WRITE|WRITE_ACP|READ|READ_ACP|FULL_CONTROL]</Permission>
        </Grant>
        <Grant>
            <Grantee>
                <Canned>Everyone</Canned>
            </Grantee>
            <Permission>[WRITE|WRITE_ACP|READ|READ_ACP|FULL_CONTROL]</Permission>
        </Grant>
    </AccessControlList>
</AccessControlPolicy>
  • Owner: Optional. Specify the object owner's ID.
  • In AccessControlList, the Grant field contains the authorized users. Grantee specifies the IDs of authorized users. Canned specifies the authorized user group (currently, only Everyone is supported).
  • The following permissions can be granted:
    • WRITE: the write permission
    • WRITE_ACP: the write permission for the ACL
    • READ: the read permission
    • READ_ACP: the read permission for the ACL
    • FULL_CONTROL: the full control permission

Because angle brackets (<) and (>) are unavoidably included in the parameter value, you must use quotation marks to enclose them for escaping when running the command. Use single quotation marks for Linux or macOS and double quotation marks for Windows.

fs

Optional (additional parameter)

Whether the method of listing parallel file systems is applied. If you are listing parallel file systems, you are recommended to add this parameter.

  • After this parameter is enabled, marker and limit will be ignored. Then, the size of the bucket, parallel file system, or directory will be calculated.
  • This parameter is only supported by obsutil 5.5.12 and later.
  • With this method, the listing time required varies largely depending on the directory structures.

versionId

Optional when setting properties of an object (additional parameter)

The version ID of the object whose properties are to be set

fr

Optional when setting properties of an object (additional parameter)

Generates an operation result file when setting properties of an object.

f

Optional when setting properties of objects in batches (additional parameter)

Runs in force mode.

r

Mandatory when setting properties of objects in batches (additional parameter)

Sets properties of objects in batches based on a specified object name prefix.

v

Optional when setting properties of objects in batches (additional parameter)

Sets properties of versions of objects in batches based on a specified object name prefix.

o

Optional (additional parameter)

The folder that stores the result files. After the command is executed, result files (including success and failure files) will be created in the specified folder.

The default value is .obsutil_output, a subfolder in the user's home directory where obsutil commands are executed.

  • A result file should be named as follows: cp_{succeed | failed | warning}_report_time_TaskId.txt.
  • By default, the maximum size of a single result file is 30 MB. You can set the maximum size by configuring recordMaxLogSize in the configuration file.
  • By default, the maximum number of result files that can be retained is 1,024. You can set the maximum number by configuring recordBackups in the configuration file.
  • If there are multiple folders and files and you need to confirm the details of a failed task, refer to the failure result file chattri_failed_report_time_TaskId.txt in the result folder and the log files in the log path.

j

Optional when setting properties of objects in batches (additional parameter)

The maximum number of concurrent tasks for setting object properties in batches. The default value is the value of defaultJobs in the configuration file.

NOTE:

The value is ensured to be greater than or equal to 1.

config

Optional (additional parameter)

The user-defined configuration file for executing the current command. To learn the parameters that can be configured in this file, see Configuration Parameters.

e

Optional (additional parameter)

The endpoint

i

Optional (additional parameter)

The user's AK

k

Optional (additional parameter)

The user's SK

t

Optional (additional parameter)

The user's security token

Only one from acl, sc, or aclXml can be set for each command.

Response

Field

Description

Parallel

The parameter -p in the request

Jobs

The parameter -j in the request

Threshold

The parameter -threshold in the request

PartSize

The parameter -ps in the request

Exclude

The parameter -exclude in the request

Include

The parameter -include in the request

TimeRange

The parameter -timeRange in the request

VerifyLength

The parameter -vlength in the request

VerifyMd5

The parameter -vmd5 in the request

CheckpointDir

The parameter -cpd in the request

OutputDir

The parameter -o in the request

ArcDir

The parameter -arcDir in the request

Succeed count

The number of successful tasks

Failed count

The number of failed tasks

Skip count

The number of tasks that are skipped during incremental upload, download, or copy, and synchronous upload, download, or copy.

NOTE:

Skipped tasks are recorded into successful tasks.

Warning count

The number of tasks that are executed successfully but contain warnings.

NOTE:
  • The task for which a warning is generated may be a failure or a success, which needs to be further determined according to the corresponding result list.
  • The number of tasks that generate warnings is independent of the number of successful or failed tasks. The total number of tasks is the number of successful tasks plus the number of failed tasks.

Succeed bytes

The number of bytes that are successfully uploaded or downloaded.

max cost

The maximum duration of all tasks, in ms

min cost

The minimum duration of all tasks, in ms

average cost

The average duration of all tasks, in ms

average tps

The average number of tasks completed per second

Task id

The unique ID of an operation, which is used to search for the result file generated for a batch task

Viewing Object Metadata

You can use OBS Console, APIs, SDKs, or obsutil to view object metadata.

Using OBS Console

  1. In the navigation pane of OBS Console, choose Object Storage.
  2. In the bucket list, click the bucket you want to operate. The Objects page is displayed.
  3. Click the required object name to go to the object details page.
  4. On the Metadata tab, view the object metadata.

Using APIs

Querying Object Metadata

Using SDKs

Java

Python

C

Go

BrowserJS

.NET

Android

iOS

PHP

Node.js

Using the CLI Tool - obsutil

Command Line Structure

  • In Windows 
    obsutil stat obs://bucket/key [-acl][-bf=xxx] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]
  • In Linux or macOS 
    ./obsutil stat obs://bucket/key [-acl][-bf=xxx] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]

Examples

  • Take the Windows OS as an example. Run the obsutil stat obs://bucket-test/key command to query the basic properties of an object. 
    obsutil stat obs://bucket-test/key

Start at 2024-09-25 04:48:10.1147483 +0000 UTC

Key:
  obs://bucket-test/key
LastModified:
  2018-11-16T02:15:49Z
Size:
  7
StorageClass:
  standard
ETag:
  43d93b553855b0e1fc67e31c28c07b65
ContentType:
  text/plain
Type:
  file
Metadata:
  key=value

Parameter Description

Parameter

Optional or Mandatory

Description

bucket

Mandatory

The name of the bucket to which an object belongs

key

Mandatory

The name of the object whose attributes are to be queried

acl

Optional

Queries the access control policies of the object at the same time.

bf

Optional (additional parameter)

The display format of the object size (in bytes). Possible values are:

  • human-readable: The object size is displayed in a human-readable format. For example, the object size is displayed in KB, MB, GB, or TB (for instance, 1 GB), rather than in bytes (for instance, 1,073,741,824 bytes, which is a very large number).
  • raw: The number of bytes is displayed without any conversion or formatting. For example, if the space occupied by an object is 1 GB, the object size is displayed as 1,073,741,824 bytes.

For common users, the human-readable format is easier to understand. For scenarios where accurate calculation or automatic processing is required, the raw format is more suitable.

If this parameter is not configured, the display format of the object size (in bytes) is determined by the humanReadableFormat parameter in the configuration file.

config

Optional (additional parameter)

The user-defined configuration file for executing the current command. To learn the parameters that can be configured in this file, see Configuration Parameters.

e

Optional (additional parameter)

The endpoint

i

Optional (additional parameter)

The user's AK

k

Optional (additional parameter)

The user's SK

t

Optional (additional parameter)

The user's security token

Response

Field

Description

Key

The object name

LastModified

The latest modification time of the object

Size

The object size

Unit: byte

StorageClass

The storage class of the object

Possible values are:

  • standard: Standard storage class. It features low access latency and high throughput, and is applicable to storing frequently accessed data (multiple accesses per month) or data that is smaller than 1 MB.
  • warm: Infrequent Access storage class. It is ideal for storing infrequently accessed (less than 12 times a year) data, but when needed, the access has to be fast.
  • cold: Archive storage class. It provides secure, durable, and inexpensive storage for rarely-accessed (once a year) data. For an object whose storage class is cold, restore the object first and then specify its storage class.
  • deep-archive: Deep Archive storage class (under limited beta testing). It is suitable for storing data that is barely (once every few years) accessed. This storage class costs less than the Archive storage class, but takes longer time (usually several hours) to restore data.

MD5

Real MD5 of the object. This parameter is used to ensure and verify data integrity.

You can query this value only after running the cp command and configuring the -vmd5 parameter.

ETag

The ETag value of an object calculated on the server

ContentType

The file type of an object. It determines the format and encoding method a browser will use to read the file.

For details about common ContentType values, see Content-Type Introduction.

Type

The file type

Metadata

The user-defined metadata of the object. This field can be queried only when the object has user-defined metadata.

For details about user-defined object metadata, see User-defined Object Metadata.
Parent Topic: Object Management