OSS supports a subset of Amazon Simple Storage Service (Amazon S3) API operations, so you can use S3-compatible SDKs and tools to access OSS. This page lists the supported operations and describes where OSS behavior differs from S3.
For API calls using the S3 protocol, thex-oss-processparameter supports onlyimage/andstyle/processing types. Other types, such asvideo/, are not supported.
Compatible S3 API operations
The following tables list the S3 bucket, object, and multipart upload operations that OSS supports.
Bucket operations
| Operation |
|---|
| PutBucket |
| DeleteBucket |
| GetBucket (ListObjects) |
| GetBucketV2 (ListObjectsV2) |
| GetBucketACL |
| GetBucketLifecycle |
| GetBucketLocation |
| GetBucketLogging |
| HeadBucket |
| PutBucketACL |
| PutBucketLifecycle |
| PutBucketLogging |
Object operations
| Operation |
|---|
| DeleteObject |
| DeleteObjects |
| GetObject |
| GetObjectACL |
| HeadObject |
| PostObject |
| PutObject |
| PutObjectCopy |
| PutObjectACL |
Multipart upload operations
| Operation |
|---|
| InitiateMultipartUpload |
| AbortMultipartUpload |
| CompleteMultipartUpload |
| ListParts |
| UploadPart |
| UploadPartCopy |
Differences between OSS and S3
The following sections describe where OSS behavior differs from S3 and what adjustments are required.
Request style
S3 supports two request addressing styles:
Virtual-hosted style — the bucket name is a subdomain of the endpoint:
https://<bucket-name>.s3.amazonaws.comPath style — the bucket name is in the URL path:
https://s3.amazonaws.com/<bucket-name>
OSS supports only virtual-hosted style. After migrating to OSS, configure all client applications and S3-compatible tools to use virtual-hosted style requests. Path-style requests are denied.
Access control lists (ACLs)
OSS and S3 define access control list (ACL) permissions differently at both the bucket and object level.
Bucket-level ACLs
| Permission | S3 | OSS |
|---|---|---|
| READ | List buckets | If no object permissions are configured for an object in a bucket, you can perform only read operations on the object |
| WRITE | Write or overwrite objects in the bucket | Create objects that don't already exist; overwrite existing objects that have no object-level ACL; initiate multipart uploads |
| READ_ACP | Read the bucket ACL | Only the bucket owner and authorized RAM users can read the bucket ACL |
| WRITE_ACP | Set the bucket ACL | Only the bucket owner and authorized RAM users can set the bucket ACL |
Object-level ACLs
| Permission | S3 | OSS |
|---|---|---|
| READ | Read the object | Read the object |
| WRITE | N/A | Overwrite the object |
| READ_ACP | Read the object ACL | Only the bucket owner and authorized RAM users can read the object ACL |
| WRITE_ACP | Set the object ACL | Only the bucket owner and authorized RAM users can set the object ACL |
OSS supports only the following S3 canned ACL modes: private, public-read, and public-read-write.
Storage classes
The following table maps S3 storage class codes to their OSS equivalents.
| S3 storage class | S3 code | OSS storage class |
|---|---|---|
| Standard | STANDARD | Standard |
| Infrequent Access (IA) | STANDARD_IA | Infrequent Access (IA) |
| Archive | GLACIER | Archive |
You can convert the storage class of OSS objects based on your requirements.
Archive object access
If real-time access of Archive objects is not enabled for a bucket, restore Archive objects before accessing them. OSS ignores the restoration duration specified in S3 API operations. By default, the restored state lasts one day and can be extended to a maximum of seven days, after which the object returns to the frozen state.
ETag
OSS and S3 produce ETags differently in two cases:
PUT uploads — OSS ETags use uppercase letters; S3 ETags use lowercase letters. If your client validates content using ETags, configure it to ignore case sensitivity.
Multipart uploads — OSS calculates ETag values using a different algorithm from S3. ETags for multipart-uploaded objects will not match between the two services.