Copying an Object¶
Functions¶
You can perform this operation to create a copy of an existing object in OBS.
Users can determine whether to copy the metadata of the source object to the target object (by default) or replace the metadata of the target object with the metadata contained in the request. The ACL of the source object is not copied to the target object. By default, the ACL of the target object is private. You can set an ACL for the target object by sending an API request.
The request for copying an object needs to carry the information about the bucket and object to be copied in the header field. The message body cannot be carried.
An object copy can be up to 5 GB in size. If the source object size exceeds 5 GB, you can only copy part of the object.
Note
You cannot determine whether a request is executed successfully only using status_code in the header returned by HTTP. If 200 in status_code is returned, the server has received the request and starts to process the request. The body in the response shows whether the copy succeeds. If the body contains ETag, the copy succeeds. Otherwise, the copy failed.
Versioning¶
By default, x-obs-copy-source specifies the latest version of the source object. If the latest version of the source object is a delete marker, the object is considered deleted. You can add versionId to request header x-obs-copy-source to copy an object with the specified version ID.
If a bucket has versioning enabled, the system automatically generates a unique version ID for the requested object in this bucket and returns the version ID in response header x-obs-version-id. If versioning is suspended for the bucket, the object version ID is null.
Important
When the bucket versioning status is disabled, if you make a copy of object_A and save it as object_B, and an object named as object_B already exists, the new object_B will overwrite the existing one. After the copying is executed successfully, only new object_B can be downloaded because old object_B has been deleted. Therefore, before copying an object, ensure that there is no object with the same name as the object copy to prevent data from being deleted mistakenly. During the copying, object_A has no changes.
WORM¶
If a bucket has WORM enabled, you can configure retention policies for objects in the bucket. You can specify the x-obs-object-lock-mode and x-obs-object-lock-retain-until-date headers to configure a retention policy when you copy an object. If you do not specify these two headers but have configured a default bucket-level WORM policy, this default policy automatically applies to the object newly copied. You can also configure or update a WORM retention policy after an object is copied to the bucket.
Note
In a copy operation, the object protection status is not copied, so the protection status of an object copy is independent of that of the source object. After the copy is complete, WORM retention changes made on the source object does not affect the object copy.
Request Syntax¶
PUT /destinationObjectName HTTP/1.1
Host: bucketname.obs.region.example.com
x-obs-copy-source: /sourceBucket/sourceObject
x-obs-metadata-directive: metadata_directive
x-obs-copy-source-if-match: etag
x-obs-copy-source-if-none-match: etag
x-obs-copy-source-if-unmodified-since: time_stamp
x-obs-copy-source-if-modified-since: time_stamp
Authorization: signature
Date: date
Request Parameters¶
This request contains no parameters.
Request Headers¶
You can add optional headers to specify the object to be copied. Table 3 describes the optional headers.
Header | Description | Mandatory |
|---|---|---|
x-obs-acl | When copying an object, you can add this header to configure the object ACL using the predefined common policies, including private, public-read, and public-read-write. Type: string Example: x-obs-acl: acl | No |
x-obs-grant-read | When creating an object, you can use this header to grant all users in an account the permissions to read the object and obtain the object metadata. Type: string | No |
x-obs-grant-read-acp | When creating an object, you can use this header to grant all users in an account the permission to obtain the object ACL. Type: string | No |
x-obs-grant-write-acp | When creating an object, you can use this header to grant all users in an account the permission to write the object ACL. Type: string | No |
x-obs-grant-full-control | When creating an object, you can use this header to grant all users in an account the permissions to read the object, obtain the object metadata and ACL, and write the object ACL. Type: string | No |
x-obs-copy-source | Indicates names of the source bucket and the source object. If the source object has multiple versions, the versionId parameter can be used to specify the desired version. Type: string Constraint: URL encoding is required for handling full-width characters and %. Example: x-obs-copy-source: /source_bucket/sourceObject | Yes |
x-obs-metadata-directive | Indicates whether the metadata of the target object is copied from the source object or replaced with the metadata contained in the request. Type: string Valid values: COPY and REPLACE Default value: COPY Example: x-obs-metadata-directive: metadata_directive Constraints: Values other than COPY or REPLACE result in an immediate 400-based error response. If you need to modify the metadata (the same for both the source and target objects), this parameter must be set to REPLACE, otherwise, the request is invalid and the server returns a 400 HTTP status code error. | No |
x-obs-copy-source-if-match | Indicates that the source object is copied only if its ETag matches the one specified in this header. Otherwise, a 412 status code (failed precondition) is returned. Type: string Example: x-obs-copy-source-if-match: etag Constraint: This header can be used with x-obs-copy-source-if-unmodified-since but not other conditional copy headers. | No |
x-obs-copy-source-if-none-match | Indicates that the source object is copied only if its ETag does not match the one specified in this header. Otherwise, a 412 status code (failed precondition) is returned. Type: string Example: x-obs-copy-source-if-none-match: etag Constraint: This parameter can be used with x-obs-copy-source-if-modified-since but not other conditional copy parameters. | No |
x-obs-copy-source-if-unmodified-since | Indicates that the source object is copied only if it has not been modified since the time specified by this header. Otherwise, error code 412 (failed precondition) is returned. This header can be used with x-obs-copy-source-if-match, but cannot be used with other conditional copy headers. Type: string Format: HTTP time string complying with the format specified at http://www.ietf.org/rfc/rfc2616.txt, which can be any of the following:
Examples:
Constraint: The time specified by this header cannot be later than the current server time (GMT time), or this header does not take effect. | No |
x-obs-copy-source-if-modified-since | Indicates that the source object is copied only if it has been modified since the time specified by this header. Otherwise, error code 412 (failed precondition) is returned. This header can be used with x-obs-copy-source-if-none-match, but cannot be used with other conditional copy headers. Type: string Format: HTTP time string complying with the format specified at http://www.ietf.org/rfc/rfc2616.txt, which can be any of the following:
Examples:
Constraint: The time specified by this header cannot be later than the current server time (GMT time), or this header does not take effect. | No |
x-obs-website-redirect-location | If a bucket is configured with the static website hosting function, it will redirect requests for this object to another object in the same bucket or to an external URL. OBS stores the value of this header in the object metadata. Type: string Default value: none Constraint: The value must be prefixed by a slash (/), http://, or https://. The length of the value cannot exceed 2 KB. | No |
success_action_redirect | Indicates the address (URL) to which a successfully responded request is redirected.
Type: string | No |
x-obs-object-lock-mode | WORM mode that will be applied to the object. Currently, only COMPLIANCE is supported. This header must be used together with x-obs-object-lock-retain-until-date. Type: string Example: x-obs-object-lock-mode:COMPLIANCE | No, but required when x-obs-object-lock-retain-until-date is present. |
x-obs-object-lock-retain-until-date | Indicates the expiration time of the Object Lock retention. The value must be a UTC time that complies with ISO 8601, for example, 2015-07-01T04:11:15Z. This header must be used together with x-obs-object-lock-mode. Type: string Example: x-obs-object-lock-retain-until-date:2015-07-01T04:11:15Z | No, but required when x-obs-object-lock-mode is present. |
For details about other headers, see Table 3.
Request Elements¶
This request contains no elements.
Response Syntax¶
HTTP/1.1 status_code
Content-Type: application/xml
Date: date
Content-Length: length
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<CopyObjectResult xmlns="http://obs.region.example.com/doc/2015-06-30/">
<LastModified>modifiedDate</LastModified>
<ETag>etagValue</ETag>
</CopyObjectResult>
Response Headers¶
The response to the request uses common headers. For details, see Table 1.
In addition to the common response headers, the headers listed in Table 2 may be used.
Header | Description |
|---|---|
x-obs-copy-source-version-id | Version ID of the source object Type: string |
x-obs-version-id | Version ID of the target object Type: string |
Response Elements¶
This response contains elements of a copy result. Table 3 describes the elements.
Element | Description |
|---|---|
CopyObjectResult | Container for the copy result Type: XML |
LastModified | Latest time when the object was modified Type: string |
ETag | 128-bit MD5 digest of the Base64 code of a new object. ETag is the unique identifier of the object content. It can be used to determine whether the object content is changed. For example, if the ETag value is A when an object is uploaded, but this value has changed to B when the object is downloaded, it indicates that the object content has been changed. Type: string |
Error Responses¶
No special error responses are returned. For details about error responses, see Table 2.
Sample Request: Copying an Object¶
Copy the object srcobject in bucket bucket to the destobject object in bucket examplebucket.
PUT /destobject HTTP/1.1
User-Agent: curl/7.29.0
Host: examplebucket.obs.region.example.com
Accept: */*
Date: WED, 01 Jul 2015 04:19:21 GMT
Authorization: OBS H4IPJX0TQTHTHEBQQCEC:2rZR+iaH8xUewvUKuicLhLHpNoU=
x-obs-copy-source: /bucket/srcobject
Sample Response: Copying an Object¶
HTTP/1.1 200 OK
Server: OBS
x-obs-request-id: 001B21A61C6C00000134031BE8005293
x-obs-id-2: MDAxQjIxQTYxQzZDMDAwMDAxMzQwMzFCRTgwMDUyOTNBQUFBQUFBQWJiYmJiYmJi
Date: WED, 01 Jul 2015 04:19:21 GMT
Content-Length: 249
<?xml version="1.0" encoding="utf-8"?>
<CopyObjectResult xmlns="http://obs.region.example.com/doc/2015-06-30/">
<LastModified>2015-07-01T00:48:07.706Z</LastModified>
<ETag>"507e3fff69b69bf57d303e807448560b"</ETag>
</CopyObjectResult>
Sample Request: Copying an Object Version¶
Copy a multi-version object and copy the object srcobject whose version number is AAABQ4uBLdLc0vycq3gAAAAEVURTRkha in bucket bucket to the destobject object in bucket examplebucket.
PUT /destobject HTTP/1.1
User-Agent: curl/7.29.0
Host: examplebucket.obs.region.example.com
Accept: */*
Date: WED, 01 Jul 2015 04:20:29 GMT
Authorization: OBS H4IPJX0TQTHTHEBQQCEC:4BLYv+1UxfRSHBMvrhVLDszxvcY=
x-obs-copy-source: /bucket/srcobject?versionId=AAABQ4uBLdLc0vycq3gAAAAEVURTRkha
Sample Response: Copying an Object Version¶
HTTP/1.1 200 OK
Server: OBS
x-obs-request-id: DCD2FC9CAB78000001438B8A9C898B79
x-obs-id-2: DB/qBZmbN6AIoX9mrrSNYdLxwvbO0tLR/l6/XKTT4NmZspzharwp5Z74ybAYVOgr
Content-Type: application/xml
x-obs-version-id: AAABQ4uKnOrc0vycq3gAAAAFVURTRkha
x-obs-copy-source-version-id: AAABQ4uBLdLc0vycq3gAAAAEVURTRkha
Date: WED, 01 Jul 2015 04:20:29 GMT
Transfer-Encoding: chunked
<?xml version="1.0" encoding="utf-8"?>
<CopyObjectResult xmlns="http://obs.region.example.com/doc/2015-06-30/">
<LastModified>2015-07-01T01:48:07.706Z</LastModified>
<ETag>"507e3fff69b69bf57d303e807448560b"</ETag>
</CopyObjectResult>