Copying an object or version of an object

Content Platform Tenant Management Help

Version
9.7.x
File Size
4269 KB
Audience
anonymous
Part Number
MK-95HCPH002-19

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.

Note: Depending on the replication configuration, copy operations may be slow, thereby increasing the likelihood of client timeouts.

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
Note: If the 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:

  • Specific version number of the file. For example:
    ?version=80232998058817
  • Range of version IDs, separated by a dash. For example:
    ?version=91728994618369-91728994618372
  • Range of create timestamps, separated by a dash. For example:
    ?version=@1493911519817-@1493911519817
  • 0-, which provides all versions of an object.

These rules apply to the version query parameter:

  • If you omit the parameter, HCP checks the existence of the current version of an object.
  • If you specify a valid range, HCP returns the requested amount of data with a status code of 200.
deleted No

By default, the GET request to retrieve object versions does not include delete records. To retrieve a listing that includes delete records, specify this URL query parameter:

deleted=true

You can also specify deleted=false, which results in the default behavior.

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.

Status codes

The table below describes the HTTP status 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.
304 Not Modified

One of:

  • A request to copy an object specified an X-HCP-Copy-Source-If-None-Match header, and the ETag of the source object matches the value in the header.
  • A request to copy an object specified X-HCP-Copy-Source-If-Modified-Since header, and the source object change time is at or before the time specified in the header.
  • A request to store a new version of an existing object specified an If-Modified-Since header, and the change time of the current version is at or before the time specified in the header.
400 Bad Request

The request was not valid. These are some, but not all, of the possible reasons:

  • The URL in the request is not well-formed.
  • Either the source or target namespace does not exist.
  • The target namespace has custom metadata XML checking enabled, and the copied object includes custom metadata that is not well-formed XML.

    If the request that causes this error included an X-HCP-MetadataDirective header with the value ALL, HCP creates an empty object before it returns the error. To resolve this issue, you can either:

    • Fix the custom metadata, and retry the request.
    • Copy the object again without custom metadata, thereby replacing the empty object. You can then fix the custom metadata at a later time and add it in a separate request.
  • The X-HCP-CopySource header identifies a symbolic link to an object.
  • The request included an If-Match or If-None-Match header and an existing target object does not yet have an ETag.
  • The request included an X-HCP-CopySource-If-Match or X-HCP-CopySource-If-None-Match header and did not include a forceEtag query parameter, and the source object does not yet have an ETag.
  • The request contained an unsupported query parameter or an invalid value for a query parameter.

If more information about the error is available, the HTTP response headers include the HCP-specific X‑HCP-ErrorMessage header.

403 Forbidden

One of:

  • The Authorization header or hcp-ns-auth cookie specifies invalid credentials.
  • The target location must be an HCP namespace within the source tenant.
  • The target namespace requires client authentication, and the request does not include an Authorization header or hcp-ns-auth cookie.
  • The user doesn’t have read permission in the source namespace or write permission in the target namespace.
  • For a request to create a new version of an existing object, the object is under retention.
  • The access method (HTTP or HTTPS) is disabled.

If more information about the error is available, the HTTP response headers include the HCP-specific X‑HCP-ErrorMessage header.

404 Not Found

One of:

  • The specified source object or object version does not exist.
  • The current version of the specified source object is a delete marker or delete record.
  • Any component of the source or target URL except for the last component in the path is a symbolic link to a directory.
409 Conflict

One of:

  • HCP could not store the object in the namespace because the object already exists and versioning is not enabled.
  • HCP could not store a new version of an existing object because another version is currently being added.
  • HCP could not evaluate conditional headers because a version of the object is currently being added.
410 Gone

Possible reasons include:

  • The source object exists, but the HCP system does not have the source object data. Retry the request, targeting a different system in the replication topology.
  • The source object is in the process of being deleted.
412 Precondition Failed

One of:

  • A request to copy an object specified an X-HCP-Copy-Source-If-Match header, and the ETag of the source object does not match the value in the header.
  • A request to copy an object specified an X-HCP-Copy-Source-If-Unmodified-Since header, and the source object change time is after the time specified in the header.
  • A request to copy a new version of an object specified an If-Match header, and the ETag of the target object does not match the value in the header.
  • A request to copy a new version of an object specified an If-None-Match header, and the ETag of the target object matches the value in the header.
  • A request to copy a new version of an object specified an If-Unmodified-Since header, and the target object change time is after the time specified in the header.
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:

  • 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

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