HCP System Management Help
The GET request to retrieve an object has these elements:
•If you’re accessing the namespace as an authenticated user, an Authorization header
•The URL of the object or symbolic link
By default, the GET request to retrieve object versions does not include deleted versions (that is, the marker versions that indicate when an object was deleted). To retrieve a listing that includes deleted versions, specify this URL query parameter:
deleted=true
You can also specify deleted=false, which results in the default behavior.
Requesting a specific old version
To retrieve a specific old version of an object, specify the version URL query parameter with the ID of the version you want. You can omit this parameter to retrieve the current version of an object.
To find the ID of the version you want, list the versions of the object. For more information on listing the versions of an object, see Listing object versions.
Requesting the latest version at a specified time
To retrieve the latest version of an object at a specified time, specify the version URL query parameter with the ingest time of the version you want. You can omit this parameter to retrieve the current version of an object.
To find the ingest time of the version you want, list the versions of the object. For more information on listing the versions of an object, see Listing object versions.
Requesting a range of versions
To retrieve a range of versions of an object, specify the version URL query parameter with the range of object version IDs you want. You can omit this parameter to retrieve the current version of an object.
To find the ID of the versions you want, by list the versions of the object, as described in Listing object versions.
The version range query parameter has this format:
?version=<StartVersionID>-<EndVersionID>
The table below shows the ways in which you can specify the range.
Range specification | Description | Example |
---|---|---|
StartVersionID–End-VersionID |
VersionID in StartVersionID through EndVersionID, inclusive. |
Object versions beginning with 91728994268353 through object version 91728994618369: 91728994268354-91728994618369 |
StartVersionID- |
VersionID in StartVersionID through the end of the object versions. |
All the bytes beginning with 91728994618369 and continuing through the end of the object versions: 91728994618370- |
0- | All VersionIDs. | All object versions: 0- |
These rules apply to the version range query parameter:
•If you omit the parameter, HCP retrieve 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.
Conditionally retrieving an object or version
To retrieve an a single object or version only if the object meets certain conditions, use the headers listed in Conditional operations.
Forcing the generation of an ETag
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. For more information see Conditional operations.
Requesting data in compressed format
To request that HCP return an single object or version in gzip-compressed format, use an Accept-Encoding header containing the value gzip or *. The header can specify additional compression algorithms, but HCP uses only gzip.
You can request a single object or version data in compressed format with any of the additional request elements described in the sections below.
Choosing not to wait for delayed retrievals
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. To do this, use the nowait URL query parameter.
When a GET request fails because the request would take a significant amount of time to return an object and the nowait parameter is specified, HCP returns an HTTP 503 (Service Unavailable) error code.
![]() |
Tip: If the request specifies nowait and HCP returns a 503 error code, retry the request a few times, waiting about thirty seconds in between retries. |
Retrieving object data and an annotation together
To retrieve a single object or version data and one annotation with a single request, specify these elements:
•A type URL query parameter with a value of whole-object.
•An annotation URL query parameter with a value of the name of the annotation. You can omit this parameter for the default annotation.
•Optionally, an X-HCP-CustomMetadataFirst header specifying the order of the parts. Valid values are:
otrue — The annotation should precede the object data.
ofalse — The object data should precede the annotation.
The default is false.
Requesting partial object data
To retrieve only part of a single object or version data, specify an HTTP Range request header with the range of bytes of the object data to retrieve. You specify the Range header in addition to other request elements described above. The first byte of the data is in position 0 (zero), so a range of 1-5 specifies the second through sixth bytes of the object, not the first through fifth.
The Range header has this format:
Range: bytes=range
The table below shows the ways in which you can specify the range.
Range specification | Description | Example |
---|---|---|
start-position–end-position |
Bytes in start-position through end-position, inclusive. If end-position is greater than the size of the data, HCP returns the bytes in start-position through the end of the data. |
Five hundred bytes beginning with the two-hundred-first: 200-699 |
Start-position - |
Bytes in start-position through the end of the object data. |
All the bytes beginning with the seventy-sixth and continuing through the end of the object data: 75- |
- offset-from-end |
Bytes in the offset-from-end position, counted back from the last position in the object data, through the end of the object data. |
The last 25 bytes of the object data: ‑25 |
These rules apply to the Range header:
•If you omit the Range header, HCP returns the complete object data.
•If you specify a valid range, HCP returns the requested amount of data with a status code of 206.
•If you specify an invalid range, HCP ignores it and returns the complete object data, with a status code of 416.
•You cannot request partial object data with custom metadata in the same request. If the request includes a Range header and a type=whole-object query parameter, HCP returns a status code of 400.
Trademarks and Legal Disclaimer
© 2017 Hitachi Vantara Corporation. All rights reserved.