This document primarily introduces the APIs supported by hierarchical namespaces. HNS buckets and FNS buckets share most APIs. You can refer to this document to understand the differences in APIs between HNS and FNS buckets. If an API is only supported in HNS buckets, it will be specified separately in this document.

Background Information

This document only provides the list of APIs supported by HNS buckets. For details on features supported by other access methods, Console feature list (HNS buckets) Please refer to the following documents:

Console feature list (HNS buckets)

SDK overview (HNS buckets)

Tool overview (HNS buckets)

Notes

The meanings of the symbols in the table are as follows:

: Indicates that the feature is supported.

: Indicates partial support. For specific support details, please refer to the remarks.

: Indicates that the feature is not supported.

Bucket

Category	API	Feature	Is HNS bucket supported?	Difference
Basic operations	CreateBucket	Create a bucket.	✅	The header x-tos-az-redundancy only supports single-az (single AZ redundancy). Request to add the header x-tos-bucket-type (indicating bucket type), parameter type: string, optional parameter, value description as follows: fns: FNS bucket. hns: HNS bucket. If this header is not included, an FNS bucket is created by default.
		DeleteBucket	Delete bucket.	✅
		HeadBucket	Check whether bucket metadata exists.	✅	HNSThe response message header carries the header field x-tos-bucket-type with the value hns. FNS bucket: The response message header does not carry the header field x-tos-bucket-type.
		ListBuckets	List all buckets.	✅	The request adds a new header field x-tos-bucket-type, which specifies the content of the list to be obtained through this header. The parameter type is String; it is an optional parameter. The value description is as follows: hns: Obtain the list of all HNS buckets. fns: Obtain the list of all FNS buckets. If this header is not included, all bucket lists are obtained. The response message adds BucketType, indicating the bucket type. The parameter type is String; the value description is as follows: fns: FNS bucket. hns: HNS bucket.
		PutBucketStorageClass	Set default storage class for the bucket.	✅
		GetBucketLocation	Query the region information of the current bucket.	✅
		GetBucketInfo	Query bucket configuration information.	✅
Lifecycle rules	PutBucketLifecycle	Set lifecycle rules.	✅	Since HNSdo not support multiple versions, only the expiration attribute for deleting the latest version of an object can be specified.
		GetBucketLifecycle	Query lifecycle rules.	✅
		DeleteBucketLifecycle	Delete lifecycle rules.	✅
Access tracking	PutBucketAccessMonitor	Set access tracking for the bucket.	✅
Access tracking		GetBucketAccessMonitor	Obtain the configuration information for access tracking.	✅
Bucket ACL	PutBucketACL	Set bucket access control permissions.	✅
Bucket ACL		GetBucketACL	Obtain access control permissions for the specified bucket.	✅
Cross-origin access rule	PutBucketCORS	Set cross-origin access rules.	✅
		GetBucketCORS	Query cross-origin access rules.	✅
		DeleteBucketCORS	Delete cross-origin access rules.	✅
Bucket inventory	PutBucketInventory	Create bucket inventory.	✅
		GetBucketInventory	View bucket inventory.	✅
		ListBucketInventory	Batch retrieve all bucket inventory.	✅
		DeleteBucketInventory	Delete the specified Bucket inventory.	✅
Bucket policy	PutBucketPolicy	Set bucket policy.	✅
		GetBucketPolicy	Query bucket policy.	✅
		DeleteBucketPolicy	Delete bucket policy.	✅
Back-to-origin rule	PutBucketMirrorBack	Set back-to-origin rules.	✅
		GetBucketMirrorBack	Query origin fetch rules.	✅
		DeleteBucketMirrorBack	Delete origin-pull rules.	✅
Bucket replication	PutBucketReplication	Set cross-region replication rules and same-region replication rules.	❌
		GetBucketReplication	Query cross-region replication rules and same-region replication rules.	❌
		DeleteBucketReplication	Delete cross-region replication rules and same-region replication rules.	❌
Version Control	PutBucketVersioning	Set versioning.	❌
Version Control		GetBucketVersioning	Get versioning status.	❌
Static website hosting	PutBucketWebsite	Set static website hosting rules.	✅
		GetBucketWebsite	Query static website hosting rules.	✅
		DeleteBucketWebsite	Delete static website hosting rules.	✅
Event notification	PutBucketNotification	Set event notification rules.	❌
		GetBucketNotification	Query event notification rules.	❌
		PutBucketNotificationV2	Set event notification rules.	❌
		GetBucketNotificationV2	Query event notification rules.	❌
Custom domain name	PutBucketCustomDomain	Set custom domain name.	✅
		GetBucketCustomDomain	Query custom domain name.	✅
		DeleteBucketCustomDomain	Delete custom domain name.	✅
Server-side encryption	PutBucketEncryption	Set server-side encryption.	❌
		GetBucketEncryption	Retrieve server-side encryption configuration.	❌
		DeleteBucketEncryption	Delete server-side encryption configuration.	❌
Bucket tags	PutBucketTagging	Set bucket tags.	✅
		GetBucketTagging	Get the tag information of the specified bucket.	✅
		DeleteBucketTagging	Delete the tag information for the specified bucket.	✅
Rename	PutBucketRename	Enable RenameObject feature.	❌	HNS buckets support the Rename feature by default; no activation is required.
		GetBucketRename	Query whether the RenameObject feature is enabled.	❌	HNS buckets support the Rename feature by default; no query is required.
		DeleteBucketRename	Disable the RenameObject feature.	❌	HNS buckets support the Rename feature by default; no need to disable it.
Recycle bin	PutBucketTrash	Enable recycle bin functionality.	✅	Only hierarchical namespaces support the recycle bin feature. For details, see Recycle Bin.
Recycle bin		GetBucketTrash	Get recycle bin details.	✅	Only hierarchical namespaces support the recycle bin feature. For details, please refer to Recycle Bin.
Transfer acceleration	PutBucketTransferAcceleration	Enable or disable transfer acceleration.	✅
Transfer acceleration		GetBucketTransferAcceleration	Retrieve transfer acceleration configuration information.	✅
Data processing	Pm3u8	Obtain download authorization for private m3u8.	❌
Log storage	PutBucketLogging	Enable or disable log storage.	✅
Log storage		GetBucketLogging	Retrieve the configuration information of log storage.	✅
AIGC	TextToImage	Combine object storage image processing features with Doubao's text-to-image model.	❌
AIGC		ImageToImage	Combine object storage image processing features with Doubao's image-to-image model.	❌
Requester pays	PutBucketRequestPayment	Set the payment mode for the bucket.	✅
Requester pays		GetBucketRequestPayment	View the payment mode of the bucket.	✅
TLS version	PutBucketHttpsConfig	Enable or disable the TLS version setting feature.	✅
TLS version		GetBucketHttpsConfig	View TLS version.	✅

Object

Category	API	Feature	Is HNS bucket supported?	Difference
Basic operations	CopyObject	Copy object.	✅	The header field x-tos-server-side-encryption-* is not supported. The header field x-tos-storage-class is supported, but directories only support the STANDARD (standard storage) storage type. Soft copy is not supported; only hard copy is supported. When both the source and destination are HNS buckets, only file-to-file and directory-to-directory copies are supported; files and directories cannot be copied to each other. Copying a directory only copies the directory object itself; it cannot recursively copy sub-files or sub-directories. When the source is an FNS bucket and the destination is an HNS bucket, non-empty objects with directory-format keys in the source are not supported for copying as directory-format key objects.
		DeleteObject	Delete object.	✅	Deleting non-empty directories is not supported.
		DeleteMultiObjects	Batch delete objects.	✅	Only file deletion is supported; directory deletion is not supported. If a batch delete request contains both files and directories, files will be deleted successfully, but directories will fail to delete.
		GetObject	Get object.	✅	If the object is a directory, the response includes the header field x-tos-directory with a value of true. After uploading a file, the Etag in the GetObject response header is the MD5 of the file. After the file is modified, the Etag in the GetObject response header is the crc64 of the file. If the request target is a directory, the response header does not include Etag. If the requested key ends with / and the object is not actually a directory, 409 is returned. If there is a file with the same name as an intermediate-level directory in the requested key, 409 is returned.
		HeadObject	Check whether the object exists.	✅	When the object is a directory, the response header includes the field x-tos-directory with a value of true. After uploading a file, the Etag field in the HeadObject response header is the MD5 of the file. After the file is modified, the Etag field in the response header is the crc64 of the file. When the target of the request is a directory, the response header does not include the Etag field. If the requested key ends with / and the object is not actually a directory, a 409 is returned. If there is a file with the same name as an intermediate-level directory in the requested key, a 409 is returned.
		AppendObject	Append object.	✔️	HNS buckets support appending objects using ModifyObject. For details, see ModifyObject.
		ModifyObject	Modify/write object. warning This interface is only supported by HNS buckets.	✅	Currently, only append write is supported, that is, the append function, and a valid offset must be provided; the response header includes x-next-modify-offset, which serves as the offset for the next modify write. Modify write is not supported for non-existent objects, that is, uploading objects via modify write is not supported. Modify write requires specifying Content-Length, and Content-Length must be greater than 0, meaning modify write must carry data. After a file is modified by write, the Etag in the response headers of HeadObject and GetObject is the file's crc64. The response header includes Etag, which is the md5 of the data uploaded this time. The response header includes crc64, which is the crc64 of the object after this modify write.
		ListObjects	List objects in the bucket.	✅	Query must carry delimiter, and the value must be /.
		ListObjectsV2	List object V2 versions in the bucket.	✅	Query must include delimiter, and the value must be /.
		ListObjectVersions	List all object version information in the bucket.	❌
		PutObject	Upload object.	✅	When the requested key ends with /, the server considers that the client intends to operate on a directory; when the requested key does not end with /, the server operates on the actual object. Files and directories cannot overwrite each other. Directories do not support overwriting. If you upload a directory that already exists, the server returns 200, but the directory will not be overwritten. If you upload an object with a directory-formatted key (i.e., ending with /), the object type is directory; otherwise, the object type is file. If intermediate directories do not exist, they are created automatically. Uploading a directory does not support including data. Chunk mode uploads are not supported. The header field x-tos-storage-class is supported, but directories only support the STANDARD (standard storage) class.
		PostObject	Upload objects using forms.	✅	When the requested key ends with /, the server considers that the client is operating on a directory; if the requested key does not end with /, the server operates on the actual object. Files and directories do not support mutual overwriting. Directories do not support overwriting. When uploading an already existing directory, return 200, but the directory will not be overwritten. When uploading an object with a directory-formatted key (i.e., ending with /), the object type is directory; otherwise, the object type is file. If an intermediate directory does not exist, it will be automatically created. Data cannot be included when uploading a directory. Chunked upload mode is supported. The header field x-tos-storage-class is supported, but directories only support the STANDARD (standard storage) storage class.
		SetObjectMeta	Update metadata of objects already uploaded in the bucket.	✅
		SetObjectExpires	Add an expiration time to the object, or modify the object's expiration time.	✅
		RestoreObject	Restore Archive, Cold Archive, and Deep Cold Archive objects.	✅
		RenameObject	Rename object.	✅	Renaming a directory to an existing directory is not supported.
Access control	PutObjectACL	Set object access control permissions.	✅
Access control		GetObjectACL	Get access control permissions for the specified object.	✅
Object tagging	PutObjectTagging	Set object tags.	✅
		GetObjectTagging	View object tag information.	✅
		DeleteObjectTagging	Delete object tags.	✅
Fetch object	FetchObject	Fetch resources from the specified URL and store them in the designated bucket.	✅
		PutFetchTask	Create an asynchronous task to fetch resources from a specified URL and store the resource in the specified bucket.	❌
		GetFetchTask	Query detailed information about asynchronous tasks.	❌
Soft link	PutSymlink	Create symbolic link.	✅
Soft link		GetSymlink	Get symbolic link object information.	✅

Multipart upload

API	Feature	Is HNS bucket supported?	Difference
CreateMultipartUpload	Initialize multipart upload task.	✅	The requested key cannot end with /; If an intermediate directory does not exist, it will be created automatically; Directories do not support overwriting. If the last-level path of the uploaded object is an existing directory, 409 is returned; The header field x-tos-storage-class is supported, but directories only support the STANDARD (standard storage) storage type.
UploadPart	Upload part data.	✅	Chunk mode upload is not supported.
CompleteMultipartUpload	Merge and upload all parts of the object.	✅
AbortMultipartUpload	Cancel multipart upload task.	✅
UploadPartCopy	Multipart copy upload object.	✅	The header x-tos-server-side-encryption-* is not supported. Soft copy is not supported; only hard copy is supported. When both source and destination are HNS buckets, only file-to-file and directory-to-directory copying are supported; files and directories cannot be copied to each other. Copying a directory only copies the directory object itself; sub-files or sub-directories cannot be copied recursively. When the source is an FNS bucket and the destination is an HNS bucket, copying objects with directory-format keys that are non-empty as directory-format key objects is not supported.
ListMultipartUploads	List multipart upload tasks.	✅
ListParts	List uploaded parts.	✅

Torch Object Storage