Copying an object
You use the HTTP COPY method with the Destination
header to copy an object from one location to another. The source and target locations can be two different containers within the same tenant, or they can be the same container. The source object is the object you're copying. The target object is the object that results from the copy operation.
To copy an object, you need read permission for the container containing the source object or for the source object itself and write permission for the target container.
When copying an object, you can specify a name for the target object that's different from the name of the source object.
Regardless of whether or not versioning is enabled, only the latest version of a source object is taken for the copy.
By default, HCP copies custom metadata for the source object to the target object. However, in the copy request, you can specify additional custom metadata to be used for the target object. To apply this custom metadata to the target object, you need to include the X-Object-Meta-name
header in the copy request.
If the target object you specify in a copy request identifies an existing object , HCP replaces the existing object with the new copy. If versioning is disabled the operation fails and a 409 (Conflict) HTTP status code appears.
Request line
Depending on whether the HSwift request uses a Keystone tenant ID or the account name, the request line for a request to copy an object has either of these formats:
- With the Keystone tenant ID:
COPY /swift/v1/tenant-ID/container-name/directory-name/object-name HTTP/1.1 "Destination: /container-name/object-name"
- With the account name:
COPY /swift/v1/account-name/container-name/directory-name/object-name HTTP/1.1 "Destination: /container-name/object-name"
Request headers
The table below describes the headers you can use in a request to copy an object.
Name | Type | Description |
X-Auth-Token | String |
Used to supply the Keystone authentication token or local authentication token. Replace the Keystone authentication token with the prefix HCP, followed by your Local Authentication token, in the format: "X-Auth-Token: HCP base64-encoded-username:md5-encoded-password" For example: "X-Auth-Token: HCP bGdyZWVu:a3b9c163f6c520407ff34cfdb83ca5c6" |
Destination | String (Required) |
Specifies the destination of the copied container and object, in this format: /container-name/source-object-name The initial forward slash (/) is required. You must UTF-8-encode and then URL-encode the names of the destination container and object before you include them in this header. |
X-Object-Meta-name | String | For objects only, specifies a custom metadata property/value pair. The response headers include one X-Object-Meta- header for each applicable pair. |
Response headers
The table below describes the response headers returned in response to a successful request to copy an object.
Name | Type | Description |
Content-length | String (Required) |
The size, in bytes, of the response body if HCP can determine the size before formulating the response. If the response does not include a response body, the value of the |
Content-Type | String (Required if the Content-Length is greater than 0) |
The Internet media type of the response body if HCP can determine the Internet media type. If HCP cannot determine the Internet media type, the value of this header is Because HCP returns error information in a response body, the response to any request can include a |
Date | Datetime (Required) |
The date and time at which HCP responded to the request in Greenwich Mean Time (GMT). The date and time are returned in this format: DDD dd MMM yyyy HH:mm:ss GMT For example: Thu, 14 Mat 2013 14:27:05 GMT |
ETag | String (Required) | This value is the MD5 checksum of the uploaded object content. The value is not quoted. If you supplied an ETag request header and the operation was successful, the values are the same. If you did not supply an ETag request header, check the ETag response header value against the object content you have just uploaded. |
Last-Modified | String (Required) | The date and time that the copied object was created or last had its metadata modified. |
X-Copied-From | String |
Shows the container and object name of the original source object from which the new object was copied. This is the format: container/object |
X-Copied-From-Last-Modified | String | Shows the last modified date and time for the original source object from which the new object was copied. |
X-Object-Meta-name | String | For object, specifies a custom metadata property/value pair. The response headers include one X-Object-Meta-name header for each applicable pair. |
X-Trans-Id | Uuid (Required) | HCP returns a universally unique identifier (UUID). This UUID does not map to any entries in the HCP database. |
HTTP status codes
The table below describes HTTP status codes that can be returned in response to a request to copy an object.
Code | Meaning | Description |
201 | Success | No response body. |
404 | Not Found | The specified source object does not exist. |
408 | Request Timeout | The request has timed out and the operation was not completed. HSwift is no longer retrying the operation. |
409 | Conflict | The object exists already and versioning is not enabled. |
410 | Gone |
Possible reasons include:
|
500 | Internal Server Error |
An internal error occurred. If this error persists, contact your tenant administrator. |
503 | Service Unavailable |
HCP is temporarily unable to handle the request, probably due to system overload, maintenance, or upgrade. Try the request again, gradually increasing the delay between each successive attempt. If this error persists, contact your tenant administrator. |
Example: Copying an object from one container to another and adding custom metadata
Here's a sample COPY request that copies an object named campaigns/GoGetEm.xls from the sales-mktg container to the finance container, where the target object that results from the copy operation is named mktg/campaign_GoGetEm_expenses.xls. With this copy, the metadata property/value pair business/campaign is added to the object.
Request with curl command line
curl -k -i -X COPY http://api.hcp.example.com/swift/v1/AUTH_6b6884ebb6f441cfbb7e740f6a927c9e/sales-mktg/campaigns/GoGetEm.xls -H "X-Auth-Token: dc5efec8f546455eac974e7bbfd0dd87" -H "Destination: finance/mktg/campaign_GoGetEm_expenses.xls" -H "X-Object-Meta-business: campaign"
Request headers
COPY /swift/v1/AUTH_6b6884ebb6f441cfbb7e740f6a927c9e/sales-mktg/campaign/GoGetEm.xls HTTP/1.1 X-Auth-Token: dc5efec8f546455eac974e7bbfd0dd87 x-Object-business: campaign Destination: /finance/mktg/campaign_GoGetEm_expenses.xls
Response headers
HTTP/1.1 201 Created Date: Mon, 03 Nov 2014 14:06:29 GMT X-Trans-Id: 1c66338b-d2e8-49ab-aa46-15f41677a919 ETag: d41d8cd98f00b204e9800998ecf8427e Content-Type: application/octet-stream Content-Length: 0 X-Copied_From-Last-Modified:Mon, 03 Nov 2014 14:06:29 GMT X-Copied-From: /finance/mktg/campaign_GoGetEm_expenses.xls Last-Modified: Mon, 03 Nov 2014 14:06:29 GMT