FetchObject
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
-
Request syntax
Plain Text1POST /<ObjectName>?fetch HTTP/1.1 2Host: <BucketName>.bj.bcebos.com 3Content-Length: 0 4Date: <Date> 5x-bce-fetch-source: <Source> 6x-bce-fetch-mode: <FetchMode> 7x-bce-storage-class: <StorageClass> 8Authorization: AuthorizationString -
Request headers
| Name | Types | Description | Whether required |
|---|---|---|---|
| x-bce-fetch-source | String | Source address of the fetched file, e.g., http://www.abc.com/img.jpg. This parameter can be included in the querystring. When it is placed in the querystring, UrlEncode is required. |
Yes |
| x-bce-fetch-mode | String | Fetch mode, supporting two modes: asynchronous fetch async and synchronous fetch sync. In the asynchronization mode, BOS returns successfully at once upon receiving the fetch task. In the synchronization mode, BOS returns successfully only after the object is fetched. The synchronization mode is recommended for small data volumes or scenarios requiring real-time fetch results. Without waiting time, the asynchronization mode is suitable for scenarios where there is no need to view the fetch results in real time, allowing subsequent querying of the fetch results. The default value is sync. This parameter can be included in the querystring. |
No |
| x-bce-storage-class | String | Storage class, supporting standard storage STANDARD, infrequent access storage STANDARD_IA, cold storage COLD, and archive storage ARCHIVE, defaulting to STANDARD; if it is multi-AZ bucket, MAZ_STANDARD_IA represents multi-AZ infrequent access storage; if unspecified, it defaults to MAZ_STANDARD multi-AZ standard storage, rather than other options. This parameter can be included in the querystring. |
No |
| x-bce-server-side-encryption | String | Server-Side Encryption (SSE) supports AES256 and SM4 encryption algorithms. | No |
| x-bce-callback-address | String | Callback address for fetch results: If asynchronous mode is enabled, results will be sent to this address upon completion. | No |
| referer | string | Referer header to be passed through during fetch at origin server | No |
| user-agent | string | User-Agent header to be passed through during fetch at origin server | No |
Response
| Name | Types | Description |
|---|---|---|
| code | String | Return codes indicating the success or failure of the return request, including return success Success and return error [Error Code](BOS/API Reference/Error code.md#BOS error code). |
| message | String | Return the information indicating the request success or failure. If succeeded, return success; if incorrect, return the [Error Code](BOS/API Reference/Error code.md#BOS error code) corresponding to the code. |
| requestId | String | Request ID. |
| jobId | String | This parameter is only returned in asynchronous mode and represents the ID of the requested task, which can be used to query the status of subsequent tasks. |
| x-bce-version-id | String | Object version ID |
Example
-
Request example (synchronization mode)
Plain Text1POST /ObjectName?fetch HTTP/1.1 2Host: BucketName.bj.bcebos.com 3Content-Length: 0 4Date: <Date> 5x-bce-fetch-source: http://www.abc.com/demo.html 6x-bce-fetch-mode: sync 7x-bce-storage-class: STANDARD 8Authorization: AuthorizationString -
Response example (synchronization mode)
Plain Text1HTTP/1.1 200 OK 2x-bce-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409 3Transfer-Encoding: chunked 4Date: Wed, 25 May 2016 06:34:40 GMT 5Server: BceBos 6{ 7 "code": "success", 8 "message": "success", 9 "requestId": "4db2b34d-654d-4d8a-b49b-3049ca786409", 10} -
Request example (asynchronization mode)
Plain Text1POST /ObjectName?fetch HTTP/1.1 2Host: BucketName.bj.bcebos.com 3Content-Length: 0 4Date: <Date> 5x-bce-fetch-source: http://www.abc.com/demo.html 6x-bce-fetch-mode: async 7x-bce-storage-class: STANDARD_IA 8Authorization: AuthorizationString -
Response example (asynchronization mode)
Plain Text1HTTP/1.1 200 OK 2x-bce-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409 3Content-Length: 43 4Date: Wed, 25 May 2016 06:34:40 GMT 5Server: BceBos 6{ 7 "code": "success", 8 "message": "success", 9 "requestId": "4db2b34d-654d-4d8a-b49b-3049ca786409", 10 "jobId": "b2419b1e3fd45d596ee22bdf62aaaa2f" 11} -
Request example (asynchronization mode, notification callback address)
Plain Text1POST /ObjectName?fetch HTTP/1.1 2Host: BucketName.bj.bcebos.com 3Content-Length: 0 4Date: <Date> 5x-bce-fetch-source: http://www.abc.com/demo.html 6x-bce-fetch-mode: async 7x-bce-storage-class: STANDARD_IA 8x-bce-callback-address:<callback-address> 9Authorization: AuthorizationString -
Response example (asynchronization mode, notification callback address)
Plain Text1HTTP/1.1 200 OK 2x-bce-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409 3Content-Length: 43 4Date: Wed, 25 May 2016 06:34:40 GMT 5Server: BceBos 6{ 7 "code": "success", 8 "message": "success", 9 "requestId": "4db2b34d-654d-4d8a-b49b-3049ca786409", 10 "jobId": "b2419b1e3fd45d596ee22bdf62aaaa2f" 11}As example of information received at the callback address is as follows:
Plain Text1{"code":"success","jobid":"fo-9a98f238d56a33b4eb6664fede20b747","message":"success","requestId":"61c41bdf-672b-49c4-921e-3d6bde8112a6"}Plain Text1{"code":"NoSuchKey","jobid":"fo-9a98f238d56a33b4eb6664fede20b747","message":"The specified key does not exist.","requestId":"24ff8d6c-f793-45ef-b55b-973837141c90"}