Copying an object or version of an object
You use the HTTP PUT method to copy an object or existing version of an object from one location to another. The copy operation has these characteristics:
- The source location can be any namespace, including the default namespace.
- The target location must be an HCP namespace within the source tenant and can include the source namespace.
- The name of the target object can differ from the name of the source object.
- The copied object inherits all its system metadata from the target namespace default values and does not have any ACL values. However, you can specify whether custom metadata is copied with the object data.
- When versioning is enabled, the target object gets a new version ID that differs from the source object version ID.
You cannot store a new version of an object that is under retention or on hold in the target namespace.
Copying a large object can take some time. If a client times out because a copy operation is taking too long, HCP continues the operation in the background.
Because the connection to the client is broken, HCP cannot report the completion of the copy operation to the client. Until the operation is complete, HCP returns a 404 Not Found status code in response to HEAD requests for the object being created by the copy operation.
After a copy operation finishes successfully, HCP returns information about the new object in response to HEAD requests for the object. If the operation does not succeed, HCP continues to return a 404 Not Found status code in response to HEAD requests for the object.
If copy operations are causing a client to time out, consider increasing the client timeout interval.
Access permission
To copy an object or version, you need read permission for the source namespace and write permission for the target namespace.
Request header
PUT /rest/directory/file HTTP/1.1
The PUT request to copy an object or version of an object has these elements:
- If you’re accessing the target namespace as an authenticated user, an Authorization header
- An
X-HCP-CopySource
header in this format:X-HCP-CopySource: source-namespace-name.source-tenant-name/source-object-path
The value of the
X-HCP-CopySource
header must be URL-encoded. - A URL specifying the location in which to store the object
X-HCP-CopySource
header identifies a directory, HCP creates an empty directory with the path specified in the target URL, assuming the specified path does not already exist.Parameter | Required | Description |
directory | Yes | Folder name. |
file | Yes | Name of the file, including file extension. |
version | No |
One of:
These rules apply to the
|
deleted | No |
By default, the GET request to retrieve object versions does not include delete markers. To retrieve a listing that includes delete marker, specify this URL query parameter: deleted=true You can also specify |
forceEtag | No | To force HCP to generate an ETag for an object that does not yet have one, specify a forceEtag URL query parameter with a value of true . |
Response headers
This option does not return any request-specific HCP-specific headers.
The request to copy an object returns an ETag header.
ETag
The ETag of the object or version enclosed in double quotation marks ("). This header is returned only if the object has an ETag.
Response body
Not applicable.
Return codes
The table below describes the HTTP return codes that have specific meaning for this request.
Code | Meaning | Description |
201 | Created | HCP successfully copied the object. If versioning is enabled and an object with the same name already exists, HCP created a new version of the object. |
204 | No Content | The requested version is a delete marker. |
304 | Not Modified |
One of:
|
400 | Bad Request |
The request was not valid. These are some, but not all, of the possible reasons:
If more information about the error is available, the HTTP response headers include the HCP-specific |
403 | Forbidden |
One of:
If more information about the error is available, the HTTP response headers include the HCP-specific |
404 | Not Found |
One of:
|
409 | Conflict |
One of:
|
410 | Gone |
Possible reasons include:
|
412 | Precondition Failed |
One of:
|
413 | File Too Large | Not enough space is available to store the object. Try the request again after objects or versions are deleted from the target namespace or the namespace capacity is increased. |
503 | Service Unavailable |
Possible reasons include:
If this error persists, contact your tenant administrator. |
Example: Copying an object
Here’s a sample HTTP PUT request that copies an object named Q1_2012.ppt from the default namespace if the source object has been modified since midnight, Tuesday, January 1, 2013 EST. The request stores the object, using the source object name, in the finance namespace.
Request with curl command line
curl -k -i -X PUT -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d" -H "X-HCP-CopySource: default.europe/quarterly_rpts/Q1_2012.ppt" -H "X-HCP-CopySource-If-Modified-Since: Tue, Jan 1 2013 05:00:00 GMT" "https://finance.europe.hcp.example.com/rest/quarterly_rpts/Q1_2012.ppt"
Request in Python using PycURL
import pycurl import os headers = ["Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d", "X-HCP-CopySource: default.europe/quarterly_rpts/ \ Q1_2012.ppt", "X-HCP-CopySource-If-Modified-Since: Tue, Jan 1 2013 05:00:00 GMT" curl = pycurl.Curl() curl.setopt(pycurl.URL, "https://finance.europe.hcp.example.com/ \ rest/quarterly_rpts/Q1_2012.ppt") curl.setopt(pycurl.SSL_VERIFYPEER, 0) curl.setopt(pycurl.SSL_VERIFYHOST, 0) curl.setopt(pycurl.HTTPHEADER, headers) curl.setopt(pycurl.PUT, 1) curl.setopt(pycurl.INFILESIZE, 0 curl.perform() print curl.getinfo(pycurl.RESPONSE_CODE) curl.close()
Request headers
PUT /rest/quarterly_rpts/Q1_2012.ppt HTTP/1.1 Host: /finance.europe.hcp.example.com Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d X-HCP-CopySource: default.europe/quarterly_rpts/Q1_2012.ppt X-HCP-If-Modified-Since: Tue, Jan 01 2013 05:00:00 GMT" Content-Length: 678400
Response headers
HTTP/1.1 200 Created X-HCP-ServicedBySystem: hcp.example.com Location: /rest/quarterly_rpts/Q1_2012.ppt ETag: "9c604138ffb0f308a8552a3752e5a1be" X-HCP-VersionId: 86675191823873 X-HCP-Hash: SHA-256 E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934C... X-HCP-Time: 1354299872 Content-Length: 0