Specifying metadata on object creation

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 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:

all_read
Grants read permission for the object to all users
auth_read
Grants read permission for the object to all authenticated users
Content-Type No

Specifies the media type of the resource. This header sends a string along with the file to specify its format.

Example

"Content-Type:text/plain"
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.
id
Unique identifier string for the labeled hold. The maximum ID size is 64 characters.
hold
Specifies whether the object is on labeled hold using this id. Either true or false.

Example

label_hold=[{"id":"MY-HOLD-ID1","hold":true}, {"id":"MY-HOLD-ID2","hold":true}]
retention No Specifies the retention setting for the object.
0 (zero) or Deletion Allowed
Allows the object to be deleted at any time. You can assign this value to an object only when you add it to the namespace or when its retention setting is -2.
The value -0 is equivalent to 0 (zero).
-1 or Deletion Prohibited
Prevents the object from being deleted and its retention setting from being changed. You can assign this value to an object that is not in a retention class at any time.
If an object is assigned to a retention class and that class is then deleted, the retention setting for that object changes to -1.
-2 or Initial Unspecified
Specifies that the object does not yet have a retention setting. You can assign this value to an object when you add the object to the namespace. You can also directly change the retention setting for an object from 0 to ‑2.
You can change ‑2 to any other retention setting.
datetime
Prevents the object from being deleted until the specified date and time. You can assign this value to an object that is not in a retention class if the specified date and time is later than the current retention setting for the object. You cannot assign it to an object for which the current retention setting is -1.
offset
Specifies a period for which to retain the object. You can assign this value to an object that is not in a retention class at any time, except when its current retention setting is -1.
HCP calculates the retention setting date and time from the offset and one of these:
  • The time the object was added to the namespace
  • The current retention setting
  • The current time
C+retention_class_name
Assigns the object to a retention class.
You can assign this value to an object if any one of these is true:
  • The original retention period for the object has expired.
  • The original retention period for the object has not expired, and the retention class results in a retention period that is longer than the current retention period.
  • The retention setting for the object is 0 or -2.
  • The retention setting for the object is -1, and the class has a retention setting of -1.
  • The object is in a retention class, and the duration of the new class is not shorter than the duration of the original class.
  • The retention class you assign must already be defined for the namespace.
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.

Status codes

The table below describes the HTTP status codes that have specific meaning for this request.

Code Meaning Description
400 OK

One of:

  • The URL in the request is not well-formed.
  • The request contains an unsupported query parameter or an invalid value for a query parameter.
  • The request is trying to store an object with a predefined ACL in a namespace that does not support ACLs.

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
Content-Type:text/plain

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