Help Center/ Object Storage Service/ User Guide/ Object Management/ Object Overview
Updated on 2024-05-31 GMT+08:00
View PDF

Object Overview

An object is the basic unit of data storage on OBS. It consists of object data and object metadata that describes object attributes. Data uploaded to OBS is stored as objects in buckets.

An object consists of data, metadata, and a key.
  • A key specifies the name of an object. An object key is a UTF-8 string up to 1,024 characters long. Each object is uniquely identified by a key within a bucket.
  • Metadata describes an object, and can be system-defined or user-defined. The metadata is a set of key-value pairs that are assigned to the object stored in OBS.
    • System-defined metadata is automatically assigned by OBS for processing objects. Such metadata includes Date, Content-Length, Last-Modified, Content-MD5, and more.
    • User-defined metadata is specified when you upload objects and is used to describe objects.
  • Data refers to the content of the object.

Generally, objects are managed as files. However, OBS is an object-based storage service and there is no concept of files and folders. For easy data management, OBS provides a method to simulate folders. By adding a slash (/) in an object name, for example, test/123.jpg, you can simulate test as a folder and 123.jpg as the name of a file under the test folder. However, the object key remains test/123.jpg.

When uploading an object, you can specify a storage class for it. If you do not specify a storage class, the object inherits the storage class of the bucket. After the object is uploaded, you can also change its storage class.

You can upload files (data) to a bucket in the ways you like based on your habits and service scenarios. OBS then stores the files as objects in the bucket. In OBS, buckets are located in different regions. No matter what method you use, you can access the same bucket and its resources in the same region.

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 reserved 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 (known as reserved purpose) in a URI and the character must be used for other purposes in the URI, this character must be percent-encoded. Use UTF-8 to encode non-ASCII characters. Otherwise, the names of the objects that are uploaded to OBS may be different from what is expected. For example, if reserved character "/" is used as the delimiter of path components in a URI, the character has a special meaning (separating a bucket name from an object name). If "/" is used in a component of the path in a URI, use three characters "%2F" or "%2f" to replace "/". The reserved character " " must be encoded as "%20". For example, the string "abc d" will be encoded as "abc%20d".

Characters That May Require Special Processing

Characters that require encoding in a key name

  • Ampersand (&)
  • Dollar sign ($)
  • Semicolon (;)
  • Colon (:)
  • Plus sign (+): OBS decodes plus signs (+) in a request URI into spaces. If an original object key name contains plus signs (+), it must be encoded into %2B before being put into the request URI.
  • Space: A large number of consecutive spaces may be lost in some cases.
  • 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 these characters 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 (<)
  • Number sign (#)
  • Vertical bar (|)

Note that OBS adopts a flat structure, where you create buckets and store objects in buckets. There are no sub-buckets or sub-folders 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 a key name prefix (bucket-log/ or cgvbs/) and separator (/) to display the folder structure, as shown in the following figure.

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

Assume that your bucket (companybucket) contains two objects with the following object keys:

  • obj
  • 1/../obj

If you call an API (for example, using the SDK) to obtain these two objects, you will successfully get them. If you use OBS Console to access them, you will actually get object obj based on the relative relationship. Since ../ has special semantics in URIs, avoid using it in object keys.

Object names starting with consecutive periods (..) are not allowed.

Parent topic: Object Management