Storing an annotation
You use the HTTP PUT method to store or replace an annotation for an existing object. Some namespaces are configured to require custom metadata to be well-formed XML. In this case, HCP rejects an annotation that is not well-formed XML and returns an HTTP 400 (Bad Request) error code.
An annotation is stored as a single unit. You can add it or replace it in its entirely, but you cannot add to or change an existing annotation. If you store an annotation with the same name as an existing annotation, the new metadata replaces the existing metadata.
In addition to storing an annotation for an existing object, you can use a single request to store object data and an annotation together.
Access permission
To store an annotation, you need write permission.
Usage consideration
A PUT to store an annotation may fail in either of these cases:
- The XML has a large number of different elements and attributes. In this case, the request returns an HTTP 400 (Bad Request) error code.
To prevent failures, try restructuring the XML to have fewer different elements and attributes. For example, try concatenating multiple element values, such as the different parts of an address, to create a new value for a single element.
If you cannot restructure the XML to prevent failures, ask your tenant administrator about reconfiguring the namespace to prevent HCP from checking custom metadata XML.
- A large number of clients try to store custom metadata for multiple objects at the same time. In this case, the request returns an HTTP 409 (Conflict) error code.
To prevent failures, limit the number of concurrent requests from clients to the namespace.
Request header
PUT /rest/directory/file?type=custom-metadata&annotation=annotation HTTP/1.1
Parameter | Required | Description |
directory | Yes | Folder name. |
file | Yes | Name of the file, including file extension. |
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. |
type | Yes | Use the value custom-metadata . |
Response headers
The list below describes the request-specific response headers for this operation.
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.
Return codes
The table below describes the HTTP return codes that have specific meaning for this request.
Code | Meaning | Description |
201 | Created | HCP successfully stored the annotation. |
400 | Bad Request |
One of:
If more information about the error is available, the HTTP response headers include the HCP-specific |
403 | Forbidden |
One of:
If more information about the error is available, the response headers include the HCP-specific |
404 | Not Found |
One of:
|
413 | File Too Large | The request is trying to store a non-default annotation that is larger than one MB or a default annotation that is larger than one GB. The maximum size of the default annotation is one GB, and the maximum size for all other annotations is one MB |
415 | Unsupported Media Type | The request has a Content-Encoding header with a value other than gzip. |
Example: Storing an annotation for an object
Here’s a sample HTTP PUT request that stores an annotation named report_data containing XML specified in the Q1_2012.custom-metadata.xml file for an existing object named Q1_2012.ppt.
Request with curl command line
curl -k -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d" -iT Q1_2012.custom-metadata.xml "https://finance.europe.hcp.example.com/ rest/quarterly_rpts/Q1_2012.ppt?type=custom-metadata &annotation=report_data"
Request in Python using PycURL
import pycurl import os filehandle = open("Q1_2012.custom-metadata.xml", '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?type=custom-metadata \ &annotation=report_data") 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.custom-metadata.xml")) 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?type=custom-metadata&annotation=report_data HTTP/1.1 Host: finance.europe.hcp.example.com Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d Content-Length: 317
Response headers
HTTP/1.1 201 Created X-HCP-ServicedBySystem: hcp.example.com X-HCP-Hash: SHA-256 20BA1FDC958D8519D11A4CC2D6D65EC64DD12466E456... Location: /rest/quarterly_rpts/Q1_2012.ppt X-HCP-Time: 1334829227 Content-Length: 0