Definition
An object is the basic unit in Cloud Object Storage (COS) and is stored in a bucket (just like a photo stored in an album). You can manage objects through various means such as the Converge Cloud console, APIs, and SDKs. In API and SDK samples, an object name is in the format of <ObjectKey>.
Note:
Objects can be uploaded via Simple Upload or Multipart Upload.
- Use simple upload for objects less than 5 GB in size.
- Multipart upload is limited to no more than 10,000 parts (each in 5 GB) and a maximum object size of around 48.82 TB.
Each object consists of an object key (ObjectKey), an object value (Value), and object metadata (Metadata).
- ObjectKey: The unique identifier of an object in a bucket.
- Value: The size of the uploaded object.
- Metadata: A set of key-value pairs, which can be set when uploading an object.
Users can configure objects through the console.
- Searching for Objects
- Viewing Object Information
- Setting Object Access Permission
- Setting Custom Definition Headers
Object Key
Definition
An object in COS should have a valid object key, which is the unique identifier of the object in a bucket.
For example, in an object's access address examplebucket-1250000000.<Endpoint>/folder/picture.jpg, the object key is folder/picture.jpg.
Naming Conventions
- You can use any UTF-8 characters in an object key name. However, we recommend you use letters (a-z, or A-Z), digits (0-9), symbols (
-,!,_,.,*), and their combinations to ensure optimal compatibility with other applications. - The encoded length can be up to 850 bytes.
- An object key cannot contain certain ASCII control characters, including upward arrow (↑), downward arrow (↓), rightward arrow (→), and leftward arrow (←), corresponding to CAN (24), EM (25), SUB (26), and ESC (27) respectively.
For example, when accessingdocument.doc, the object key is:document.doc. The actual percent-encoded value converted according to URL Encode rules is%e6%96%87%e6%a1%a3.doc.
The following are examples of valid object key names:
- my-organization
- my.great_photos-2016/01/me.jpg
- videos/2016/birthday/video.wmv
Special Characters
Certain characters may need to be URL-encoded or referenced in the hexadecimal format. Some of them are non-printable characters, and your browser may not be able to handle them. Special handling is required for these characters. The characters that may require special handling are as follows:
| , | : | ; | = |
| & | $ | @ | + |
| ? | ASCII character ranges: 00–1F hexadecimal (0–-31 decimal) and 7F (127 decimal) | (Space) |
There are also some characters that require significant special handling to maintain consistency across all applications, so we recommend you avoid them directly. The characters to be avoided are as follows:
| ` | ^ | " | \ |
| { | } | [ | ] |
| ~ | % | # | \| |
| > | < | ASCII 128-255 decimal |
Related Description
Default access address
The access address of an object consists of a bucket access address and an object key in the format of [bucket domain name]/[object key].
For example, after you upload the exampleobject.txt object to the examplebucket-1250000000 bucket, the access address for exampleobject.txt is examplebucket-1250000000.<Endpoint>/exampleobject.txt.
Folder and directory
As COS comes with no folders or directories, it will not create a project folder for uploading the object project/a.txt. To make it easier for you to get started, COS simulates the display mode of folder or directory in the console. This is implemented by creating an empty object with a key value of project/ and displaying it as a traditional folder.
For example, when you upload the object project/doc/a.txt via APIs or SDKs, the delimiter / simulates the display mode of "folder", and you can see the folders project and doc in the console. The folder doc is displayed under the folder project and contains the file a.txt.
Note:
Objects in the bucket are evenly distributed among distributed clusters. Therefore, you cannot directly get the size of all objects with a specified object key prefix. Instead, you can accumulate the size of each object to get the full size.
Deleting folders and directories is relatively complicated as detailed below:
| Deletion Methods | Deletion | Result |
|---|---|---|
| Console. | Folder project |
All objects with the object key prefix project/ will be deleted. |
| Console. | Object project/doc/a.txt |
project and doc folders will remain |
| APIs and SDKs | Object project/ or project/doc/ |
Objects project/doc/*.txt will remain. If you want to delete the objects in the folder, use code traversal to delete them. |
Object Metadata
Definition
The HTTP header of an object is a string sent by the server before transmitting HTML data to the browser using the HTTP protocol. By modifying the HTTP header, you can change the response format of the page or convey configuration information, such as modifying the cache time. Modifying the HTTP header of an object does not modify the object itself.
There are two types of metadata: system metadata and user-defined metadata.
Note:
Modifying an object's HTTP header does not modify the object itself.
System Metadata
This refers to the attribute information of an object, such as object uploading or modification time.
| Name | Description |
|---|---|
| Date | Current date and time |
| Content-Length | The HTTP request content length (in bytes) defined in RFC 2616, commonly used for operations of the PUT type API. |
| Last-Modified | The creation date or last modified date of an object (whichever is later). |
| Content-MD5 | Base64-encoded 128-bit content MD5 checksum as defined in RFC 1864. This header is used to verify whether the file content has changed. |
| Authorization | Signature information that carries authentication information and is used to verify the validity of a request. For publicly readable files, this header is not needed. |
| x-cos-version-id | Object version. If versioning is enabled for a bucket, the version ID of the object will be returned. |
| ETag | The MD5 value of an object uploaded by calling PUT Object, or the unique ID of an object uploaded by multipart upload or a legacy API (which cannot perform check though). |
| Expect | HTTP request content length (bytes) defined in RFC 2616. |
| Connection | Indicates the network connection status between the client and the server. Enumerated values: keep-alive, close. |
Custom Metadata
This refers to the object's custom parameters, such as Content-Type, Cache-Control, Expires, and x-cos-meta-.
| Name | Description |
|---|---|
| Cache-Control | Cache policy defined in RFC 2616. It is saved as object metadata. |
| Content-Disposition/Encoding/Type | The content type (MIME) defined in RFC 2616 is saved as object metadata. |
| Expires | Expiration Time |
| x-cos-acl | Define Object's ACL attribute. Valid values: private, public-read-write, and public-read. Default value: private. |
| x-cos-grant-* | Grants the reading permission to the grantee. |
| x-cos-meta- * | // Allow user-defined header information, which will be returned as Object metadata, with a size limit of 2K. |
| x-cos-storage-class | Sets the storage class of the Object, with enumeration values: STANDARD, STANDARD_IA, ARCHIVE. Default value: STANDARD |
| x-cos-server-side-encryption | Specifies whether to enable server-side encryption for the object. If you use the COS primary key for encryption, fill in: AES256. |
Object Subresource
COS has subresources that are associated with buckets and objects. Subresources are subordinate to objects, so they do not exist on their own and are always associated with other entities (such as objects and buckets). An ACL (Access Control List) is the access control information list for a specific object, which is a subresource of the object in COS.
An access control list contains an authorization list that can identify the authorized person and the permissions granted to it to achieve access control over objects. When an object is created, ACL will identify the object owner who has full control over the object. The user can retrieve the object ACL or replace it with an updated authorization list.
Note:
Any updates to the ACL require replacing the existing ACL.
Access Permission
COS supports setting two types of permissions for objects: Public Permission and User Permission.
Public Permission: Include private read/write, public read/private write, and public read/write.
- Private read/write: Only the creator of the bucket and authorized accounts have read/write permission on the objects in the bucket. No one else has read/write permissions. The default access permission of a bucket is private read/write, which is recommended.
- Public read and private write: Anyone (including anonymous visitors) has read permission to objects in the bucket, but only the bucket creator and authorized accounts have write permission to objects in the bucket.
- Public read and write: anyone (including anonymous visitors) has read/write permission on the objects in the bucket, which is not recommended.
User Permissions: A root account has all the permissions (full control) for objects by default. In COS, you can also add sub-accounts that are granted permissions to read/write data and permissions, and even full control, which is the highest permission level.
Applicable Scenario
Set to allow public access to a specific object in a private read/write bucket, or set to require authentication to access a specific object in a public read/write bucket.