Working with annotations
You can perform these operations on annotations:
•Checking the existence of an annotation
•Listing annotations for an object or version
•Retrieving annotations for objects and versions
This chapter describes the procedures for the operations listed above.
Trademarks and Legal Disclaimer
© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.
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. For more information about this, see Storing an object or version of an object.
Trademarks and Legal Disclaimer
© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.
Request contents (PUT annotation)
The PUT request to store an annotation includes these elements:
•If you’re accessing the namespace as an authenticated user, an Authorization header.
•A URL specifying the object for which you’re storing the annotation.
•A type=custom-metadata URL query parameter.
•An annotation=annotation-name URL query parameter, where annotation-name is the name of the annotation you’re storing. If you’re storing the default annotation, you can omit this parameter.
•A body consisting of the custom metadata.
You can send an annotation in compressed format and have HCP decompress the data before storing it. To do this, in addition to specifying the request elements listed above:
•Use gzip to compress the content before sending it.
•Include a Content-Encoding request header with a value of gzip.
•Use a chunked transfer encoding.
Trademarks and Legal Disclaimer
© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.
Access permission (PUT annotation)
To store an annotation, you need write permission.
Trademarks and Legal Disclaimer
© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.
Request-specific return codes (PUT annotation)
The table below describes the HTTP return codes that have specific meaning for this request. For descriptions of all possible return codes, see HTTP return codes.
Code | Meaning | Description |
---|---|---|
201 | Created |
HCP successfully stored the annotation. |
400 | Bad Request |
One of: •The URL in the request is not well-formed. •The namespace is configured with custom metadata XML checking enabled, and the request included custom metadata that is not well-formed XML. •The request has a Content-Encoding header that specifies gzip, but the annotation is not in gzip-compressed format. •The request contains an unsupported query parameter or an invalid value for a query parameter. •The specified object has ten annotations, and the request is trying to add an annotation. •The request contains an If-Match, If-None-Match, If-Modified-Since, or If-Unmodified-since header. If more information about the error is available, the HTTP response headers include the HCP-specific X‑HCP-ErrorMessage header. |
403 | Forbidden |
One of: •The Authorization header or hcp-ns-auth cookie specifies invalid credentials. •The namespace requires client authentication, and the request does not have an Authorization header or hcp-ns-auth cookie. •The user doesn’t have write permission. •The object is under retention, and the namespace does not allow adding or replacing annotations for objects under retention. •The namespace does not exist. •The access method (HTTP or HTTPS) is disabled. If more information about the error is available, the response headers include the HCP-specific X‑HCP-ErrorMessage header. |
404 | Not Found |
One of: •HCP could not find an object or version at the specified URL. The specified object or version does not exist, or the request specified the current version of an object that has been deleted. •Any component of the URL except for the last component in the path is a symbolic link to a directory. |
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. |
Trademarks and Legal Disclaimer
© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.
Request-specific response headers (PUT annotation)
The table below describes the request-specific response headers for this operation. For information about all HCP-specific response headers, see HCP-specific HTTP response headers.
Header | Description |
---|---|
X-HCP-Hash |
The cryptographic hash algorithm HCP uses and the cryptographic hash value of the stored annotation, 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 do this, compare this value with a hash value that you generate from the original data. |
Trademarks and Legal Disclaimer
© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.
Usage consideration (PUT annotation)
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.
For information about annotation limits, see Custom metadata.
Trademarks and Legal Disclaimer
© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.
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
Trademarks and Legal Disclaimer
© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.
Checking the existence of an annotation
You use the HTTP HEAD method to check whether an object or specific version of an object has a specific annotation.
Trademarks and Legal Disclaimer
© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.
Request contents (HEAD annotation)
The HEAD request to check for an annotation includes these elements:
•If you’re accessing the namespace as an authenticated user, an Authorization header.
•The URL of the object.
•A type=custom-metadata URL query parameter.
•An annotation=annotation-name query parameter, where annotation-name is the name of the specific annotation for which you are checking the existence. If you’re checking for the default annotation, you can omit this query parameter.
To check whether an annotation exists for a specific object version, in addition to specifying the request elements listed above, specify this URL query parameter:
version=version-id
Trademarks and Legal Disclaimer
© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.
Access permission (HEAD annotation)
To check for the existence of an annotation, you need browse permission.
Trademarks and Legal Disclaimer
© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.
Request-specific return codes (HEAD annotation)
The table below describes the HTTP return codes that have specific meaning for this request. For descriptions of all possible return codes, see HTTP return codes.
Code | Meaning | Description |
---|---|---|
200 | OK |
The specified object has the requested annotation. |
204 | No Content |
The specified object does not have the requested annotation. |
404 | Not Found |
One of: •HCP could not find an object or version at the specified URL. The specified object or version does not exist, or the request specified the current version of an object that has been deleted. •Any component of the URL except for the last component in the path is a symbolic link to a directory. |
Trademarks and Legal Disclaimer
© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.
Request-specific response headers (HEAD annotation)
The table below describes the request-specific response headers for this operation. For information about all HCP-specific response headers, see HCP-specific HTTP response headers.
Header | Description |
---|---|
Content-Type |
Always text/xml. |
Content-Length |
The size of the annotation, in bytes. |
ETag |
The ETag of the object or version enclosed in double quotation marks ("). |
X-HCP- ChangeTimeMilliseconds |
The change time for the annotation, in milliseconds since January 1, 1970, at 00:00:00 UTC, followed by an integer that’s unique for the change time (for example, 1336483100178.00). For information about object change times, see Object ingest time and change time. |
X-HCP-ChangeTimeString |
The change time for the annotation in this format: yyyy-MM-ddThh:mm:ssZ In this format, Z represents the offset from UTC and is specified as: (+|-)hhmm For example, 2012-05-08T09:18:20-0400 represents the start of the 20th second into 9:18 AM, May 8, 2012, EDT. |
X-HCP-Hash |
The cryptographic hash algorithm HCP uses, along with the cryptographic hash value stored for the annotation, in this format: X-HCP-Hash: hash-algorithmhash-value You can use the returned hash value to verify that the stored annotation is the same as the annotation you originally sent. To do this, compare this value with a hash value that you generate from the original data. |
X-HCP-Size |
The size of the annotation, in bytes. |
X-HCP-SymlinkTarget |
The path to the target object as specified when the symbolic link was created. This header is returned only if the URL specifies a symbolic link. If this header is returned, the X-HCP-ACL value is always false. |
X-HCP-Type |
Always annotation. |
If HCP does not find the specified annotation, it returns an X-HCP-ErrorMessage header with the message “No annotation exists with name annotation-name.”
Trademarks and Legal Disclaimer
© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.
Example: Checking the existence of an annotation
Here’s a sample HTTP HEAD request that checks the existence of the report_data annotation for an object named Q1_2012.ppt in the quarterly_rpts directory.
Request with curl command line
curl -k -iI -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
"https://finance.europe.hcp.example.c...ts/Q1_2012.ppt
?type=custom-metadata&annotation=report_data"
Request in Python using PycURL
import pycurl
import StringIO
cin = StringIO.StringIO()
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.HEADER, 1)
curl.setopt(pycurl.NOBODY, 1)
curl.setopt(pycurl.WRITEFUNCTION, cin.write)
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
print cin.getvalue()
curl.close()
Request headers
HEAD /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
Response headers
HTTP/1.1 200 OK
X-HCP-ServicedBySystem: hcp.example.com
X-HCP-Time: 1352396298
X-HCP-SoftwareVersion: 7.0.0.16
X-RequestId: 47306C879E376245
ETag: "8d604138ffb0f308a8552a3752e5a1be"
Content-Type: text/xml
Content-Length: 35643
X-HCP-Type: annotation
X-HCP-Size: 35643
X-HCP-ChangeTimeMilliseconds: 1352322160000.00
X-HCP-ChangeTimeString: 2012-11-07T16:02:40-0500
X-HCP-Hash: SHA-256 F8C7D88D139D14D115BA5300CD352338B8A1D344046DB2...
Trademarks and Legal Disclaimer
© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.
Listing annotations for an object or version
Trademarks and Legal Disclaimer
© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.
Request contents (GET annotations)
The GET request to list the annotations for an object includes these elements:
•If you’re accessing the namespace as an authenticated user, an Authorization header
•The URL of the object
•A type=custom-metadata-info query parameter
If an object has multiple versions, specify this optional URL query parameter to retrieve the annotation information for a specific version of the object:
version=version-id
If you omit the version parameter, HCP retrieves annotation information for the current version of the object.
Trademarks and Legal Disclaimer
© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.
Access permission (GET annotations)
To list annotations, you need read permission.
Trademarks and Legal Disclaimer
© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.
Request-specific return codes (GET annotations)
The table below describes the HTTP return codes that have specific meaning for this request. For descriptions of all possible return codes, see HTTP return codes.
Code | Meaning | Description |
---|---|---|
200 | OK |
HCP successfully listed the annotations for the object. |
204 | No Content |
The specified object or version does not have any annotations. |
404 | Not Found |
One of: •HCP could not find an object or version at the specified URL. The specified object or version does not exist, or the request specified the current version of an object that has been deleted. •Any component of the URL except for the last component in the path is a symbolic link to a directory. |
Trademarks and Legal Disclaimer
© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.
Request-specific response header (GET annotations)
The table below describes the request-specific response header for this operation. For information about all HCP-specific response headers, see HCP-specific HTTP response headers.
Header | Description |
---|---|
X-HCP-SymlinkTarget |
The path to the target object as specified when the symbolic link was created. This header is returned only if the URL specifies a symbolic link. If this header is returned, the X-HCP-ACL value is always false. |
Trademarks and Legal Disclaimer
© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.
Response body (GET annotations)
The body of the HTTP response to a GET request to list the annotations for an object or version contains an XML document listing the annotation information, in this format:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<annotations>
<annotation>
<name>annotation-name</name>
<hash>hash-algorithm hash-value</hash>
<changeTimeMilliseconds>change-milliseconds-after-1/1/1970.unique-
integer</changeTimeMilliseconds>
<changeTimeString>yyyy-MM-ddThh:mm:ssZ</changeTimeString>
<size>annotation-size-in-bytes</size>
<contentType>text/xml|unknown</contentType>
</annotation>
.
.
.
</annotations>
The contentType element value is text/xml if the namespace is configured to check whether custom metadata is well-formed XML. Otherwise the value is unknown.
Trademarks and Legal Disclaimer
© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.
Example: Listing annotations for an object
Here’s a sample HTTP GET request that lists the annotations for an object named Q1_2012.ppt in the quarterly_rpts directory.
Request with curl command line
curl -k -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
"https://finance.europe.hcp.example.c...ts/Q1_2012.ppt
?type=custom-metadata-info
Request in Python using PycURL
import pycurl
filehandle = open("Q1_2012.ppt.custom-metadata.xml", 'wb')
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-info")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.WRITEFUNCTION, filehandle.write)
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()
filehandle.close()
Request headers
GET /rest/quarterly_rpts/Q1_2012.ppt?type=custom-metadata-info HTTP/1.1
Host: finance.europe.hcp.example.com
Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d
Response headers
HTTP/1.1 200 OK
X-HCP-ServicedBySystem: hcp.example.com
X-HCP-Time: 1352389820
X-HCP-SoftwareVersion: 7.0.0.16
Content-Type: text/xml
Content-Length: 822
Response body
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<annotations>
<annotation>
<name>report_data</name>
<hash>SHA-256 F8C7D88D139D14D115BA5300CD352338B8A1D344...</hash>
<changeTimeMilliseconds>1352322387000.00</changeTimeMilliseconds>
<changeTimeString>2012-11-07T16:06:27-0500</changeTimeString>
<size>35643</size>
<contentType>text/xml</contentType>
</annotation>
<annotation>
<name>default</name>
<hash>SHA-256 F8C7D88D139D14D115BA5300CD352338B8A1D344...</hash>
<changeTimeMilliseconds>1352386457000.00</changeTimeMilliseconds>
<changeTimeString>2012-11-08T09:54:17-0500</changeTimeString>
<size>908</size>
<contentType>tex/xml</contentType>
</annotation>
</annotations>
Trademarks and Legal Disclaimer
© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.
Retrieving annotations for objects and versions
You use the HTTP GET method to retrieve an annotation for an object or version of an object. The annotation is returned in the format it had before it was stored.
You can also use a single request to retrieve object or version data and custom metadata together. For more information about this, see Retrieving an object or multiple versions of an object.
Trademarks and Legal Disclaimer
© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.
Request contents (GET annotation for objects and versions)
The GET request to retrieve an annotation for an object or version includes these elements:
•If you’re accessing the namespace as an authenticated user, an Authorization header.
•The URL of the object.
•A type=custom-metadata query parameter.
•An annotation=annotation-name query parameter, where annotation-name is the name of the specific annotation you are retrieving. If you’re retrieving the default annotation, you can omit this query parameter.
Choosing not to wait for delayed retrievals
HCP may detect that a GET request will take a significant amount of time to return the annotation. You can choose to have the request fail in this situation instead of waiting for HCP to return the annotation. To do this, in addition to specifying the request elements listed above, use the nowait URL query parameter.
When a GET request fails because the request would take a significant amount of time to return the annotation 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 error code, retry the request a few times, waiting about thirty seconds in between retries. |
Retrieving an annotation for a specific version
If an object has multiple versions, specify this optional URL query parameter to retrieve an annotation for a specific version of the object:
version=version-id
If you omit the version parameter, HCP retrieves the annotation for the current version of the object.
Retrieving an annotation in compressed format
To request that HCP return the annotation 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.
Trademarks and Legal Disclaimer
© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.
Access permission (GET annotation for objects and versions)
To retrieve an annotation, you need read permission.
Trademarks and Legal Disclaimer
© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.
Request-specific return codes (GET annotation for objects and versions)
The table below describes the HTTP return codes that have specific meaning for this request. For descriptions of all possible return codes, see HTTP return codes.
Code | Meaning | Description |
---|---|---|
200 | OK |
HCP successfully retrieved the annotation. |
204 | No Content |
The specified object does not the specified annotation. |
404 | Not Found |
One of: •HCP could not find an object or version at the specified URL. The specified object or version does not exist, or the request specified the current version of an object that has been deleted. •The URL path contains a symbolic link to a directory anywhere other than in the last component. |
406 | Not Acceptable |
The request has an Accept-Encoding header that does not include gzip or *. |
503 | Service Unavailable |
The request contains the nowait query parameter, and HCP determined that the request would have taken a significant amount of time to return the annotation. |
Trademarks and Legal Disclaimer
© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.
Request-specific response headers (GET annotation for objects and versions)
The table below describes the request-specific response headers for this operation. For information about all HCP-specific response headers, see HCP-specific HTTP response headers.
Header | Description |
---|---|
Content-Encoding |
Always gzip. This header is returned only if the response data is compressed. |
Content-Length |
The size of the returned data, in bytes. |
Content-Type |
Always text/xml. |
ETag |
The ETag of the object or version, enclosed in double quotation marks ("). |
X-HCP- ChangeTimeMilliseconds |
The change time for the annotation, in milliseconds since January 1, 1970, at 00:00:00 UTC, followed by an integer that’s unique for the change time (for example, 1336483100178.00). For information about object change times, see Object ingest time and change time. |
X-HCP-ChangeTimeString |
The change time for the annotation in this format: yyyy-MM-ddThh:mm:ssZ In this format, Z represents the offset from UTC and is specified as: (+|-)hhmm For example, 2012-05-08T09:18:20-0400 represents the start of the 20th second into 9:18 AM, May 8, 2012, EDT. |
X-HCP-ContentLength |
The size of the annotation, in bytes. This header is returned only if the request specifies a compressed response. |
X-HCP-Hash |
The cryptographic hash algorithm HCP uses, along with the cryptographic hash value stored for the annotation, in this format: X-HCP-Hash: hash-algorithmhash-value You can use the returned hash value to verify that the stored annotation is the same as the annotation you originally sent. To do this, compare this value with a hash value that you generate from the original data. |
X-HCP-Size |
The size of the annotation, in bytes. |
X-HCP-SymlinkTarget |
The path to the target object as specified when the symbolic link was created. This header is returned only if the URL specifies a symbolic link. If this header is returned, the X-HCP-ACL value is always false. |
X-HCP-Type |
Always annotation. |
Trademarks and Legal Disclaimer
© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.
Response body (GET annotation for objects and versions)
The body of the HTTP response contains the annotation.
Trademarks and Legal Disclaimer
© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.
Example: Retrieving an annotation for an object
Here’s a sample HTTP GET request that retrieves the account_info annotation for an object named Q1_2012.ppt in the quarterly_rpts directory.
Request with curl command line
curl -k -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
"https://finance.europe.hcp.example.c...ts/Q1_2012.ppt
?type=custom-metadata&annotation=account_info" >
Q1_2012.ppt.custom-metadata.xml
Request in Python using PycURL
import pycurl
filehandle = open("Q1_2012.ppt.custom-metadata.xml", 'wb')
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=account_info")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.WRITEFUNCTION, filehandle.write)
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()
filehandle.close()
Request headers
GET /rest/quarterly_rpts/Q1_2012.ppt?type=custom-metadata&annotation=
account_info HTTP/1.1
Host: finance.europe.hcp.example.com
Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d
Response headers
HTTP/1.1 200 OK
X-HCP-ServicedBySystem: hcp.example.com
X-HCP-Time: 1336490468
X-HCP-SoftwareVersion: 7.0.0.16
ETag: "9c604138ffb0f308a8552a3752e5a1be"
Content-Type: text/xml
Content-Length: 287
X-HCP-Type: annotation
X-HCP-Size: 119459
X-HCP-ChangeTimeMilliseconds: 1335347627362.00
X-HCP-ChangeTimeString: 2012-04-25T05:53:47-0400
X-HCP-Hash: SHA-256 42C605FBFFCD7CEAC36BE62F294374F94503D1DC1793736...
Response body
<?xml version="1.0" ?>
<quarterly_rpt>
<preparation>
<prepared_by>Lee Green</prepared_by>
<department>Accounting</department>
<title>Budget Director</title>
</preparation>
<presentation_date>04-18-2012</presentation_date>
<slide_count>23</slide_count>
</quarterly_rpt>
Trademarks and Legal Disclaimer
© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.
Deleting annotations
You use the HTTP DELETE request to delete an annotation for an object. You cannot delete annotations for old versions of an object.
Trademarks and Legal Disclaimer
© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.
Request contents (DELETE annotation)
The DELETE request to delete an annotation includes these elements:
•If you’re accessing the namespace as an authenticated user, an Authorization header.
•The URL of the object.
•A type=custom-metadata URL query parameter.
•An annotation=annotation-name query parameter, where annotation-name is the name of the specific annotation you are deleting. If you’re deleting the default annotation, you can omit this query parameter.
Trademarks and Legal Disclaimer
© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.
Access permission (DELETE annotation)
To delete an annotation, you need delete permission.
Trademarks and Legal Disclaimer
© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.
Request-specific return codes (DELETE annotation)
The table below describes the HTTP return codes that have specific meaning for this request. For descriptions of all possible return codes, see HTTP return codes.
Code | Meaning | Description |
---|---|---|
200 | OK |
HCP successfully deleted the annotation. |
204 | No Content |
The specified object does not have the specified annotation. |
400 | Bad Request |
The request specified a conditional header, such as If-Match. If more information about the error is available, the HTTP response headers include the HCP-specific X‑HCP-ErrorMessage header. |
403 | Forbidden |
One of: •The Authorization header or hcp-ns-auth cookie specifies invalid credentials. •The namespace requires client authentication, and the request does not have an Authorization header or hcp-ns-auth cookie. •The user doesn’t have delete permission. •The object is under retention, and the namespace does not allow deleting custom metadata for objects under retention. •The access method (HTTP or HTTPS) is disabled. If more information about the error is available, the response headers include the HCP-specific X‑HCP-ErrorMessage header. |
404 | Not Found |
One of: •HCP could not find an object or version at the specified URL. The specified object or version does not exist, or the request specified the current version of an object that has been deleted. •The URL path contains a symbolic link to a directory anywhere other than in the last component. |
409 | Conflict |
HCP could not delete the annotation because it is currently being written to the namespace. |
Trademarks and Legal Disclaimer
© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.
Request-specific response headers (DELETE annotation)
This operation does not return any request-specific response headers. For information about all HCP-specific response headers, see HCP-specific HTTP response headers.
Trademarks and Legal Disclaimer
© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.
Example: Deleting an annotation for an object
Here’s a sample HTTP DELETE request that deletes the report_data annotation for an object named Q1_2012.ppt located in the quarterly_rpts directory.
Request with curl command line
curl -k -iX DELETE
-H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
"https://finance.europe.hcp.example.c...ts/Q1_2012.ppt
?type=custom-metadata&annotation=report_data"
Request in Python using PycURL
import pycurl
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.CUSTOMREQUEST, "DELETE")
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()
Request headers
DELETE /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
Response headers
HTTP/1.1 200 OK
X-HCP-ServicedBySystem: hcp.example.com
X-RequestId: E62EFD408DBB7B8F
X-HCP-Time: 1334829227
Content-Length: 0
Trademarks and Legal Disclaimer
© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.