In Object Storage Service (OSS), an object is the basic unit of data storage — equivalent to a file. Documents, images, videos, and any other type of file are stored as objects inside a bucket.
Object components
Each object consists of four components:
| Component | Description |
|---|---|
| Key | The unique name of the object, used to identify and retrieve it. |
| Data | The actual content, stored as a sequence of bytes. |
| Object metadata | A set of key-value pairs describing the object's properties, such as last modification time and size. Custom metadata is also supported. |
| Version ID | A unique ID assigned to each version when versioning is enabled. Use version IDs to access or manage specific versions of an object. |
Object keys
Every object has a unique name called a key. For example, the key exampledir/example.jpg identifies the file example.jpg stored under the exampledir prefix.
In SDK documentation, the key may also be referred to asObjectKey,ObjectName, or object name. These terms are interchangeable.
Naming rules
| Rule | Details |
|---|---|
| Encoding | UTF-8 |
| Length | 1–1,023 bytes |
| Starting character | Cannot start with a forward slash (/) or backslash (\) |
| Case sensitivity | Keys are case-sensitive |
Naming recommendations
Use meaningful names. Include filenames, dates, or user IDs to make objects easier to find and understand.
Use prefixes to organize data. Group related objects under a common prefix such as a date, user ID, or region (for example,
logs/2026-03/,users/u001/).Ensure uniqueness. Add random numbers or UUIDs to avoid naming conflicts when multiple clients upload concurrently.
Naming examples
| Object location | Key |
|---|---|
exampleobject.txt in the root of examplebucket | exampleobject.txt |
exampleobject.jpg in the destdir directory | destdir/exampleobject.jpg |
Directories in OSS
OSS has no traditional directory structure. To simulate folders, OSS uses forward slashes (/) as delimiters in object keys. For example, consider a bucket with these objects:
photos/2026/trip.jpg
photos/2026/portrait.png
reports/q1-summary.pdf
readme.txtThe OSS console and tools like ossbrowser display photos/2026/, photos/, and reports/ as folders. The object readme.txt appears at the root level because its key has no prefix. The actual storage structure remains flat — the keys are exactly as listed.
For more information, see Manage directories.
Object types
OSS supports four object types based on how they are created. Once created, an object's type cannot be changed — a Normal object cannot be converted to a Multipart or Appendable object.
| Type | Created by | Typical use case |
|---|---|---|
| Normal | Simple upload | Single-request upload for files under 5 GB; general-purpose file storage |
| Multipart | Multipart upload | Large files split into parts and uploaded separately; supports resumable uploads |
| Appendable | Append upload | Append content directly to the end of an existing object |
| Symlink | PutSymlink operation | Symbolic links for quick access to frequently accessed objects |
Versioning behavior by object type
How OSS handles multiple uploads to the same key depends on both the object type and whether versioning is enabled.
Normal objects
Versioning disabled or suspended: The latest upload overwrites the previous one. Only the most recent object is retained.
Versioning enabled: Each upload creates a new version with a unique version ID. OSS determines the latest version based on upload start time.
Multipart objects
Versioning disabled or suspended: The combined multipart object overwrites the previous one. Only the most recently combined object is retained.
Versioning enabled: Each
CompleteMultipartUploadcall creates a new version with a unique version ID. The most recently combined object is designated as the latest version.
Appendable objects
Data is appended directly to the existing object regardless of versioning status. No new version is created.
Delete markers
When you call DeleteObject on an object in a versioning-enabled or versioning-suspended bucket:
Without a version ID: OSS creates a delete marker and sets it as the latest version. The object data is preserved and can be restored.
With a version ID: OSS deletes that specific version permanently. No delete marker is created.
Upload objects
| Method | Description |
|---|---|
| Simple upload | Use PutObject to upload a single file under 5 GB in one HTTP request. |
| Multipart upload | Split a large file into parts, upload them separately, then call CompleteMultipartUpload to combine them. |
| Resumable upload | Record upload progress in a checkpoint file. If the upload is interrupted, resume from the last checkpoint. |
| Upload callback | Include callback parameters in the upload request. OSS notifies your application server after the upload completes. |
| Direct client upload | Upload from a client directly to OSS, bypassing your application server to improve speed and reduce server load. |
| Form upload | Use PostObject to upload a file from an HTML form. Maximum file size is 5 GB. |
| Append upload | Append content to the end of an existing Appendable object. |
| RTMP-based stream ingest | Ingest H.264-encoded video and AAC-encoded audio streams over RTMP (Real-Time Messaging Protocol) for on-demand playback or livestreaming where latency is not critical. |
Download objects
| Method | Description |
|---|---|
| Simple download | Use GetObject to download an object in a single HTTP request. |
| Resumable download | Download a file in multiple parts starting from a specified position. Resume an interrupted download without starting over. |
| Signed URL download | Generate a signed URL to share an object with third parties for preview or download without exposing bucket credentials. |
| Conditional download | Download an object only if its content has changed, based on last modified time or ETag. Skips the download if the content is unchanged, avoiding unnecessary transfers. |
Manage objects
| Operation | Description |
|---|---|
| List objects | List objects alphabetically. Filter by prefix or limit the number of results returned. |
| Copy objects | Copy an object from one bucket to another within the same region without modifying the content. |
| Rename objects | Rename an object in a bucket. |
| Search for objects | Search for objects by filename prefix to locate a target file quickly. |
| Restore objects | Initiate a restore process before accessing objects in Cold Archive or Deep Cold Archive storage. |
| Delete objects | Delete objects you no longer need. |
| Tag objects | Assign tags to objects to classify them. Apply lifecycle rules and access permissions based on tags. |
| Create symbolic links | Create a symbolic link to provide quick access to a frequently used object. |
| Manage object metadata | Set HTTP headers (such as cache policy and content disposition) and user-defined metadata on objects. |
| Single-connection bandwidth throttling | Limit bandwidth per connection during upload and download to prevent OSS traffic from affecting other applications. |
| Query objects | Use SelectObject to run SQL queries directly on a file and retrieve results without downloading the entire object. |
| Delete parts | Call AbortMultipartUpload to delete incomplete parts from a multipart upload. |
| Use CSG to attach OSS buckets to ECS instances | Use Cloud Storage Gateway (CSG) to mount an OSS bucket as shared file storage on ECS instances, allowing multiple users to access OSS as a local file system. |