Modifying object metadata
You use the HTTP POST method to change the metadata for existing objects in a namespace. The request changes only the metadata that it explicitly specifies. All other metadata remains unchanged.
You can modify metadata only for the current version of an object. You cannot modify metadata for an old version.
If the request to change metadata specifies a symbolic link, HCP changes the metadata on the object that’s the target of the link.
Access permission
To modify object metadata, you need write permission.
To specify a hold parameter, you also need privileged permission for the namespace.
To specify an owner parameter, you need change owner permission for the namespace.
Request header
POST /rest/directory/file HTTP/1.1
These considerations apply to requests to change object metadata:
- You cannot change the hold and retention settings in the same request.
- You cannot change the shred setting from
true
tofalse
.
Parameter | Required | Description |
directory | Yes | Folder name. |
file | Yes | Name of the file, including file extension. |
domain | Specifies the Active Directory domain that contains the user account specified by the owner query parameter. | |
hold | No | Places an object on hold or specifies that it's 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}] |
owner | No |
Specifies the user that owns the object. One of:
|
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
This operation does not return any request-specific response headers.
Return codes
The table below describes the HTTP return codes that have specific meaning for this request.
Code | Meaning | Description |
200 | OK | HCP successfully updated the metadata. |
400 | Bad Request |
One of:
If more information about the error is available, the response headers include the HCP product-specific |
403 | Forbidden |
One of:
|
404 | Not Found | HCP could not find the specified object, or the URL path contains a symbolic link to a directory anywhere other than in the last component. |
Example: Changing multiple metadata values for an existing object
Here is a sample HTTP POST request that makes the following changes to the metadata for the Q1_2020.ppt file:
- Increases retention by one year from the current value
- Turns on shredding on delete
- Turns off indexing
Request with curl command line
curl -k -i -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d" -d "retention=R+1y" -d "shred=true" -d "index=false" "https://finance.europe.hcp.example.com/rest/quarterly_rpts/Q1_2020.ppt"
Request in Python using PycURL
import pycurl curl = pycurl.Curl() theHeader = ["Transfer-Encoding: chunked"] curl.setopt(pycurl.HTTPHEADER, ["Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d", theHeader]) curl.setopt(pycurl.URL, "https://finance.europe.hcp.example.com \ /rest/quarterly_rpts/Q1_2020.ppt") curl.setopt(pycurl.SSL_VERIFYPEER, 0) curl.setopt(pycurl.SSL_VERIFYHOST, 0) curl.setopt(pycurl.POST, 1) theFields = "retention=R+1y&shred=true&index=false" theHeader = ["Transfer-Encoding: chunked"] curl.setopt(pycurl.POSTFIELDS, theFields) curl.perform() print curl.getinfo(pycurl.RESPONSE_CODE) curl.close()
Request headers
POST /rest/quarterly_rpts/Q1_2020.ppt HTTP/1.1 Host: finance.europe.hcp.example.com Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d Content-Length: 37 Content-Type: application/x-www-form-urlencoded
Response headers
HTTP/1.1 200 OK X-HCP-ServicedBySystem: hcp.example.com Content-Length: 0