CopyObject

API description

This API enables an existing object to be copied to another object, accommodating file sizes from 0 Byte to 5 GB. It also supports metadata updates in replace mode, where the source and destination objects are the same. The requester must specify the copy source in the header when using this API.

The CopyObject API supports cross-region replication of files, meaning the source bucket where the copied file is located and the object bucket may not be in the same region (currently only supporting data copying from other regions to this region). The cross-region traffic generated from the cross-region replication of files will be charged. For the cross-region charging standards, see [Product Pricing](BOS/Product pricing/Product price/Pay-As-You-Go Charge Type.md).

Request

• Request syntax

  Plain Text Copy

  1PUT /<ObjectKey> HTTP/1.1
  2Host: <BucketName>.bj.bcebos.com
  3Date: <Date>
  4Authorization: <AuthorizationString>
  5Content-Length: <ContentLength>
  6Content-Type:text/plain
  7x-bce-copy-source: /SourceBucket/SourceObject
  8x-bce-copy-source-if-match: 3858f62230ac3c915f300c664312c11f
  9x-bce-metadata-directive: <DirectiveString>
  10x-bce-storage-class: <StorageClass>

• Request parameters

  Plain Text Copy

  1None

• Request headers

  Name	Types	Description	Whether required
  x-bce-copy-source	String	Source object address	Yes
  x-bce-copy-source-if-match	String	If the ETag value of the source object matches the ETag value provided by the user, the copy operation is performed; otherwise, it fails.	No
  x-bce-metadata-directive	String	Whether the Metadata of the target object is copied from the source object or is specified by request The valid values are copy and replace. The default value is copy. If it is set to copy, the meta of the source object is used directly; if it is set to replace, the meta specified by request is applied.	No
  x-bce-meta-*	String	Reboot in replace mode to modify user-defined metadata used for storing custom object information. For example, assign a file tag using the parameter "x-bce-meta-gender" with the value set to "Male.\	No
  x-bce-copy-source-if-none-match	String	If the ETag value of the source object does not match the ETag value provided by the user, the copy operation is performed; otherwise, it fails.	No
  x-bce-copy-source-if-unmodified-since	String	If the source object has not been modified since the time specified in x-bce-copy-source-if-unmodified-since, the copy operation is performed; otherwise, it fails. The parameter value is in GMT format, e.g., Wed, 06 Apr 2016 06:34:40 GMT.	No
  x-bce-copy-source-if-modified-since	String	If the source object has been modified since the time specified in x-bce-copy-source-if-modified-since, the copy operation is performed; otherwise, it fails. The parameter value is in GMT format, e.g., Wed, 06 Apr 2016 06:34:40 GMT.	No
  x-bce-storage-class	String	It specifies the storage class of the object: STANDARD_IA indicates infrequent access storage, COLD indicates cold storage, ARCHIVE indicates archive storage. If the storage class is not specified, the default class is standard storage. For multi-AZ buckets, MAZ_STANDARD_IA indicates multi-AZ infrequent access storage. If the storage class is not specified, the default class is MAZ_STANDARD multi-AZ standard storage, rather than other options.	No
  x-bce-acl	String	Header supported by CannedACL. Users can set object permissions with values such as private and public-read.	No
  x-bce-grant-read	String	Header supported by CannedACL. Users can configure read permissions for the object. It supports multiple IDs, separated by commas.	No
  x-bce-grant-full-control	String	Header supported by CannedACL. Users can configure FULL_CONTROL permissions for the object. It supports multiple IDs, separated by commas.	No
  x-bce-server-side-encryption	String	Server-Side Encryption (SSE) algorithm is supported. Currently, AES256 and SM4 encryption are available.	No
  x-bce-tagging-directive	String	Whether copy includes the source object tag, with the value of "Copy" (default): Copy the source object tag to the target object; "Replace": Ignore the source object tag	No

Response

• Response headers

• Response parameters

1> **Note**
2>
3> 1.  The requester must have read permissions for the source object.
4> 2.  Before calculating the signature, users must URL-encode non-standard ASCII characters (e.g., Chinese) in the x-bce-copy-source field.
5> 3.  To maintain HTTP connections during the copy process, HTTP responses from the CopyObject API may use Transfer-Encoding: Chunked mode.
6> 4.  If a server-side error occurs during the CopyObject operation, the HTTP status code may still return 2XX, but the copy may fail. The outcome should be determined based on the JSON in the HTTP body.
7> 5.  If the source object belongs to the archive storage class in CopyObject, it must be restored before calling the CopyObject API.
8> 6.  Objects in the archive storage class do not support metadata updates via CopyObject (replace mode with the source and target pointing to the same file).
9> 7.  When copying a symlink file, only the symlink is copied, no data. If the target file of the symlink is deleted while accessing this API via symlink, HTTP 404, SymlinkTargetNotExist will be returned.

Example

• Example of standard storage request

  Plain Text Copy

  1PUT /ObjectName HTTP/1.1
  2Host: BucketName.bj.bcebos.com
  3Date: Wed, 06 Apr 2016 06:34:40 GMT
  4Authorization: AuthorizationString
  5Content-Length: 0
  6Content-Type:text/plain
  7x-bce-copy-source: /SourceBucket/SourceObject
  8x-bce-copy-source-if-match: 3858f62230ac3c915f300c664312c11f
  9x-bce-metadata-directive: replace
  10x-bce-meta-mykey: myvalue

• Example of infrequent access/cold storage request

  Plain Text Copy

  1PUT /object HTTP/1.1
  2Host: BucketName.bj.bcebos.com
  3Date: Wed, 06 Apr 2016 06:34:40 GMT
  4Authorization: AuthorizationString
  5Content-Length: 0
  6Content-Type:text/plain
  7x-bce-copy-source: /SourceBucket/SourceObject
  8x-bce-copy-source-if-match: 3858f62230ac3c915f300c664312c11f
  9x-bce-storage-class: STANDARD_IA

• Response example

  Copy succeeded

  Plain Text Copy

  1HTTP/1.1 200 OK
  2x-bce-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
  3Date: Wed, 06 Apr 2016 06:34:40 GMT
  4Connection: close
  5Server: BceBos
  6{
  7    "lastModified":"2009-10-28T22:32:00Z",
  8    "ETag":"9b2cf535f27731c974343645a3985328"
  9}

  Server exception is judged based on the returned JSON

  Plain Text Copy

  1HTTP/1.1 200 OK
  2Date: Thu, 12 May 2016 09:14:32 GMT
  3Content-Type: application/json; charset=utf-8
  4Connection: keep-alive
  5Server: BceBos
  6x-bce-request-id: bb90cc9c-2b80-462c-87a4-095e610c9a2f
  7Transfer-Encoding: chunked
  8{
  9    "code":"InternalError",
  10    "message":"We encountered an internal error. Please try again.",
  11    "requestId":"52454655-5345-4420-4259-204e47494e58"
  12}

  Multi-version request example

  Plain Text Copy

  1PUT /object HTTP/1.1
  2Host: BucketName.bj.bcebos.com
  3Date: Wed, 06 Apr 2016 06:34:40 GMT
  4Authorization: AuthorizationString
  5Content-Length: 0
  6Content-Type:text/plain
  7x-bce-copy-source: /SourceBucket/SourceObject?versionId=AJyQ0XRhboY=
  8x-bce-copy-source-if-match: 3858f62230ac3c915f300c664312c11f
  9x-bce-storage-class: STANDARD_IA

• Response example

  Copy succeeded

  Plain Text Copy

  1HTTP/1.1 200 OK
  2x-bce-request-id: 41dffrad-654d-4d8a-b49b-304dsd34fadd5df59
  3Date: Wed, 06 Apr 2024 08:34:40 GMT
  4Connection: close
  5x-bce-version-id:AKyQ9DRhhoY=
  6Server: BceBos
  7{
  8    "lastModified":"2024-04-06T08:34:40Z",
  9    "ETag":"9b2cf535f27731c974343645a3985328"
  10}