本文主要介绍分层命名空间支持的 API 情况。分层桶与扁平桶共通绝大部分 API，您可以参考本文，了解分层桶与扁平桶之间的 API 差异。如果该 API 仅支持在分层桶中使用，将在本文档中单独说明。

背景信息

本文仅介绍分层桶支持的 API 列表，关于其他访问方式支持的功能详情，请参见以下文档：

控制台功能列表（分层桶）

SDK 概览（分层桶）

工具概览（分层桶）

注意事项

关于表格中的标识，说明如下：

：表示支持该功能。

：表示部分支持，具体支持情况请参考备注。

：表示不支持该功能。

存储桶

分类	API 名称	功能	分层桶是否支持	说明
基础操作	CreateBucket	创建存储桶。	✅	头域 x-tos-az-redundancy仅支持携带 single-az（单 AZ 冗余）。请求新增头域x-tos-bucket-type（表示桶类型），参数类型 string，非必选参数，取值说明如下： fns：扁平桶。 hns：分层桶。不携带此消息头则默认创建 fns 桶。
		DeleteBucket	删除存储桶。	✅	-
		HeadBucket	查询桶元数据是否存在。	✅	分层桶：响应消息头携带头域x-tos-bucket-type，取值为 hns。扁平桶：响应消息头不携带头域x-tos-bucket-type。
		ListBuckets	列举所有桶。	✅	请求新增头域 x-tos-bucket-type，通过此消息头明确获取的列表内容。参数类型为 String，非必选参数，取值说明如下： hns：获取所有分层桶列表。 fns：获取所有扁平桶列表。不带此消息头则获取所有桶列表。响应消息中，新增BucketType，表示桶类型。参数类型为 String，取值说明如下： fns：扁平桶。 hns：分层桶。
		PutBucketStorageClass	设置桶默认存储类型。	✅	-
		GetBucketLocation	查询当前桶的地域信息。	✅	-
		GetBucketInfo	查询存储桶的配置信息。	✅	-
生命周期规则	PutBucketLifecycle	设置生命周期规则。	✅	由于分层桶不支持多版本，所以仅支持指定删除最新版本对象的过期属性。
		GetBucketLifecycle	查询生命周期规则。	✅	-
		DeleteBucketLifecycle	删除生命周期规则。	✅	-
访问跟踪	PutBucketAccessMonitor	为存储桶设置访问跟踪。	✅	-
访问跟踪		GetBucketAccessMonitor	获取访问跟踪的配置信息。	✅	-
桶 ACL	PutBucketACL	设置桶的访问控制权限。	✅	-
桶 ACL		GetBucketACL	获取指定桶的访问控制权限。	✅	-
跨域访问规则	PutBucketCORS	设置跨域访问规则。	✅	-
		GetBucketCORS	查询跨域访问规则。	✅	-
		DeleteBucketCORS	删除跨域访问规则。	✅	-
桶清单	PutBucketInventory	创建桶清单。	✅	-
		GetBucketInventory	查看桶清单。	✅	-
		ListBucketInventory	批量获取所有桶清单。	✅	-
		DeleteBucketInventory	删除指定的桶清单。	✅	-
桶策略	PutBucketPolicy	设置桶策略。	✅	-
		GetBucketPolicy	查询桶策略。	✅	-
		DeleteBucketPolicy	删除桶策略。	✅	-
回源规则	PutBucketMirrorBack	设置回源规则。	✅	-
		GetBucketMirrorBack	查询回源规则。	✅	-
		DeleteBucketMirrorBack	删除回源规则。	✅	-
存储桶复制	PutBucketReplication	设置跨区域复制规则和同区域复制规则。	❌	-
		GetBucketReplication	查询跨区域复制规则和同区域复制规则。	❌	-
		DeleteBucketReplication	删除跨区域复制规则和同区域复制规则。	❌	-
版本控制	PutBucketVersioning	设置版本控制。	❌	-
版本控制		GetBucketVersioning	获取版本控制状态。	❌	-
静态网站托管	PutBucketWebsite	设置静态网站托管规则。	✅	-
		GetBucketWebsite	查询静态网站托管规则。	✅	-
		DeleteBucketWebsite	删除静态网站托管规则。	✅	-
事件通知	PutBucketNotification	设置事件通知规则。	❌	-
		GetBucketNotification	查询事件通知规则。	❌	-
		PutBucketNotificationV2	设置事件通知规则。	❌	-
		GetBucketNotificationV2	查询事件通知规则。	❌	-
自定义域名	PutBucketCustomDomain	设置自定义域名。	✅	-
		GetBucketCustomDomain	查询自定义域名。	✅	-
		DeleteBucketCustomDomain	删除自定义域名。	✅	-
服务端加密	PutBucketEncryption	设置服务端加密。	❌	-
		GetBucketEncryption	获取服务端加密配置。	❌	-
		DeleteBucketEncryption	删除服务端加密配置。	❌	-
桶标签	PutBucketTagging	设置桶标签。	✅	-
		GetBucketTagging	获取指定桶的标签信息。	✅	-
		DeleteBucketTagging	删除指定桶的标签信息。	✅	-
重命名	PutBucketRename	开启 RenameObject 功能。	❌	分层桶默认支持 Rename 功能，不需要开启。
		GetBucketRename	查询是否开启 RenameObject 功能。	❌	分层桶默认支持 Rename 功能，不需要查询。
		DeleteBucketRename	关闭 RenameObject 功能。	❌	分层桶默认支持 Rename 功能，不需要关闭。
回收站	PutBucketTrash	开启回收站功能。	✅	仅分层命名空间支持回收站功能，详细说明请参见回收站。
回收站		GetBucketTrash	获取回收站详细信息。	✅	仅分层命名空间支持回收站功能，详细说明请参见回收站。
传输加速	PutBucketTransferAcceleration	开启或关闭传输加速。	✅	-
传输加速		GetBucketTransferAcceleration	获取传输加速配置信息。	✅	-
数据处理	Pm3u8	获取私有 m3u8 的下载授权。	❌	-
日志存储	PutBucketLogging	开启或关闭日志存储。	✅	-
日志存储		GetBucketLogging	获取日志存储的配置信息。	✅	-
AIGC	TextToImage	组合使用对象存储的图片处理功能和豆包的文生图模型。	❌	-
AIGC		ImageToImage	组合使用对象存储的图片处理功能和豆包的图生图模型。	❌	-
请求者付费	PutBucketRequestPayment	设置存储桶的付费模式。	✅	-
请求者付费		GetBucketRequestPayment	查看存储桶的付费模式。	✅	-
TLS 版本	PutBucketHttpsConfig	开启或关闭 TLS 版本设置功能。	✅	-
TLS 版本		GetBucketHttpsConfig	查看 TLS 版本。	✅	-

对象

分类	API 名称	功能	分层桶是否支持	说明
基础操作	CopyObject	复制对象。	✅	不支持携带头域 x-tos-server-side-encryption-*。支持头域 x-tos-storage-class ，但目录仅支持携带 STANDARD（标准存储）存储类型。不支持软拷贝，只支持硬拷贝。源和目的均为分层桶时，仅支持文件拷贝到文件，目录拷贝到目录，文件和目录无法相互拷贝。拷贝目录仅拷贝目录对象本身，无法递归拷贝子文件或子目录。源为扁平桶，目的为分层桶时，不支持源对象是目录格式的 key 的非空对象，拷贝为目录格式的 key 的对象。
		DeleteObject	删除对象。	✅	不支持删除非空目录。
		DeleteMultiObjects	批量删除对象。	✅	只支持删除文件，不支持删除目录。若批删请求中既有文件也有目录，则文件删除成功，目录删除失败。
		GetObject	获取对象。	✅	对象为目录时，响应携带头域x-tos-directory，取值为 true。上传文件后，GetObject 请求的响应头域 Etag 为为文件的 MD5，当文件发生修改写后，GetObject 请求的响应头域 Etag 为文件的crc64。请求的目标为目录时，响应头域不携带Etag。请求的 key 以/结尾时，若对象实际不是目录，返回 409。当存在与请求的 key 的中间层级目录同名的文件时，返回 409。
		HeadObject	查询对象是否存在。	✅	对象为目录时，响应头携带头域x-tos-directory，取值为true。上传文件后，HeadObject 请求的响应头域Etag为文件的 MD5，当文件发生修改写后，响应头域 Etag 为文件的 crc64。请求的目标为目录时，响应头域不携带 Etag。请求的key以 / 结尾时，若对象实际不是目录，返回 409。当存在与请求的key的中间层级目录同名的文件时，返回 409。
		AppendObject	追加写对象。	✔️	分层桶支持使用 ModifyObject 追加写对象，详情请参见 ModifyObject。
		ModifyObject	修改写对象。注意仅分层桶支持该接口。	✅	当前只支持追加写，即 append 的功能，需要传入合法的 offset；响应头域携带 x-next-modify-offset，作为下次修改写的offset。不支持对不存在的对象进行修改写，即不支持修改写上传对象。修改写需要指定 Content-Length，并且 Content-Length 必须大于0，即修改写必须要携带数据。当文件发生修改写后，HeadObject 和 GetObject 的响应头域 Etag 为文件的 crc64。响应头域携带 Etag，为本次上传数据的 md5。响应头域携带 crc64，为本次修改写后对象的 crc64。
		ListObjects	列举桶中对象。	✅	Query 必须携带delimiter，且取值必须为 /。
		ListObjectsV2	列举桶中对象 V2 版本。	✅	Query 必须携带delimiter，且取值必须为 /。
		ListObjectVersions	列举桶中所有对象的版本信息。	❌	-
		PutObject	上传对象。	✅	请求的 key 以 / 结尾时，服务端认为客户端需要操作的是目录；请求的 key 未以 / 结尾时，服务端则以实际的对象为准。文件和目录不支持相互覆盖。目录不支持覆盖，上传已经存在的目录时，返回 200，但目录不会被覆盖。携带目录格式的 key（即以 / 结尾）上传对象时，对象类型为目录；否则，对象类型为文件。中间目录不存在时，会自动创建中间目录。上传目录时，不支持携带数据。不支持 chunk 模式上传。支持头域 x-tos-storage-class ，但目录仅支持携带 STANDARD（标准存储）存储类型。
		PostObject	使用表单上传对象。	✅	请求的 key 以 / 结尾时，服务端认为客户端需要操作的是目录；请求的 key 未以 / 结尾时，服务端则以实际的对象为准。文件和目录不支持相互覆盖。目录不支持覆盖，上传已经存在的目录时，返回 200，但目录不会被覆盖。携带目录格式的 key（即以 / 结尾）上传对象时，对象类型为目录；否则，对象类型为文件。中间目录不存在时，会自动创建中间目录。上传目录时，不支持携带数据。支持 chunk 模式上传。支持头域 x-tos-storage-class ，但目录仅支持携带 STANDARD（标准存储）存储类型。
		SetObjectMeta	更新桶中已经上传的对象的元数据。	✅	-
		SetObjectExpires	为对象添加过期时间，或修改对象的过期时间。	✅	-
		RestoreObject	恢复归档、冷归档和深度冷归档对象。	✅	-
		RenameObject	重命名对象。	✅	不支持将一个目录重命名为一个已经存在的目录。
访问控制	PutObjectACL	设置对象的访问控制权限。	✅	-
访问控制		GetObjectACL	获取指定对象的访问控制权限。	✅	-
对象标签	PutObjectTagging	设置对象标签。	✅	-
		GetObjectTagging	查看对象标签信息。	✅	-
		DeleteObjectTagging	删除对象标签。	✅	-
抓取对象	FetchObject	从指定 URL 抓取资源，并将该资源存储到指定存储桶。	✅	-
		PutFetchTask	创建从指定 URL 抓取资源，并将该资源存储到指定存储桶的异步任务。	❌	-
		GetFetchTask	查询异步任务的详细信息。	❌	-
软链接	PutSymlink	创建软链接。	✅	-
软链接		GetSymlink	获取软链接对象信息。	✅	-

分片上传

API名称	功能	分层桶是否支持	说明
CreateMultipartUpload	初始化分片上传任务。	✅	请求的 key 不支持以 / 结尾；中间目录不存在时，会自动创建中间目录；目录不支持覆盖，上传对象的最后一级路径为已经存在的目录时，返回 409；支持头域 x-tos-storage-class ，但目录仅支持携带 STANDARD（标准存储）存储类型。
UploadPart	上传分片数据。	✅	不支持 chunk 模式上传。
CompleteMultipartUpload	合并上传整个对象的分片数据。	✅	-
AbortMultipartUpload	取消分片上传任务。	✅	-
UploadPartCopy	分片复制上传对象。	✅	不支持携带头域 x-tos-server-side-encryption-*。不支持软拷贝，只支持硬拷贝。源和目的均为分层桶时，仅支持文件拷贝到文件，目录拷贝到目录，文件和目录无法相互拷贝。拷贝目录仅拷贝目录对象本身，无法递归拷贝子文件或子目录。源为扁平桶，目的为分层桶时，不支持源对象是目录格式的 key 但非空，拷贝为目录格式的 key 的对象。
ListMultipartUploads	列举分片上传任务。	✅	-
ListParts	列举已经上传的分片。	✅	-

对象存储