Specifying metadata on object creation
You use the HTTP PUT method to store an object in the namespace and override the default values for its metadata.
Access permission
To specify metadata in a request to store an object, you need write permission. Additionally, to specify the hold parameter, you also need privileged permission.
Request header
PUT /rest/directory/file?retention=retention HTTP/1.1
Parameter | Required | Description |
acl | No |
Stores a predefined ACL for the object. One of:
|
directory | Yes | Folder name. |
file | Yes | Name of the file, including file extension. |
hold | No | Places an object on hold or specifies that it is not on hold. Either true or false . |
index | No | Specifies whether the object should be indexed for search. Either true or false . |
label-hold | No | Specifies whether to place an object on labeled hold and if true, specifies a JSON format array containing pairs of one or more unique labeled hold IDs and an associated hold value.
Example x-hcp-labelretentionhold [{"id":"UniqueLabelHold-1","hold":true}, {"id":"UniqueLabelHold-2","hold":true}] |
retention | No | Specifies the retention setting for the object.
|
shred | No | Specifies whether to shred the object after it is deleted. Either true or false . |
Response headers
The list below describes the request-specific HTTP response headers for this operation.
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-CustomMetadata Hash
The cryptographic hash algorithm HCP uses and the cryptographic hash value of the stored annotation, in this format:
X-HCP-CustomMetadataHash: hash-algorithm hash-value
You can use the returned hash value to verify that the content of the stored annotation is the same as the annotation content you sent. To do this, compare this value with a hash value that you generate from the original annotation content.
This header is returned only if the request contains both data and custom metadata.
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-VersionId
The version ID of the object.
Return codes
The table below describes the HTTP return codes that have specific meaning for this request.
Code | Meaning | Description |
400 | OK |
One of:
|
Example: Setting metadata when storing an object
Here’s a sample HTTP PUT request that stores a file named Q1_2012.ppt in the quarterly_rpts directory, sets the retention value for the object to the Reg-107 class, and sets the shred setting for the object to true
.
Request with curl command line
curl -k -iT Q1_2012.ppt -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d" "https://finance.europe.hcp.example.com/rest/quarterly_rpts/ Q1_2012.ppt?retention=C+Reg-107&shred=true"
Request in Python using PycURL
import pycurl import os filehandle = open("Q1_2012.ppt", 'rb') 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?retention=C+Reg-107") curl.setopt(pycurl.SSL_VERIFYPEER, 0) curl.setopt(pycurl.SSL_VERIFYHOST, 0) curl.setopt(pycurl.UPLOAD, 1) curl.setopt(pycurl.INFILESIZE, os.path.getsize("Q1_2012.ppt")) curl.setopt(pycurl.READFUNCTION, filehandle.read) curl.perform() print curl.getinfo(pycurl.RESPONSE_CODE) curl.close() filehandle.close()
Request headers
PUT /rest/quarterly_rpts/Q1_2012.ppt?retention=C+Reg-107 HTTP/1.1 Host: finance.europe.hcp.example.com Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d Content-Length: 678400
Response headers
HTTP/1.1 201 Created X-HCP-ServicedBySystem: hcp.example.com ETag: "9c604138ffb0f308a8552a3752e5a1be" Location: /rest/quarterly_rpts/Q1_2012.ppt X-HCP-VersionId: 80238663473089 X-HCP-Hash: SHA-256 E830B86212A66A792A79D58BB185EE63A4FADA76BB8A1C... X-HCP-Time: 1334829227 Content-Length: 0