文档中心

AWS S3 协议兼容性说明

最近更新时间：2024.01.15 15:20:44

首次发布时间：2022.10.10 18:01:02

火山引擎对象存储 TOS（以下简称 TOS）提供了对 AWS S3 协议（以下简称 S3 协议）的兼容性支持，因此将数据从任何兼容 S3 协议存储迁移到 TOS 后，可以将之前访问该兼容 S3 协议存储的应用几乎无缝地切换到 TOS。本文描述了该场景下的应用切换方案以及相关的注意事项，并提供了 TOS 兼容的 S3 协议接口详细说明，供您使用时参考。

约束限制

TOS 兼容 S3 协议，因此您完全可以通过 AWS S3 SDK 或者其他支持 S3 协议的工具进行创建桶、上传对象等相关操作。
使用过程中带宽、QPS 等限制需要遵循 TOS 的约束限制，详情请参见 TOS 约束限制。

应用切换方案

对于在兼容 S3 协议存储上已有数据的场景，应用切换前需要先将数据迁移到 TOS，然后再将应用的访问切换到 TOS。

步骤一：将数据迁移到 TOS

您可以使用火山引擎存储迁移服务将兼容 S3 协议存储的数据迁移到 TOS，详细方案请参见存储迁移服务用户指南。

步骤二：通过 S3 协议访问 TOS

将数据从兼容 S3 协议存储迁移到 TOS 后，应用可以继续使用 AWS S3 SDK 或者其他支持 S3 协议的工具（例如 AWSCli、S3Browser、Postman等）访问 TOS，但需要注意以下事项：

访问域名选择
TOS 为 S3 协议提供了专属的访问域名（即 Endpoint），使用 S3 协议访问 TOS 时必须使用 S3 协议的专属域名。
注意
- 不同于 AWS S3 等云厂商内外网域名一致的方案，TOS 为内外网提供了不同的访问域名。例如，通过内外网访问 TOS 华北2（北京）地域的 S3 协议域名分别为 tos-s3-cn-beijing.ivolces.com 和 tos-s3-cn-beijing.volces.com。
- TOS 支持的域名详情，请参见访问域名。
- TOS 仅支持 S3 协议的 V4 签名算法，不支持 V2 签名算法。
域名区域差异
不同于 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 枚举（使用 `x-amz-acl` 头域）	支持 7 种枚举值： private public-read public-read-write authenticated-read aws-exec-read bucket-owner-read bucket-owner-full-control	支持 6 种枚举值，与 S3 协议对应的枚举值语义一致： private public-read public-read-write authenticated-read bucket-owner-read bucket-owner-full-control
消息体中携带 ACL 配置	Type 支持 3 种枚举值： CanonicalUser AmazonCustomerByEmail Group 当 Type 为 Group 时，URI 支持 3 种枚举值： AllUsers：`http://acs.amazonaws.com/groups/global/AllUsers` AuthenticatedUsers：`http://acs.amazonaws.com/groups/global/AuthenticatedUsers` LogDelivery：`http://acs.amazonaws.com/groups/s3/LogDelivery`	Type 支持 2 种枚举值，与 S3 协议对应的枚举值语义一致： CanonicalUser Group 当 Type 为 Group 时，URI 支持 2 种枚举值，与 S3 协议对应的枚举值语义一致： AllUsers：`http://acs.amazonaws.com/groups/global/AllUsers` AuthenticatedUsers：`http://acs.amazonaws.com/groups/global/AuthenticatedUsers`

功能

AWS S3

TOS

请求头中携带 ACL 枚举（使用 x-amz-acl 头域）

支持 7 种枚举值：

private
public-read
public-read-write
authenticated-read
aws-exec-read
bucket-owner-read
bucket-owner-full-control

支持 6 种枚举值，与 S3 协议对应的枚举值语义一致：

private
public-read
public-read-write
authenticated-read
bucket-owner-read
bucket-owner-full-control

消息体中携带 ACL 配置

Type 支持 3 种枚举值：

CanonicalUser
AmazonCustomerByEmail
Group
当 Type 为 Group 时，URI 支持 3 种枚举值：
- AllUsers：http://acs.amazonaws.com/groups/global/AllUsers
- AuthenticatedUsers：http://acs.amazonaws.com/groups/global/AuthenticatedUsers
- LogDelivery：http://acs.amazonaws.com/groups/s3/LogDelivery

Type 支持 2 种枚举值，与 S3 协议对应的枚举值语义一致：

CanonicalUser
Group
当 Type 为 Group 时，URI 支持 2 种枚举值，与 S3 协议对应的枚举值语义一致：
- AllUsers：http://acs.amazonaws.com/groups/global/AllUsers
- AuthenticatedUsers：http://acs.amazonaws.com/groups/global/AuthenticatedUsers

存储类型对照
TOS 当前支持标准存储、低频访问存储、智能分层存储、归档闪回存储、归档存储、冷归档存储和深度冷归档存储，除深度冷归档存储外，其他存储类型属于 S3 协议的子集，对应关系如下：

AWS S3	TOS
支持 9 种枚举值： STANDARD REDUCED_REDUNDANCY STANDARD_IA ONEZONE_IA INTELLIGENT_TIERING GLACIER_IR GLACIER DEEP_ARCHIVE OUTPOSTS	支持 6 种枚举值： STANDARD：标准存储 IA：低频访问存储 INTELLIGENT_TIERING：智能分层存储 ARCHIVE_FR：归档闪回存储 ARCHIVE：归档存储 COLD_ARCHIVE：冷归档存储

AWS S3

TOS

支持 9 种枚举值：

STANDARD
REDUCED_REDUNDANCY
STANDARD_IA
ONEZONE_IA
INTELLIGENT_TIERING
GLACIER_IR
GLACIER
DEEP_ARCHIVE
OUTPOSTS

支持 6 种枚举值：

STANDARD：标准存储
IA：低频访问存储
INTELLIGENT_TIERING：智能分层存储
ARCHIVE_FR：归档闪回存储
ARCHIVE：归档存储
COLD_ARCHIVE：冷归档存储

注意

使用 AWS-SDK 时，仍然按照 AWS-S3 定义的枚举值设置对象存储类型；使用 TOS-SDK 时，需要按照 TOS 定义的枚举值设置对象存储类型。

接口定义对照
TOS 确保了对 S3 协议常用接口，如 CreateBucket、ListBuckets、PutObject、GetObject、ListObjects 的完全兼容（详情请参见下表）。
注意
虽然 TOS 确保完全兼容 S3 协议的接口，但在特性实现上，TOS 接口通常是 S3 协议对应接口的子集，部分 S3 协议支持的参数，在请求 TOS 时可能会被忽略，实际使用时请您特别注意此类差异。

附表：TOS 兼容 S3 协议的接口

接口类型	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	完全兼容。

约束限制

应用切换方案

步骤一：将数据迁移到 TOS

步骤二：通过 S3 协议访问 TOS

附表：TOS 兼容 S3 协议的接口