Object Overview

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.

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 or 1/./obj

If you use APIs, SDKs, or OBS Browser+ 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 ../ and ./ has special semantics in URIs, avoid using them in object keys. In addition, if an object name contains ../ or ./, this object cannot be edited on OBS Console, for example, transitioning storage classes or configuring lifecycle rules.

Object names cannot start with consecutive periods (..) or a single period (.).