本文描述了数据从任何兼容 S3 协议存储迁移到 TOS 后的应用无缝切换方案、相关的注意事项,并提供了 TOS 兼容的 S3 协议接口详细说明。
火山引擎对象存储 TOS(以下简称 TOS)提供了对 AWS S3 协议(以下简称 S3 协议)的兼容性支持,因此将数据从任何兼容 S3 协议存储迁移到 TOS 后,可以将之前访问该兼容 S3 协议存储的应用几乎无缝地切换到 TOS。
TOS 兼容 S3 协议,因此您完全可以通过 AWS S3 SDK 或者其他支持 S3 协议的工具进行创建桶、上传对象等相关操作。
使用过程中带宽、QPS 等限制需要遵循 TOS 的约束限制,详情请参见 TOS 约束限制。
对于在兼容 S3 协议存储上已有数据的场景,应用切换前需要先将数据迁移到 TOS,然后再将应用的访问切换到 TOS。
您可以使用火山引擎存储迁移服务将兼容 S3 协议存储的数据迁移到 TOS,详细方案请参见存储迁移服务用户指南。
将数据从兼容 S3 协议存储迁移到 TOS 后,应用可以继续使用 AWS S3 SDK 或者其他支持 S3 协议的工具(例如 AWSCli、S3Browser、Postman等)访问 TOS,但需要注意以下事项:
访问域名选择
TOS 为 S3 协议提供了专属的访问域名(即 Endpoint),使用 S3 协议访问 TOS 时必须使用 S3 协议的专属域名。
注意
tos-s3-cn-beijing.ivolces.com
和 tos-s3-cn-beijing.volces.com
。域名区域差异
不同于 AWS S3 等云厂商支持全局域名(即 s3.amazonaws.com,任何区域的桶都可以通过该全局域名访问),TOS 仅支持区域域名(即 Region 域名),对于桶的访问必须使用对应的 Region 域名。例如,bucket-test1 和 bucket-test2 分别位于华北2(北京)和华南1(广州),则从外网访问这两个桶时必须分别使用 tos-s3-cn-beijing.volces.com
和 tos-s3-cn-guangzhou.volces.com
。
访问密钥获取
TOS 通过火山引擎 IAM 提供的访问密钥(即 AccessKey ID 和 AccessKey Secret)进行签名认证,使用各种支持 S3 协议的 SDK 和工具访问 TOS 时,需要配置从火山引擎 IAM 获取到的 AccessKey ID 和 AccessKey Secret,获取方法,请参见访问密钥。
请求方式设置
TOS 仅支持使用虚拟主机(即 VirtualHostStyle)的请求方式,不支持路径样式(即 PathStyle)的请求方式。因此使用各种支持 S3 协议的 SDK 和工具访问 TOS 时,请务必确保配置了 VirtualHostStyle 的请求方式。例如,使用 AWS S3 Java SDK 时,需要在客户端初始化时确保设置了禁用 PathStyle 的配置参数:AmazonS3Builder.withPathStyleAccessEnabled(false)
。
ACL 权限支持
TOS 与 S3 协议对 ACL 权限的定义完全一致,但是在对 ACL 的特性支持上 TOS 是 S3 协议的子集,详细区别可参见下表。
功能 | AWS S3 | TOS |
---|---|---|
请求头中携带 ACL 枚举(使用 | 支持 7 种枚举值:
| 支持 6 种枚举值,与 S3 协议对应的枚举值语义一致:
|
消息体中携带 ACL 配置 | Type 支持 3 种枚举值:
| Type 支持 2 种枚举值,与 S3 协议对应的枚举值语义一致:
|
存储类型对照
TOS 当前支持标准存储、低频访问存储、智能分层存储、归档闪回存储、归档存储、冷归档存储和深度冷归档存储,除深度冷归档存储外,其他存储类型属于 S3 协议的子集,对应关系如下:
AWS S3 | TOS |
---|---|
支持 9 种枚举值:
| 支持 6 种枚举值:
|
注意
使用 AWS-SDK 时,仍然按照 AWS-S3 定义的枚举值设置对象存储类型;使用 TOS-SDK 时,需要按照 TOS 定义的枚举值设置对象存储类型。
接口定义对照
TOS 确保了对 S3 协议常用接口,如 CreateBucket、ListBuckets、PutObject、GetObject、ListObjects 的完全兼容(详情请参见下表)。
注意
虽然 TOS 确保完全兼容 S3 协议的接口,但在特性实现上,TOS 接口通常是 S3 协议对应接口的子集,部分 S3 协议支持的参数,在请求 TOS 时可能会被忽略,实际使用时请您特别注意此类差异。
接口类型 | S3 协议接口名 | TOS 兼容性说明 |
---|---|---|
桶相关接口 | CreateBucket | 完全兼容。 |
HeadBucket | 完全兼容。 | |
DeleteBucket | 完全兼容。 | |
ListBuckets | 完全兼容。 | |
对象相关接口 | CopyObject | 该接口的请求参数和响应结果兼容 S3 协议,但只支持同区域的对象复制,不支持跨区域的对象复制。 |
DeleteObject | 完全兼容。 | |
DeleteObjects | 完全兼容,TOS 在说明文档上的接口名称为 DeleteMultiObjects。 | |
GetObject | 完全兼容。 | |
GetObjectAcl | 完全兼容,TOS 在说明文档上的接口名称为 GetObjectACL。 | |
HeadObject | 完全兼容。 | |
ListObjects | 完全兼容。 | |
ListObjectVersions | 完全兼容。 | |
PutObject | 完全兼容。 | |
PostObject | 完全兼容。 | |
PutObjectAcl | 完全兼容,TOS 在说明文档上的接口名称为 PutObjectACL。 | |
分片相关接口 | CreateMultipartUpload | 完全兼容。 |
UploadPart | 完全兼容。 | |
CompleteMultipartUpload | 该接口的请求参数和响应结果兼容 S3 协议,但只支持合并指定 UploadId 的所有已上传的分片,不支持仅合并部分已上传的分片。 | |
AbortMultipartUpload | 完全兼容。 | |
UploadPartCopy | 完全兼容。 | |
ListMultipartUploads | 完全兼容。 | |
ListParts | 完全兼容。 |