Skip to main content

We've Moved!

Product Documentation has moved to docs.hitachivantara.com
Hitachi Vantara Knowledge

Working with annotations


You can perform these operations on annotations:

Storing an annotation

Checking the existence of an annotation

Listing annotations for an object or version

Retrieving annotations for objects and versions

Deleting annotations

This chapter describes the procedures for the operations listed above.

© 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.

© 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.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

Access permission (PUT annotation)


To store an annotation, you need write permission.

© 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.

© 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.

© 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.

© 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

© 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.

© 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

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

Access permission (HEAD annotation)


To check for the existence of an annotation, you need browse permission.

© 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.

© 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.”

© 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...

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

Listing annotations for an object or version


You use the HTTP GET method to list the annotations for an object or version.

© 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.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

Access permission (GET annotations)


To list annotations, you need read permission.

© 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.

© 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.

© 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.

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

© 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.

© 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.

TipWebHelp.png

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.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

Access permission (GET annotation for objects and versions)


To retrieve an annotation, you need read permission.

© 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.

© 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.

© 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.

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

© 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.

© 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.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

Access permission (DELETE annotation)


To delete an annotation, you need delete permission.

© 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.

© 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.

© 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

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

 

  • Was this article helpful?