Retrieving an object or multiple versions of an object
You use the HTTP GET method to retrieve an object, a version of an object, or a range of versions of an object from a namespace. When retrieving an single object or version, you can request all the object data or part of the data. When retrieving multiple versions of an object, you can only request all the object data.
You can use a GET request to retrieve all the object data of a single object or version and an annotation together. You cannot retrieve part of the object data together with an annotation in a single request. You can also use a GET request to retrieve the timestamp range of an object, which you can use to find a version of that object.
Using GET with a symbolic link returns the current version of the object that is the target of the link.
Access permission
To retrieve an object or version, you need read permission.
Request header
GET /rest/directory/file?version=@version&deleted=true HTTP/1.1
The GET request to retrieve an object has these elements:
- If you are accessing the namespace as an authenticated user, an
Authorization
header - The URL of the object or symbolic link
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 . |
nowait | No |
HCP may detect that a GET request will take a significant amount of time to return an object. You can choose to have the request fail in this situation instead of waiting for HCP to return the object. When a GET request fails because the request would take a significant amount of time to return an object and the |
type | No | Use the value whole-object to retrieve a single object or version data. |
annotation | No | Use a value of the name of the annotation. You can omit this parameter for the default annotation.Used in conjunction with the type parameter. |
Response headers for retrieving a single object or version
The next list describes request-specific response headers for the retrieving a single object or version of the an object.
The response headers for retrieving multiple objects or object versions are described in the next section.
ChangeTimeString
The change time for the object in this format:
DDD, ddmmmyyyyhh:mm:ss GMT
For example, Fri, 18 Sep 2020 21:02:13 GMT.
This header contains the same datetime value as the
X-HCP
-ChangeTimeMilliseconds
andX-HCP-ChangeTimeString
headers, but in a format that can be used directly inIf-Modified-Since
andIf-Unmodified-Since
request headers.Content-Encoding
Always
gzip
.This header is returned only if HCP compressed the response before returning it.
Content-Length
The length, in bytes, of the returned data. These considerations apply:
- If you requested that the response be compressed, this is the compressed size of the returned data.
- If you requested uncompressed object data without custom metadata, the value of this header is the same as the value of the
X-HCP-Size
header. - If you requested uncompressed partial content, the value is the size of the returned part. This value is equal to the difference between the start-position and end-position values in the
Content-Range
header plus one byte. - If you requested uncompressed object data and custom metadata, the value is the sum of the size of the object data (the
X-HCP-Size
header) and the size of the custom metadata.
If the returned data is large, HCP might send a chunked response, which does not include this header.
Content-Range
Returned only when getting partial content.
The byte range of the returned object data, in this format:
start-position–end-position / object-size
where object-size is the total size of the object data and is the same as the value of the
X-HCP-Size
header.Content-Type
The type of content for the object:
- If you requested all or part of the object data only, this is the Internet media type of the object data, such as
text/plain
orimage/jpg
. - If you requested the object data and an annotation together, this value is always
application/octet-stream
.
- If you requested all or part of the object data only, this is the Internet media type of the object data, such as
ETag
The ETag of the object or version enclosed in double quotation marks ("). This header is returned only if the object has an ETag.
X-HCP-ACL
A
true
orfalse
value indicating whether the object has an ACL.X-HCP-ChangeTimeMilliseconds
The change time for the object, in milliseconds since January 1, 1970, at 00:00:00 UTC, followed by an integer that is unique for the change time. For example: 1336483100178.00.
X-HCP-ChangeTimeString
The change time for the object in this format:
yyyy-MM-ddThh:mm:ssZ
In this format, Z represents the offset from UTC and is specified as:
(+|-)hhmm
For example, 2020-09-18T09:18:20-0400 represents the start of the 20th second into 9:18 AM, September 18, 2020, EDT.
X-HCP-ContentLength
The uncompressed length of the returned data. If the response returns object data only, this header and the
X-HCP-Size
header are equal.This header is returned only if HCP compresses the data before returning it.
X-HCP-Custom-Metadata
A
true
orfalse
value indicating whether the object has any annotations.X-HCP-CustomMetadataAnnotations
A comma-and-space-separated list containing the names and sizes of all object annotations. Each entry in the list consists of the annotation name, a semicolon (;) and the annotation size in bytes. For example:
report_data; 12908
.This header is returned only if
X-HCP-Custom-Metadata
istrue
.X-HCP-CustomMetadataContentType
The annotation type, one of:
text/xml
If HCP checked for well-formed XML when the annotation was stored
unknown
otherwise
This header is returned only if the request asked for the object data and an annotation.
X-HCP-CustomMetadataFirst
One of:
true
The annotation precedes the object data.
false
The object data precedes the annotation.
X-HCP-DataContentType
The object Internet media type, such as
text/plain
orimage/jpg
.This header is returned only if the request asked for the object data and an annotation.
X-HCP-Domain
The Active Directory domain that contains the user identified by the
X-HCP-Owner
header.This value is an empty string if the
X-HCP-Owner
header identifies a user account defined in HCP or if the object has no owner.If the
X-HCP-Owner
header returns a user account ID or nobody, the value of theX-HCP-Domain
header is one of several invalid domains that begin with the percent sign (%). These values have meanings internal to the HCP system.X-HCP-DPL
The data protection level for the object.
X-HCP-GID
The POSIX group ID for the object.
For objects added through the NFS protocol, this value is determined by the NFS client.
This value is an empty string if either of these conditions is true:
- The object was added through a protocol other than NFS and neither the UID nor the GID for the object has been changed.
- The HCP product-specific owner of the object was changed.
X-HCP-Hash
The cryptographic hash algorithm HCP uses, along with the cryptographic hash value stored for the object, in this format:
X-HCP-Hash: hash-algorithmhash-value
You can use the returned hash value to verify that the stored data is the same as the data you sent. To perform the verification, compare this value with a hash value that you generate from the original data.
The
X-HCP-Hash
header is not returned for multipart objects.X-HCP-Index
A
true
orfalse
value indicating whether the object is marked for indexing.X-HCP-IngestProtocol
The namespace access protocol through which the object was added to the namespace. Possible values are:
CIFS_NFS
HTTP
SMTP
WebDAV
If HCP cannot determine the protocol through which the object was added, this value is
UNKNOWN
.X-HCP-IngestTime
The time when HCP stored the object, in seconds since January 1, 1970, at 00:00:00 UTC.
x-HCP-LabelRetentionHold
Specifies whether the object is on labeled hold. A Boolean value (
true
|false
) is returned.x-HCP-LabelRetentionHold-Labels
If the object is on labeled hold (
X-HCP-LabelRetentionHold:true
) and the user has privileged data access and read permissions on the object, this header is returned with a list of all labeled holds.Example
X-HCP-LabelRetentionHold-Labels: [{"id":"UniqueLabelHold-1","hold": true}, [{"id":"UniqueLabelHold-2","hold": true },[{"id":"UniqueLabelHold-3","hold": true }]
X-HCP-LastVersionId
The version ID of the last returned object version.
X-HCP-Owner
The user that owns the object.
This value is an empty string if the object has no owner.
This value is
nobody
for objects that were stored by an authenticated user before the HCP system was upgraded from a release earlier than 5.0. These objects effectively have no owner.This value is a user account ID if HCP can no longer identify the object owner by username. For example, you would see a user account ID if the HCP user account has been deleted.
X-HCP-Replicated
A
true
orfalse
value indicating whether the object, has been replicated. The value istrue
only if the current version of the object, its system metadata, annotations (if any), and ACL (if any) have been replicated.HCP returns this header only if either of these conditions is true:
- HCP is configured to return this header, and the request does not include the
X-HCP-Get-Replicated
header with a value offalse
. - The request includes the
X-HCP-Get-Replicated
header with a value oftrue
.
- HCP is configured to return this header, and the request does not include the
X-HCP-ReplicationCollision
A
true
orfalse
value indicating whether the object is flagged as a replication collision.X-HCP-Retention
The end of the retention period for the object. Possible values are:
- A time in seconds since January 1, 1970, at 00:00:00 UTC
0
-1
-2
X-HCP-RetentionClass
The name of the retention class to which the object belongs.
This value is an empty string if the object is not in a retention class.
X-HCP-RetentionHold
A
true
orfalse
value indicating whether the object is on hold.X-HCP-RetentionString
The end of the retention period for the object. Possible values are:
- A date and time in this format:
yyyy-MM-ddThh:mm:ssZ
In this format, Z represents the offset from UTC and is specified as:
(+|-)hhmm
For example, 2019-12-14T14:27:20-0500 represents the start of the 20th second into 2:27 PM, December 14, 2019, EST.
Deletion Allowed
Deletion Prohibited
Initial Unspecified
- A date and time in this format:
X-HCP-Shred
A
true
orfalse
value indicating whether HCP will shred the object after the object is deleted.X-HCP-Size
The size of the object data, in bytes.
X-HCP-SoftwareVersion
The version number of the HCP software.
X-HCP-SymlinkTarget
The path to the target object as specified when the symbolic link was created.
This header is returned only if the URL specifies a symbolic link to an object.
If this header is returned, the
X-HCP-ACL
value is alwaysfalse
.X-HCP-Type
The object entity type.
X-HCP-UID
The POSIX user ID for the object.
For objects added through the NFS protocol, this value is determined by the NFS client.
This value is an empty string if either of these conditions are true:
- The object was added through a protocol other than NFS and neither the UID nor the GID for the object was changed.
- The HCP product-specific owner of the object was changed.
X-HCP-VersionId
The version ID of the object.
Response headers for retrieving a range of object versions
The next list describes request-specific response headers for retrieving a range of object versions from a namespace.
When retrieving multiple versions of an object, you can only request all the object data. Four headers are returned for each object version, as described in the following list.
X-HCP-VersionID
The version ID of the object or object version.
X-HCP-Operation
Whether the object or object version is created or deleted.
X-HCP-IngestTimeMilliseconds
The time when HCP stored the object or object version, in seconds since January 1, 1970, at 00:00:00 UTC.
X-HCP-Size
The size of the object or object version in bytes.
Return codes
Code | Meaning | Description |
200 | OK |
HCP successfully processed the request. This code is also returned if the URL specified a valid directory path and HCP returned a directory listing. Note: For a request for an object or version, if the number of bytes returned does not equal the value of the |
204 | No Content | The requested version is a delete marker. |
206 | Partial Content | HCP successfully retrieved the data in the byte range specified in the request. |
304 | Not Modified |
One of:
|
400 | Bad Request |
The request was not valid. Possible reasons include:
If more information about the error is available, the response headers include the HCP product-specific |
403 | Forbidden |
The requested operation is not allowed. Possible reasons include:
If more information about the error is available, the response headers include the HCP product-specific |
404 | Not Found |
One of:
|
406 | Not Acceptable | The request has an Accept-Encoding header that does not include gzip or * . |
410 | Gone |
Possible reasons include:
|
412 | Precondition Failed |
One of:
|
416 | Requested Range Not Satisfiable |
One of:
|
503 | Service Unavailable |
Possible reasons include:
Try the request again, gradually increasing the delay between each successive attempt. If the error persists, contact your tenant administrator. |
Example: Retrieving all object data
Here’s a sample HTTP GET request that retrieves an object named Q1_2012.ppt in the quarterly_rpts directory.
Request with curl command line
curl -k -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d" "https://finance.europe.hcp.example.com/rest/quarterly_rpts/Q1_2012.ppt" > Q1_2012.ppt
Request in Python using PycURL
import pycurl filehandle = open("Q1_2012.ppt", 'wb') curl = pycurl.Curl() curl.setopt(pycurl.HTTPHEADER, ["Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"]) 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.WRITEFUNCTION, filehandle.write) curl.perform() print curl.getinfo(pycurl.RESPONSE_CODE) curl.close() filehandle.close()
Request headers
GET /rest/quarterly_rpts/Q1_2012.ppt HTTP/1.1 Host: finance.europe.hcp.example.com Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d
Response headers
HTTP/1.1 200 OK X-HCP-Time: 1336490468 X-HCP-SoftwareVersion: 7.0.0.16 Content-Type: application/vnd.ms-powerpoint Content-Length: 678400 X-HCP-ServicedBySystem: hcp.example.com ETag: "d45e5b124c1807d6ec4f8088b5e51f8d" X-HCP-Type: object X-HCP-Size: 678400 X-HCP-Hash: SHA-256 36728BA190BC4C377FE4C1A57AEF9B6AFDA98720422960... X-HCP-VersionId: 80205544854849 X-HCP-IngestTime: 1334829227 X-HCP-RetentionClass: X-HCP-RetentionString: Deletion Allowed X-HCP-Retention: 0 X-HCP-IngestProtocol: HTTP X-HCP-RetentionHold: false X-HCP-Shred: false X-HCP-DPL: 2 X-HCP-Index: false X-HCP-Custom-Metadata: false X-HCP-ACL: false X-HCP-Owner: lgreen X-HCP-Domain: X-HCP-UID: X-HCP-GID: X-HCP-Replicated: false X-HCP-ReplicationCollision: false X-HCP-ChangeTimeMilliseconds: 1335347627362.00 X-HCP-ChangeTimeString: 2012-04-25T05:53:47-0400 Last-Modified: Wed, 25 Apr 2012 09:53:47 GMT
Response body is the contents of the Q1_2012.ppt object
Example: Retrieving object data in compressed format (command line)
Here’s a sample curl command that tells HCP to compress the Q1_2012.ppt object before sending it to the client and then decompresses the returned content.
Request with curl command line
curl --compressed -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d" "https://finance.europe.hcp.example.com/rest/quarterly_rpts/Q1_2012.ppt" > Q1_2012.ppt -k
Request in Python using PycURL
import pycurl filehandle = open("Q1_2012.ppt", 'wb') curl = pycurl.Curl() curl.setopt(pycurl.HTTPHEADER, ["Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"]) 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.ENCODING, 'gzip') curl.setopt(pycurl.WRITEFUNCTION, filehandle.write) curl.perform() print curl.getinfo(pycurl.RESPONSE_CODE) curl.close() filehandle.close()
Request headers
GET /rest/quarterly_rpts/Q1_2012.ppt HTTP/1.1 Host: finance.europe.hcp.example.com Accept-Encoding: deflate, gzip Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d
Response headers
HTTP/1.1 200 OK X-HCP-Time: 1336490468 X-HCP-SoftwareVersion: 7.0.0.16 Content-Type: application/vnd.ms-powerpoint X-HCP-ServicedBySystem: hcp.example.com ETag: "827ccb0eea8a706c4c34a16891f84e7b" X-HCP-Type: object X-HCP-Size: 678400 X-HCP-Hash: SHA-256 36728BA190BC4C377FE4C1A57AEF9B6AFDA98720422960... X-HCP-VersionId: 80205544854849 X-HCP-IngestTime: 1334426531 X-HCP-RetentionClass: X-HCP-RetentionString: Deletion Allowed X-HCP-Retention: 0 X-HCP-IngestProtocol: HTTP X-HCP-RetentionHold: false X-HCP-Shred: false X-HCP-DPL: 2 X-HCP-Index: true X-HCP-Custom-Metadata: false X-HCP-ACL: false X-HCP-Owner: myuser X-HCP-Domain: X-HCP-UID: X-HCP-GID: X-HCP-Replicated: false X-HCP-ReplicationCollision: false X-HCP-ChangeTimeMilliseconds: 1335347627362.00 X-HCP-ChangeTimeString: 2012-04-25T05:53:47-0400 Last-Modified: Wed, 25 Apr 2012 09:53:47 GMT Content-Encoding: gzip Transfer-Encoding: chunked
Response body: The contents of the Q1_2012.ppt object in gzip-compressed format.
Example: Retrieving object data in compressed format (Java)
Here’s the partial implementation of a Java class named HTTPCompression. The implementation shows the ReadFromHCP method, which retrieves an object from an HCP namespace. It uses the Accept-Encoding
header to tell HCP to compress the object before returning it and then decompresses the results.
import org.apache.http.client.methods.HttpGet; import org.apache.http.HttpResponse; import org.apache.http.EntityUtils; import java.util.zip.GZIPInputStream; class HTTPCompression { . . . void ReadFromHCP() throws Exception { /* * Set up the GET request. * * This method assumes that the HTTP client has already been * initialized. */ HttpGet httpRequest = new HttpGet(sHCPFilePath); // Indicate that you want HCP to compress the returned data with gzip. httpRequest.setHeader("Accept-Encoding", "gzip"); // Create the HCP authorization header. httpRequest.setHeader("Authorization", "HCP " + sEncodedUserName + ":" + sEncodedPassword); /* * Now execute the GET request. */ HttpResponse httpResponse = mHttpClient.execute(httpRequest); /* * Process the HTTP Response. */ // If the return code is anything but in the 200 range indicating // success, throw an exception. if (2 != (int)(httpResponse.getStatusLine().getStatusCode() / 100)) { // Clean up after ourselves and release the HTTP connection to the // connection manager. EntityUtils.consume(httpResponse.getEntity()); throw new Exception("Unexpected HTTP status code: " + httpResponse.getStatusLine().getStatusCode() + " (" + httpResponse.getStatusLine().getReasonPhrase() + ")"); } /* * Write the decompressed file to disk. */ FileOutputStream outputFile = new FileOutputStream( sBaseFileName + ".fromHCP"); // Build the string that contains the response body for return to the // caller. GZIPInputStream bodyISR = new GZIPInputStream(httpResponse.getEntity().getContent()); byte partialRead[] = new byte[1024]; int readSize = 0; while (-1 != (readSize = bodyISR.read(partialRead))) { outputFile.write(partialRead, 0, readSize); } // Clean up after ourselves and release the HTTP connection to the // connection manager. EntityUtils.consume(httpResponse.getEntity()); } . . . }
Example: Retrieving a specific old version of an object
Here’s a sample HTTP GET request that retrieves version 80232998058817 of an object named Q1_2012.ppt in the quarterly_rpts directory.
Request with curl command line
curl -k -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d" "https://finance.europe.hcp.example.com/rest/quarterly_rpts/Q1_2012.ppt ?version=80232998058817" > Q1_2012.ppt
Request in Python using PycURL
import pycurl filehandle = open("Q1_2012.ppt", 'wb') curl = pycurl.Curl() curl.setopt(pycurl.HTTPHEADER, ["Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"]) curl.setopt(pycurl.URL, "https://finance.europe.hcp.example.com/ rest/quarterly_rpts/Q1_2012.ppt%3Fversion=80232998058817") curl.setopt(pycurl.SSL_VERIFYPEER, 0) curl.setopt(pycurl.SSL_VERIFYHOST, 0) curl.setopt(pycurl.WRITEFUNCTION, filehandle.write) curl.perform() print curl.getinfo(pycurl.RESPONSE_CODE) curl.close() filehandle.close()
Request headers
GET /rest/quarterly_rpts/Q1_2012.ppt?version=80232998058817 HTTP/1.1 Host: finance.europe.hcp.example.com Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d
Response headers
HTTP/1.1 200 OK X-HCP-Time: 1336490468 X-HCP-SoftwareVersion: 7.0.0.16 Content-Type: application/vnd.ms-powerpoint Content-Length: 678400 X-HCP-ServicedBySystem: hcp.example.com ETag: "827ccb0eea8a706c4c34a16891f84e7b" X-HCP-Type: object X-HCP-Size: 678400 X-HCP-Hash: SHA-256 36728BA190BC4C377FE4C1A57AEF9B6AFDA98720422960... X-HCP-VersionId: 80232998058817 X-HCP-IngestTime: 1334426531 X-HCP-VersionCreateTimeMilliseconds: 1508940313887 X-HCP-RetentionClass: X-HCP-RetentionString: Deletion Allowed X-HCP-Retention: 0 X-HCP-IngestProtocol: HTTP X-HCP-RetentionHold: false X-HCP-Shred: false X-HCP-DPL: 2 X-HCP-Index: true X-HCP-Custom-Metadata: false X-HCP-ACL: false X-HCP-Owner: myuser X-HCP-Domain: X-HCP-UID: X-HCP-GID: X-HCP-Replicated: false X-HCP-ReplicationCollision: false X-HCP-ChangeTimeMilliseconds: 1335347627362.00 X-HCP-ChangeTimeString: 2012-04-25T05:53:47-0400 Last-Modified: Wed, 25 Apr 2012 09:53:47 GMT
Response body: The contents of the requested version of the object.
Example: Retrieving the last object version created at a specified time
Here’s a sample HTTP GET request that retrieves the version of an object named Q1_2012.ppt in the quarterly_rpts directory that was created at 1433265536867.
Request with curl command line
curl -i -k -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d" "https://finance.europe.hcp.example.com/rest/quarterly_rpts/Q1_2012.ppt ?version=@1433265536867" > Q1_2012.ppt
Request in Python using PycURL
import pycurl filehandle = open("Q1_2012.ppt", 'wb') curl = pycurl.Curl() curl.setopt(pycurl.HTTPHEADER, ["Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"]) curl.setopt(pycurl.URL, "https://finance.europe.hcp.example.com/ \ rest/quarterly_rpts/Q1_2012.ppt?version=@1433265536867") curl.setopt(pycurl.SSL_VERIFYPEER, 0) curl.setopt(pycurl.SSL_VERIFYHOST, 0) curl.setopt(pycurl.WRITEFUNCTION, filehandle.write) curl.perform() print curl.getinfo(pycurl.RESPONSE_CODE) curl.close() filehandle.close()
Request headers
GET /rest/quarterly_rpts/Q1_2012.ppt?version=@1433265536867 HTTP/1.1 Host: finance.europe.hcp.example.com Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d
Response headers
HTTP/1.1 200 OK Date: Wed, 03 Jun 2015 16:42:45 GMT X-HCP-ServicedBySystem: hcp.example.com X-HCP-Time: 1433349765 X-HCP-SoftwareVersion: 7.2.0.346 ETag: "827ccb0eea8a706c4c34a16891f84e7b" Expires: Thu, 01 Jan 1970 00:00:00 GMT Content-Type: application/vnd.ms-powerpoint Content-Disposition: attachment; Content-Length: 678400 X-HCP-Type: object X-HCP-Size: 678400 X-HCP-Hash: SHA-256 36728BA190BC4C377FE4C1A57AEF9B6AFDA98720422960... X-HCP-VersionId: 80232998058817 X-HCP-IngestTime: 1433265536 X-HCP-VersionCreateTimeMilliseconds: 1508940313887 X-HCP-RetentionClass: X-HCP-RetentionString: Deletion Allowed X-HCP-Retention: 0 X-HCP-IngestProtocol: HTTP X-HCP-RetentionHold: false X-HCP-Shred: false X-HCP-DPL: 2 X-HCP-Index: true X-HCP-Custom-Metadata: false X-HCP-ACL: false X-HCP-Owner: myuser X-HCP-Domain: X-HCP-UID: X-HCP-GID: X-HCP-CustomMetadataAnnotations: X-HCP-Replicated: false X-HCP-ReplicationCollision: false X-HCP-ChangeTimeMilliseconds: 1433265537266.00 X-HCP-ChangeTimeString: 2015-06-02T13:18:57-0400 Last-Modified: Tue, 02 Jun 2015 17:18:57 GMT
Response body: The contents of the requested version of the object.
Example: Retrieving a range of an object's versions using version ID
Here’s a sample HTTP GET request that checks the existence of a range of object versions for an object named Q1_2012.ppt in the quarterly_rpts directory using version IDs. The version range for the object is 80232998058817-80232998058819.
Request with curl command line
curl -i -k -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d" "https://finance.europe.hcp.example.com/rest/quarterly_rpts/Q1_2012.ppt ?version=80232998058817-80232998058819" > Q1_2012.ppt
Request in Python using PycURL
import pycurl import StringIO cin = StringIO.StringIO() curl = pycurl.Curl() curl.setopt(pycurl.HTTPHEADER, ["Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"]) curl.setopt(pycurl.URL, "https://finance.europe.hcp.example.com/ \ rest/quarterly_rpts/Q1_2012.ppt?version=80232998058817-80232998058819") curl.setopt(pycurl.SSL_VERIFYPEER, 0) curl.setopt(pycurl.SSL_VERIFYHOST, 0) curl.setopt(pycurl.HEADER, 1) curl.setopt(pycurl.NOBODY, 1) curl.setopt(pycurl.WRITEFUNCTION, cin.write) curl.perform() print curl.getinfo(pycurl.RESPONSE_CODE) print cin.getvalue() curl.close()
Request headers
GET /rest/quarterly_rpts/Q1_2012.ppt?version=80232998058817-80232998058819 HTTP/1.1 Host: finance.europe.hcp.example.com Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d
Response headers
HTTP/1.1 200 OK Date: Wed, 03 Jun 2015 16:42:45 GMT Expires: Thu, 01 Jan 1970 00:00:00 GMT X-HCP-ServicedBySystem: hcp.example.com X-HCP-Time: 1433349765 X-HCP-SoftwareVersion: 7.2.0.346 X-HCP-LastVersionId: 80232998058819 Content-Length: 678400
Response body
X-HCP-VersionId: 80232998058817 X-HCP-Operation: CREATE X-HCP-IngestTimeMilliseconds: 1493911519817 X-HCP-Size: 9 The contents of the requested version of the object. X-HCP-VersionId: 80232998058818 X-HCP-Operation: CREATE X-HCP-IngestTimeMilliseconds: 1493911519818 X-HCP-Size: 9 The contents of the requested version of the object. X-HCP-VersionId:80232998058819 X-HCP-Operation: CREATE X-HCP-IngestTimeMilliseconds: 1493911519819 X-HCP-Size: 9 The contents of the requested version of the object.
Example: Retrieving a range of an object's versions using timestamp
Here’s a sample HTTP GET request that checks the existence of a range of object versions for an object named Q1_2012.ppt in the quarterly_rpts directory using ingest timestamps. The version ingest timestamp range for the object is @1493911519817–@1493911519820.
Request with curl command line
curl -i -k -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d" "https://finance.europe.hcp.example.com/rest/quarterly_rpts/Q1_2012.ppt ?version=@1493911519817–@1493911519820" > Q1_2012.ppt
Request in Python using PycURL
import pycurl import StringIO cin = StringIO.StringIO() curl = pycurl.Curl() curl.setopt(pycurl.HTTPHEADER, ["Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"]) curl.setopt(pycurl.URL, "https://finance.europe.hcp.example.com/ \ rest/quarterly_rpts/Q1_2012.ppt?version=@1493911519817–@1493911519820") curl.setopt(pycurl.SSL_VERIFYPEER, 0) curl.setopt(pycurl.SSL_VERIFYHOST, 0) curl.setopt(pycurl.HEADER, 1) curl.setopt(pycurl.NOBODY, 1) curl.setopt(pycurl.WRITEFUNCTION, cin.write) curl.perform() print curl.getinfo(pycurl.RESPONSE_CODE) print cin.getvalue() curl.close()
Request headers
GET /rest/quarterly_rpts/Q1_2012.ppt?version=@1493911519817–@1493911519820 HTTP/1.1 Host: finance.europe.hcp.example.com Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d
Response headers
HTTP/1.1 200 OK Date: Wed, 03 Jun 2015 16:42:45 GMT X-HCP-ServicedBySystem: hcp.example.com X-HCP-Time: 1433349765 X-HCP-SoftwareVersion: 7.2.0.346 X-HCP-LastVersionId: 80232998058819 Content-Length: 678400
Response body
X-HCP-VersionId: 80232998058817 X-HCP-Operation: CREATE X-HCP-IngestTimeMilliseconds: X-HCP-Size: 9 The contents of the requested version of the object. X-HCP-VersionId: 80232998058818 X-HCP-Operation: CREATE X-HCP-IngestTimeMilliseconds: 1493911519818 X-HCP-Size: 9 The contents of the requested version of the object. X-HCP-VersionId: 80232998058819 X-HCP-Operation: CREATE X-HCP-IngestTimeMilliseconds: 1493911519819 X-HCP-Size: 9 The contents of the requested version of the object.
Example: Retrieving object data and an annotation together (Java)
Here’s the partial implementation of a Java class named WholeIO. The implementation shows the ReadFromHCP method, which retrieves object data and an annotation named report_data
in a single data stream, splits the object data from the annotation, and stores each in a separate file.
The ReadFromHCP method uses the WholeIOOutputStream
helper class.
This example assumes that the applicable imports are included in the full class implementation.
class WholeIO { . . . void ReadFromHCP() throws Exception { /* * Set up the GET request, specifying whole-object I/O. * This method assumes that the HTTP client has already been * initialized. */ HttpGet httpRequest = new HttpGet(sHCPURLFilePath + "?type=whole-object&annotation=report_data"); // Create the HTTP Authorization Header. httpRequest.setHeader(HCPUtils.HTTP_AUTH_HEADER, "HCP " + sEncodedUserName + ":" + sEncodedPassword); // Request the annotation before the object data. // This can be useful if the application examines the annotation // to set the context for the data that will follow. httpRequest.setHeader("X-HCP-CustomMetadataFirst", "true"); /* * Now execute the GET request. */ HttpResponse httpResponse = mHttpClient.execute(httpRequest); // If the return code is anything BUT 200 range indicating success // throw an exception. if (2 != (int)(httpResponse.getStatusLine().getStatusCode() / 100)) { // Clean up after ourselves and release the HTTP connection to the // connection manager. EntityUtils.consume(httpResponse.getEntity()); throw new HttpResponseException( httpResponse.getStatusLine().getStatusCode(), "Unexpected status returned from " + httpRequest.getMethod() + " (" + httpResponse.getStatusLine().getStatusCode() + ": " + httpResponse.getStatusLine().getReasonPhrase() + ")"); } /* * Determine whether the object data or annotation is first. */ Boolean cmFirst = new Boolean(httpResponse.getFirstHeader( "X-HCP-CustomMetadataFirst").getValue()); /* * Determine the size of the first part based on whether the object * data or annotation is first. */ // Assume the object data is first. int firstPartSize = Integer.valueOf(httpResponse.getFirstHeader( "X-HCP-Size").getValue()); // If the annotation, do the math. if (cmFirst) { // subtract the data size from the content length returned. firstPartSize = Integer.valueOf(httpResponse.getFirstHeader( "Content-Length").getValue()) - firstPartSize; } /* * Split and write the file to disk. */ WholeIOOutputStream outputCreator = new WholeIOOutputStream( new FileOutputStream(sBaseFileName + ".fromHCP"), new FileOutputStream(sBaseFileName + ".fromHCP.cm"), cmFirst); outputCreator.copy(httpResponse.getEntity().getContent(), firstPartSize); outputCreator.close(); // Files should be created. // Clean up after ourselves and release the HTTP connection to the // connection manager. EntityUtils.consume(httpResponse.getEntity()); } . . . }
Example: Retrieving partial object data
Here’s a sample HTTP GET request that retrieves the first 10,000 bytes of an object named status27.txt in the status directory.
Request with curl command line
curl -k -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d" -r 0-9999 "https://finance.europe.hcp.example.com/rest/status/status27.txt" > status27a.txt
Request in Python using PycURL
import pycurl filehandle = open("status27a.txt", 'wb') curl = pycurl.Curl() curl.setopt(pycurl.HTTPHEADER, ["Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"]) curl.setopt(pycurl.RANGE, "0-9999") curl.setopt(pycurl.URL, "https://finance.europe.hcp.example.com \ /rest/status/status27.txt") curl.setopt(pycurl.SSL_VERIFYPEER, 0) curl.setopt(pycurl.SSL_VERIFYHOST, 0) curl.setopt(pycurl.WRITEFUNCTION, filehandle.write) curl.perform() print curl.getinfo(pycurl.RESPONSE_CODE) curl.close() filehandle.close()
Request headers
GET /rest/status/status27.txt HTTP/1.1 Range: bytes=0-9999 Host: finance.europe.hcp.example.com Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d
Response headers
HTTP/1.1 206 Partial Content X-HCP-Time: 1335347627 X-HCP-SoftwareVersion: 7.0.0.16 Content-Type: text/plain Content-Range: bytes 0-9999/38985 Content-Length: 10000 X-HCP-ServicedBySystem: hcp.example.com ETag: "39273c07f4709e6fea1c155c569fa29f" X-HCP-Type: object X-HCP-Size: 38985 X-HCP-Hash: SHA-256 36728BA190BC4C377FE4C1A57AEF9B6AFDA98720422960... X-HCP-VersionId: 80232488876481 X-HCP-IngestTime: 1334851131 X-HCP-RetentionClass: X-HCP-RetentionString: Deletion Allowed X-HCP-Retention: 0 X-HCP-IngestProtocol: HTTP X-HCP-RetentionHold: false X-HCP-Shred: false X-HCP-DPL: 2 X-HCP-Index: true X-HCP-Custom-Metadata: false X-HCP-ACL: false X-HCP-Owner: myuser X-HCP-Domain: X-HCP-UID: X-HCP-GID: X-HCP-Replicated: false X-HCP-ReplicationCollision: false X-HCP-ChangeTimeMilliseconds: 1335347627362.00 X-HCP-ChangeTimeString: 2012-04-25T05:53:47-0400 Last-Modified: Wed, 25 Apr 2012 09:53:47 GMT
Response body: The first 10,000 bytes of the contents of status27.txt