Help Center> Object Storage Service> Developer Guide> Using Objects> Object Metadata
View PDF

Object Metadata

Each object has the data, key, and metadata. An object key (or key name) can uniquely identify an object in a bucket. When you create an object, specify an object key because it uniquely identifies the object in the bucket. A key name is a sequence of Unicode characters, and its UTF-8 code contains up to 1024 bytes. Object metadata is a key-value pair. You can set the metadata when you upload an object. After the object is uploaded, you cannot modify its metadata. The only way to modify object metadata is to create an object copy and set metadata.

Guidelines on Naming Object Keys

Although any UTF-8 characters can be used in an object key name, naming object keys according to the following guidelines can help maximize the object keys' compatibility with other applications. Ways to analyze special characters vary with applications. The following guidelines help object key names substantially meet the requirements of DNS, web security characters, XML analyzers and other APIs.

The following character sets can be freely used in key names.

Alphanumeric characters (also known as unreserved characters)

[0-9a-zA-Z]

Special characters (also known as unreserved characters)

Exclamation mark (!)

Hyphen (-)

Underscore (_)

Period (.)

Asterisk (*)

Single quotation mark (')

Left bracket "("

Right bracket ")"

The following are examples of valid object key names:

4my-organization 
my.great_photos-2014/jan/myvacation.jpg 
videos/2014/birthday/video1.wmv

Percent-Encoding of Reserved Characters

If a reserved character has a special meaning (also known as reserved purpose) in a URI and the character must be used for other purposes in the URI, the character must be percent-encoded. Use UTF-8 to encode non-ASCII characters. Otherwise, object names may be different from expected after they are uploaded to OBS. For example, if the reserved character "/" is used as the delimiter of the path components in an URI, the reserved character has a special meaning (separating the bucket name from the object name). If a path component in an URI contains "/", use three characters "%2F" or "%2f" to replace it.

Characters That May Require Special Processing

Characters that require encoding in a key name

Ampersand ("&")

Dollar sign ("$")

Semicolon (";")

Colon (":")

Plus sign ("+")

Spaces: Spaces may be lost in some cases if there are multiple consecutive spaces.

Equality sign ("=")

At sign ("@")

Comma (",")

Question mark ("?")

ASCII characters: 00–1F in hexadecimal form (0–31 in decimal form) and 7F (127 in decimal form)
Avoid using the following characters in key names, because they require a lot of special processing to keep consistency across all applications. 
Backslash (\)
Left brace ({)
Non-printable ASCII characters (128–255 decimal characters)
Insert symbol (^)
Right brace (})
Percentage character (%)
Accent/Untick (`)
Right square bracket (])
Quotation mark
Greater than sign (>)
Left square bracket ([)
Tilde (~)
Less than sign (<)
Hashtag (#)
Vertical bar (|)

Note that the OBS adopts a flat structure, where you create buckets and store objects in buckets. No sub-buckets or sub-folders exist in the structure. However, you can use key name prefixes and delimiters to deduce the logical structure like OBS Console does. The folder concept is available on OBS Console. Assume that your bucket (companybucket) contains four objects with the following object keys:

bucket-log/log01.txt 
cgvbs/test1.txt 
2015-10-14_111756.png 
test1.txt

OBS Console uses the key name prefix (bucket-log/ and cgvbs/) and separator (/) to display the folder structure. as shown in the following figure.

The 2015-10-14_111756.png and key test1.txt keys do not have prefixes. Therefore, the objects appear at the root level of the bucket. If you open the cgvbs/ folder, you will see that it contains the test1.txt object.

Object Metadata

Metadata includes system metadata and user-defined metadata.

System metadata: OBS reserves a set of system metadata for each object in a bucket. OBS deals with the system metadata based on requirements. For example, OBS reserves object metadata such as creation time and size, and the metadata is part of object management.

  1. System metadata is classified into the following two types:
  • System-controlled metadata (such as the object creation date). Only OBS can change its value.
  • Other system metadata (such as the storage class configured for an object and the data that indicates whether encryption is enabled at the server end for an object). You can control values of such metadata. Assume that you own a bucket that is configured as a website and you may want to redirect a page request to another page or an external URL. In this example, the web page is the object in your bucket. The OBS stores the page redirection value as such system metadata whose value is controlled by you.

When creating an object, you can configure the values of these system metadata projects or update the values when needed.

Table 1 Object metadata defined by the system

Name

Description

Whether a User Can Change the Value

Content-Length

Object size, in bytes

No

Last-Modified

Date when the object was modified last time

No

Content-MD5

128-bit MD5 digest of the Base64 code of an object

No

x-obs-version-id

Object version. If versioning is enabled for a bucket, the bucket will specify a version ID for each added object. For more information, see content about object versioning.

No

x-obs-delete-marker

In the bucket where versioning is enabled, this Boolean value marks whether the object is a delete mark.

No

x-obs-storage-class

Storage class

No

x-obs-website-redirect-location

Redirecting requests of associated objects to other objects in the same bucket or external URLs

Yes
  1. Use-defined metadata

When uploading an object, you can also specify the metadata for the object. When you send a PUT or POST request to create an object, you provide the optional information in the form of key-value pairs. When you use REST APIs to upload objects, the optional user-defined metadata names must start with x-obs-meta- to differentiate them from other HTTP headers. When you use REST APIs to search for data elements, the prefix x-obs-meta- is returned.

  • When you use REST APIs to search for metadata, OBS lists namesake (case insensitive) headers and separates them with commas (,) in the list. If some metadata contains unprintable characters, the characters are not returned. However, the header x-obs-missing-meta and the number of metadata items that cannot be printed are returned together.
  • Do not use non-US-ASCII characters to avoid unnecessary troubles.
  • OBS uses lowercase letters to store user-defined metadata, but metadata values are case-sensitive. When you use REST and UTF-8 or send a POST request to upload objects based on browsers, key-value pairs must comply with US-ASCII.
  • The maximum size of a PUT request header is 8 KB. In a PUT request header, the maximum size of user-defined metadata is 2 KB. User-defined metadata is a group of key-value pairs. You can calculate the size of user-defined metadata by summarizing the total number of bytes in the UTF-8 codes of all keys and values.

OBS Storage Class

User-defined metadata x-obs-storage-class reserved by the system is used to set and record object storage classes. OBS supports three storage classes. For details about the application scenarios of three storage classes, see Storage Classes.

The tree storage classes are as follows:

  • Standard
  • Infrequent Access
  • Archive

In OBS, you can specify a storage class when uploading and copying an object. Use x-obs-storage-class in the request header to set a storage class for the object.

You can also modify the storage class of an existing object. Modifying the storage class of an object is the same as that of modifying the user-defined metadata.

OBS also allows you to modify the storage class of an object by configuring a life cycle management task. For details, see Object Lifecycle Management.

Parent topic: Using Objects