Feature description

Call the FetchObject interface to fetch resources from the specified URL and store them in the designated bucket.

Server-side encryption

With server-side encryption enabled, TOS encrypts the data you upload at the file level and stores the encrypted data permanently. When you download a file, TOS automatically decrypts and returns the data to you. For more details about server-side encryption, see server-side encryption overview.

ACL

You can set the object's ACL through headers. All objects are private by default. You can grant specific permissions to an account or predefined group. For more details about ACL, see ACL policy overview.

Storage type

TOS stores objects in Standard Storage by default. This storage type features high availability, reliability, and performance. You can also choose another storage type according to the use case. For more details about storage types, see Storage type.

Notes

Category	Notes
Object count	Only one object can be fetched at a time. The maximum supported size is 5 GiB. Fetching objects larger than 5 GiB will fail.
URL	Only publicly accessible URL resources are supported for fetching.
Permissions	Please ensure your Volcengine account has permission to upload objects to the corresponding bucket; otherwise, calling FetchObject to fetch resources will fail.

Request syntax

Request parameters and headers

This request uses common request headers. See Common parameters.

Name	Location	Type	Required	Sample value	Note
fetch	Query	String	Yes	-	Represents a special identifier for the FetchObject request.
x-storage-class	Header	string	No	STANDARD	Specifies the storage type of the copy. If this parameter is unset, the copy inherits the default storage type of its containing bucket. Valid values: STANDARD: Standard Storage. IA: Infrequent Access Storage. INTELLIGENT_TIERING: Intelligent Tiering Storage. ARCHIVE_FR: Archive Flashback Storage. COLD_ARCHIVE: Cold Archive Storage. tip Cold Archive is only supported in China (Beijing), China (Shanghai), and China (Guangzhou). DEEP_COLD_ARCHIVE: Deep Cold Archive Storage. tip Deep Cold Archive is only supported in China (Beijing), China (Shanghai), and China (Guangzhou). Deep Cold Archive is currently in closed beta. Please contact your account manager for access.
x-tos-acl	Header	string	No	private	Object ACL setting. Valid values: private: private. public-read: public read. public-read-write: public read-write. authenticated-read: authenticated user read. bucket-owner-read: bucket owner read. bucket-owner-full-control: bucket owner full control. default: inherit bucket ACL, meaning the object's ACL policy matches the bucket ACL policy.
x-tos-grant-full-control	Header	string	No	id=123,id=456	Grants the grantees READ, READ_ACP, and WRITE_ACP permissions on the object during object creation. Format: id=account1,id=account2.
x-tos-grant-read	Header	string	No	id=123,id=456	Allows the grantee to read the object and its metadata. Format: id=account1,id=account2.
x-tos-grant-read-acp	Header	string	No	id=123,id=456	Allows the authorized user to read the object ACL. Format: id=account1,id=account2.
x-tos-grant-write-acp	Header	string	No	id=123,id=456	Allows the grantees to modify the object ACL. Format: id=account1,id=account2.
x-tos-meta-*	Header	string	No	x-tos-meta-key: value	Used to add custom metadata for personalized object management. Your custom metadata will appear in the response headers when others retrieve this object or query the object metadata.
x-tos-server-side-encryption	Header	String	No	AES256	Specifies the method used for encrypting the object. If this parameter is unset, the object is not encrypted by default. Valid values: AES256: uses SSE-TOS encryption with the AES256 algorithm. SM4: uses SSE-TOS encryption with the SM4 algorithm. kms: uses SSE-KMS encryption. For detailed explanations of SSE-TOS and SSE-KMS encryption methods, see Server-Side Encryption Overview. tip Using SSE-KMS for server-side encryption generates API call fees. Creating a KMS key incurs key management fees charged by KMS. For more information, see KMS Billing Overview.
x-tos-server-side-data-encryption	Header	String	No	AES256	Set the encryption algorithm when using SSE-KMS encryption. Description: AES256: AES256 encryption algorithm. SM4: SM4 encryption algorithm. Default is AES256 algorithm.
x-tos-server-side-encryption-kms-key-id	Header	String	No, but yes if SSE-KMS is used.	trn:kms:cn-beijing:20000111:keyrings/ring-test/keys/key-test	Specify the master key used for SSE-KMS encrypted target objects in the following format: trn:kms:<region>:<accountID>:keyrings/<keyring>/keys/<key>: the TRN of the KMS master key, where region is the Region ID of the key, accountID is the account ID owning the key, keyring is the keyring alias, and key is the master key alias. tip Default master key is not supported currently. If SSE-KMS encryption is specified without providing this header, the server returns a 400 InvalidRequest error.
x-tos-server-side-encryption-customer-algorithm	Header	String	No, but YES if SSE-C is used.	AES256	Specifies the algorithm for SSE-C encrypting the object. Valid value: AES256: encrypt the object using the AES256 algorithm.
x-tos-server-side-encryption-customer-key	Header	String	No, but YES if SSE-C is used.	YWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFh****	Used with x-tos-server-side-encryption-customer-algorithm, specifies the SSE-C encrypted target object's key, formatted as a base64-encoded 256-bit encryption key.
x-tos-server-side-encryption-customer-key-MD5	Header	String	No, but YES if SSE-C is used.	0gYVWExOAz67jX5A6qY4****	Used with x-tos-server-side-encryption-customer-key, this header represents the MD5 value of the key used to encrypt the object. The value is derived by Base64-encoding the 128-bit MD5 of the key and is used for message integrity check to ensure error-free transmission of the encryption key.

Request body elements

Name	Location	Type	Required	Sample value	Note
URL	Body	String	Yes	http://abc/obj	URL to be fetched. tip Only a single URL is supported at present.
IgnoreSameKey	Body	Bool	No	true	Fetch strategy when a file with the same name exists in the bucket. The values are as follows: true: if a file with the same name already exists in the bucket, skip this fetch. false: if a file with the same name already exists in the bucket, still fetch the object and overwrite the existing object when uploading. default is false. tip The same-name file is determined by the file key; file content is not compared.
ContentMD5	Body	String	No	XrY7u+Ae7tCTyyK7j1rN****	Base64 value of the MD5 of the file to upload. After setting this, TOS calculates the MD5 of the uploaded file and checks it against the MD5 carried by FetchObject. If the verification fails, the fetch will fail.

Response headers

The common response headers returned by this request. See common parameters.

Name	Parameter type	Sample value	Note
x-tos-server-side-encryption	String	kms	Server-side encryption method of the object, which is returned if the object is SSE-TOS or SSE-KMS encrypted. Valid values: AES256: uses SSE-TOS encryption with the AES256 algorithm. SM4: uses SSE-TOS encryption with the SM4 algorithm. kms: uses SSE-KMS encryption. For detailed explanations of SSE-TOS and SSE-KMS encryption methods, see Server-Side Encryption Overview.
x-tos-server-side-encryption-kms-key-id	String	trn:kms:cn-beijing:2000****:keyrings/ring-test/keys/key-test	ID of the KMS master key, which is returned if the object is SSE-KMS encrypted.
x-tos-server-side-encryption-customer-algorithm	String	AES256	Algorithm used for encrypting the object, which is returned if the object is SSE-C encrypted.
x-tos-server-side-encryption-customer-key-MD5	String	0gYVWExOAz67jX5A6qY4+A==	MD5 value of the encryption key, which is returned if the object is SSE-C encrypted.
x-tos-version-id	String	57AF1A32CECB56721267	Version ID of the object. This header will not appear in the response if the object has no version ID.
x-qos-delay-time	String	5	The expected delay time. The x-qos-delay-time header is calculated and added only when AvgQosDelayTime is not 0. If this value is 0, this header is not added, indicating that flow control is not in effect.

Response body elements

Name	Type	Sample value	Description
ETag	String	883abc8623528daf10b7e1bb1b2774ba	Uniquely identifies the content of an object.

Sample request

Sample response

Torch Object Storage