API 列表（分层桶）--对象存储-火山引擎

文档中心

立即注册

导航

对象存储

API 列表（分层桶）

最近更新时间：2024.11.21 10:38:07首次发布时间：2024.07.08 16:10:14

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

背景信息

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

注意事项

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

✅ ：表示支持该功能。
✔️：表示部分支持，具体支持情况请参考备注。
❌ ：表示不支持该功能。

存储桶

分类	API 名称	功能	分层桶是否支持	差异说明
基础操作	CreateBucket	创建存储桶。	✅	头域 `x-tos-storage-class`仅支持携带 `STANDARD`（标准存储）存储类型。头域 `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	查询当前桶的地域信息。	✅
生命周期规则	PutBucketLifecycle	设置生命周期规则。	❌
	GetBucketLifecycle	查询生命周期规则。	❌
	DeleteBucketLifecycle	删除生命周期规则。	❌
桶 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	查询事件通知规则。	❌
自定义域名	PutBucketCustomDomain	设置自定义域名。	✅
	GetBucketCustomDomain	查询自定义域名。	✅
	DeleteBucketCustomDomain	删除自定义域名。	✅
服务端加密	PutBucketEncryption	设置服务端加密。	❌
	GetBucketEncryption	获取服务端加密配置。	❌
	DeleteBucketEncryption	删除服务端加密配置。	❌
桶标签	PutBucketTagging	设置桶标签。	✅
	GetBucketTagging	获取指定桶的标签信息。	✅
	DeleteBucketTagging	删除指定桶的标签信息。	✅
重命名	PutBucketRename	开启 RenameObject 功能。	❌	分层桶默认支持 Rename 功能，不需要开启。
	GetBucketRename	查询是否开启 RenameObject 功能。	❌	分层桶默认支持 Rename 功能，不需要查询。
	DeleteBucketRename	关闭 RenameObject 功能。	❌	分层桶默认支持 Rename 功能，不需要关闭。

对象

分类	API 名称	功能	分层桶是否支持	差异说明
基础操作	CopyObject	复制对象。	✅	不支持携带头域 `x-tos-server-side-encryption-*`。头域 `x-tos-storage-class` 仅支持标准存储类型。不支持软拷贝，只支持硬拷贝。源和目的均为分层桶时，仅支持文件拷贝到文件，目录拷贝到目录，文件和目录无法相互拷贝。拷贝目录仅拷贝目录对象本身，无法递归拷贝子文件或子目录。源为扁平桶，目的为分层桶时，不支持源对象是目录格式的 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 模式上传。
	PostObject	使用表单上传对象。	✅	请求的 key 以 `/` 结尾时，服务端认为客户端需要操作的是目录；请求的 key 未以 `/` 结尾时，服务端则以实际的对象为准。文件和目录不支持相互覆盖。目录不支持覆盖，上传已经存在的目录时，返回 200，但目录不会被覆盖。携带目录格式的 key（即以 `/` 结尾）上传对象时，对象类型为目录；否则，对象类型为文件。中间目录不存在时，会自动创建中间目录。上传目录时，不支持携带数据。支持 chunk 模式上传。
	SetObjectMeta	更新桶中已经上传的对象的元数据。	✅
	RestoreObject	恢复归档、冷归档和深度冷归档对象。	❌
	RenameObject	重命名对象。	✅	不支持将一个目录重命名为一个已经存在的目录。
访问控制	PutObjectACL	设置对象的访问控制权限。	✅
访问控制	GetObjectACL	获取指定对象的访问控制权限。	✅
对象标签	PutObjectTagging	设置对象标签。	✅
	GetObjectTagging	查看对象标签信息。	✅
	DeleteObjectTagging	删除对象标签。	✅
抓取对象	FetchObject	从指定 URL 抓取资源，并将该资源存储到指定存储桶。	❌
	PutFetchTask	创建从指定 URL 抓取资源，并将该资源存储到指定存储桶的异步任务。	❌
	GetFetchTask	查询异步任务的详细信息。	❌

分片上传

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