Fetch an Object and Store It in a Bucket
Updated at：2025-11-03
API description
This API retrieves resources from a specified URL and stores them in a targeted bucket. The requester must have write permissions for the bucket. This operation is limited to fetching one object at a time, with an option to set a custom name for the object.
Description:
- The FetchObject API supports resource retrieval sizes ranging from 0 to 10 GB.
Request URI
POST /v1/{bucketName}/{objectKey}?fetch
| Parameter name | Parameter type | Required or not | Description | Example value | Parameter location |
|---|---|---|---|---|---|
| bucketName | String | Yes | Bucket name | "bucketName_example" | Path |
| objectKey | String | Yes | Object name | "objectKey_example" | Path |
Request header parameters
| Parameter name | Parameter type | Required or not | Description | Example value |
|---|---|---|---|---|
| xBceFetchSource | String | Yes | Provide the source URL of the file to be fetched, such as http://www.abc.com/img.jpg. This parameter can be included in the querystring. When placed in the querystring, UrlEncode is required. | "xBceFetchSource_example" |
| xBceFetchMode | String | No | Specify the fetch mode, which supports two options: asynchronous fetch (async) and synchronous fetch (sync). In asynchronous mode, BOS confirms receipt of the fetch task immediately. In synchronous mode, BOS confirms success only after the object is fetched. Synchronous mode is recommended for small data volumes or scenarios requiring real-time fetch results. Asynchronous mode, which eliminates waiting time, is suitable for scenarios where real-time fetch results are unnecessary, allowing the fetch results to be queried later. The default mode is sync. This parameter can also be included in the querystring. | "xBceFetchMode_example" |
| xBceStorageClass | String | No | Storage class options include standard storage (STANDARD), infrequent access storage (STANDARD_IA), cold storage (COLD), and archive storage (ARCHIVE). The default option is STANDARD. This parameter can be included in the querystring. | "xBceStorageClass_example" |
| xBceServerSideEncryption | String | No | Currently, only AES256 is supported as the server-side encryption algorithm. | "xBceServerSideEncryption_example" |
Parameters of request body
Description of the data structure of request body fields
Response body parameters
Description of the data structure of response body fields
| Parameter name | Parameter type | Description | Example value |
|---|---|---|---|
| errors | List |
Retrieve the container that holds erroneous object information, containing one or more object elements. |
Description of Errors field data structure
| Parameter name | Parameter type | Description | Example value |
|---|---|---|---|
| key | String | Retrieve the name of the erroneous object. | my-object2 |
| code | String | Error Code. | InvalidArgument |
| message | String | Error Message. | Invalid Argument. |
Request example
JSON
1POST /v1/bucketName_example/objectKey_example?fetch
2 <Common request headers>
3x-bce-fetch-source: xBceFetchSource_example
4x-bce-fetch-mode: xBceFetchMode_example
5x-bce-storage-class: xBceStorageClass_example
6x-bce-server-side-encryption: xBceServerSideEncryption_example
7{ }Response example
JSON
1HTTP/1.1 200 OK
2 <Common response headers>
3{
4 "errors" : [ {
5 "code" : "InvalidArgument",
6 "message" : "Invalid Argument.",
7 "key" : "my-object2"
8 }, {
9 "code" : "InvalidArgument",
10 "message" : "Invalid Argument.",
11 "key" : "my-object2"
12 } ]
13}Error code
Please refer to the general error codes