Working with directories
HCP lets you perform these operations on directories:
•Checking the existence of a directory
This chapter describes these procedures.
Trademarks and Legal Disclaimer
© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.
Creating an empty directory
You use the HTTP PUT method to create empty directories in a namespace. If any other directories in the path you specify for a new directory do not already exist, HCP creates them as well.
Trademarks and Legal Disclaimer
© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.
Request contents (PUT directory)
The PUT request to create an empty directory has these elements:
•If you’re accessing the namespace as an authenticated user, an Authorization header
•A URL specifying the location in which to create the directory
Trademarks and Legal Disclaimer
© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.
Access permission (PUT directory)
To create a directory, you need write permission for the namespace.
Trademarks and Legal Disclaimer
© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.
Request-specific return codes (PUT directory)
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 created the directory. |
409 | Conflict |
HCP could not create the directory in the namespace because a directory, object, or symbolic link with the specified name already exists. |
Trademarks and Legal Disclaimer
© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.
Request-specific response headers (PUT directory)
This creation operation does not return any request-specific response headers. For information on all HCP-specific response headers, see HCP-specific HTTP response headers.
Trademarks and Legal Disclaimer
© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.
Example: Creating an empty directory
Here’s a sample HTTP PUT request that creates a new directory named graphics in the quarterly_rpts directory.
Request with curl command line
curl -k -iX PUT
-H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
"https://finance.europe.hcp.example.c..._rpts/graphics
?type=directory"
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/graphics?type=directory")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.CUSTOMREQUEST, "PUT")
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()
Request headers
PUT /rest/quarterly_rpts/graphics?type=directory HTTP/1.1
Host: finance.europe.hcp.example.com
Authorizaton: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d
Response headers
HTTP/1.1 201 Created
X-HCP-ServicedBySystem: hcp.example.com
Location: /rest/quarterly_rpts/graphics
Content-Length: 0
Trademarks and Legal Disclaimer
© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.
Checking the existence of a directory
Trademarks and Legal Disclaimer
© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.
Request contents (HEAD directory)
The HEAD request to check the existence of a directory has these elements:
•If you’re accessing the namespace as an authenticated user, an Authorization header
•The URL of the directory
By default, you can't check the existence of a directory if it has been deleted. If the namespace supports versioning, you can check for deleted objects and directories. To do this, specify this URL query parameter:
deleted=true
You can also specify deleted=false, which results in the default behavior.
Trademarks and Legal Disclaimer
© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.
Access permission (HEAD directory)
To check for directory existence, you need browse permission.
Trademarks and Legal Disclaimer
© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.
Request-specific return codes (HEAD directory)
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 found a directory or object at the specified URL. |
404 | Not Found |
One of: •HCP could not find a directory, object, or version at the specified URL. The specified directory does not exist, or the request specified a directory 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 directory)
The table below describes the request-specific response headers for this operation. For information on all HCP-specific response headers, see HCP-specific HTTP response headers.
Header | Description |
---|---|
X-HCP-Type |
The type of the entity. This value is always directory for directories. |
X-HCP-ChangeTimeMilliseconds |
The change time for the directory, 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). The change time for a directory is the most recent of: •The time the directory was created •The time the directory was deleted •The time an object was added to the directory •The time an object was deleted from the directory |
X-HCP-ChangeTimeString |
The change time for the directory 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-SymlinkTarget |
The path to the target directory as specified when the directory was created. This header is returned only if the request URL specifies a symbolic link to a directory. |
Trademarks and Legal Disclaimer
© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.
Example: Checking the existence of a directory
Here’s a sample HTTP HEAD request that checks the existence of a directory named quarterly_rpts.
Request with curl command line
curl -k -iI -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
"https://finance.europe.hcp.example.c...quarterly_rpts"
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")
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 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: 1334829227
X-HCP-SoftwareVersion: 7.0.0.16
Content-Type: text/xm
X-HCP-ChangeTimeMilliseconds: 1326336965436
X-HCP-ChangeTimeString: 2012-01-11T09:56:05-0500
X-HCP-Type: directory
Content-Length: 0
Trademarks and Legal Disclaimer
© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.
Listing directory contents
You use the HTTP GET method to list the contents of a directory in a namespace. This method does not list old versions of objects.
Trademarks and Legal Disclaimer
© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.
Request contents (GET directory)
The GET request to list a directory contents has these elements:
•If you’re accessing the namespace as an authenticated user, an Authorization header
•The URL of the directory
Listing deleted objects and directories
By default, a directory list does not include deleted objects or directories. If the namespace supports versioning, you can include deleted objects and directories in the list. To do this, specify this URL query parameter:
deleted=true
You can also specify deleted=false, which results in the default behavior.
Also specify the deleted=true parameter to list the contents of a deleted directory (which can contain only deleted objects and directories).
Managing subdirectory change times
By default, the change time returned for each subdirectory in a directory list is the time the subdirectory was created or, if the subdirectory is a deleted directory, the time it was deleted. You can choose instead to return change times that are the most recent of:
•The time the subdirectory was created
•The time the subdirectory was deleted
•The time an object was most recently added to the subdirectory
•The time an object was most recently deleted from the subdirectory
To do this, specify this URL query parameter:
mostRecentDirTimes=true
You can also specify mostRecentDirTimes=false, which results in the default behavior.
Trademarks and Legal Disclaimer
© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.
Access permission (GET directory)
To list the contents of a directory, you need browse permission.
Trademarks and Legal Disclaimer
© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.
Request-specific return codes (GET directory)
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 directory listing. This code is also returned if the URL specified an object and HCP successfully retrieved the object. |
404 | Not Found |
One of: •HCP could not find a directory, object, or version at the specified URL. The specified directory does not exist, or the request specified a directory 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 directory)
The table below describes the request-specific response header for this operation. For information on all HCP-specific response headers, see HCP-specific HTTP response headers.
Header | Description |
---|---|
X-HCP-Type |
The type of the entity. This value is always directory for directories. |
X-HCP-ChangeTimeMilliseconds |
The change time for the directory, 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). The change time for a directory is the most recent of: •The time the directory was created •The time the directory was deleted •The time an object was most recently added to the directory •The time an object was most recently deleted from the directory |
X-HCP-ChangeTimeString |
The change time for the directory 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-SymlinkTarget |
The path from the symbolic link to the target directory as specified when the symbolic link was created. This header is returned only if the request URL specifies a symbolic link to a directory. |
Trademarks and Legal Disclaimer
© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.
Response body (GET directory)
The body of the HTTP response consists of XML that lists the contents of the requested directory, including metadata for the objects the directory contains. It lists only the immediate directory contents, not the contents of any subdirectories.
The XML for the list has this format:
<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="/static/xsl/directory.xsl"?>
<directory xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="/static/xsd/directory.xsd"
path="directory-path"
utf8Path="utf8-directory-path"
parentDir="directory-path"
utf8ParentDir="utf8-directory-path"
dirDeleted="true|false"
showDeleted="true|false"
namespaceName="namespace-name"
utf8NamespaceName="utf8-namespace-name">
changeTimeMilliseconds="change-milliseconds-after-1/1/1970.unique-integer
changeTimeString="yyyy-MM-ddThh:mm:ssZ"
<!-- Format for a subdirectory -->
<entry urlName="directory-name"
utf8Name="utf8-directory-name"
type="directory"
changeTimeMilliseconds="change-milliseconds-after-1/1/1970.unique-integer
changeTimeString="yyyy-MM-ddThh:mm:ssZ"
state="created|deleted"
/>
<!-- Format for a symbolic link -->
<entry urlName="symbolic-link-name"
utf8Name="utf8-symbolic-link-name"
type="symlink"
symlinkTarget="path-to-target"
utf8SymlinkTarget="utf8-path-to-target"
state="created|deleted"
/>
<!-- Format for an object -->
<entry urlName="object-name"
utf8Name="utf8-object-name"
type="object"
size="object-size-in-bytes"
etag="etag"
hashScheme="hash-algorithm"
hash="hash-value"
retention="(retention-seconds-after-1/1/1970|0|-1|-2)"
retentionString="(retention-datetime-value|Deletion Allowed|
Deletion Prohibited|Initial Unspecified)"
retentionClass="[retention-class-name]"
ingestTime="ingest-seconds-after-1/1/1970"
ingestTimeString="MM/dd/yyyyhh:mm(AM|PM)"
hold="true|false"
shred="true|false"
dpl="data-protection-level"
index="true|false"
customMetadata="true|false"
customMetadataAnnotations="semicolon-delimited list of annotations"
version="version-number"
replicated="true|false"
changeTimeMilliseconds="change-milliseconds-after-1/1/1970.unique-integer"
changeTimeString="yyyy-MM-ddThh:mm:ssZ"
owner="[username|nobody]"
domain="[active-directory-domain]"
hasAcl="true|false"
state="created|deleted"
/>
</directory>
In this format:
•The hashScheme and hash attributes are not returned for multipart objects.
•The ingestTimeString and retentionString values are in the time zone of the HCP system. For example, if the repository is in Boston, Massachusetts and the ingestTime is 1330626356 (which corresponds to 3/1/2012 18:25:56 UTC), the ingestTimeString value is 3/1/2012 2:25PM.
•The changeTimeString value is in ISO 8601 format, which is the time in the time zone of the HCP system followed by the hour and minute offset between local time and UTC.
Trademarks and Legal Disclaimer
© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.
Example: Listing the contents of a directory that includes deleted objects
Here’s a sample HTTP GET request that lists all the contents, including any deleted objects or subdirectories, of a directory named quarterly_rpts in a namespace that supports versioning.
Request with curl command line
curl -k -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
"https://finance.europe.hcp.example.c...s?deleted=true"
> quarterly_rpts.xml
Request in Python using PycURL
import pycurl
filehandle = open("quarterly_rpts.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?deleted=true")
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?deleted=true 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: 1335036864
X-HCP-SoftwareVersion: 7.0.0.16
Content-Type: text/xml
X-HCP-Type: directory
X-HCP-ChangeTimeMilliseconds: 1353420657688.00
X-HCP-ChangeTimeString: 2012-11-20T09:10:57-0500
Content-Length: 577
Response body
<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="/static/xsl/ns-directory.xsl"?>
<directory xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="/static/xsd/ns-directory.xsd"
path="/rest/quarterly_rpts"
utf8Path="/rest/quarterly_rpts"
parentDir="/rest">
utf8ParentDir="/rest"
dirDeleted="false"
showDeleted="true"
namespaceName="finance"
utf8NamespaceName="finance">
changeTimeMilliseconds="1326336965436"
changeTimeString="2012-01-11T09:56:05-0500"
<entry urlName="Q4_2011.ppt"
utf8Name="Q4_2011.ppt"
type="object"
size="671744"
hashScheme="SHA-256"
hash="42C605FBFFCD7CEAC36BE62F294374F94503D1DC1793736EF367..."
retention="0"
retentionString="Deletion Allowed"
retentionClass=""
ingestTime="1326898187"
ingestTimeString="1/18/2012 2:49PM"
hold="false"
shred="false"
dpl="2"
index="true"
customMetadata="false"
customMetadataAnnotations=""
version="80238375537921"
replicated="false"
changeTimeMilliseconds="1326898187533.00"
changeTimeString="2012-01-18T14:49:47-0400"
owner="lgreen"
domain=""
hasAcl="false"
state="created"
/>
<entry urlName="obsolete"
utf8Name="obsolete"
type="directory"
changeTimeMilliseconds="1331847677748.00"
changeTimeString="2012-03-15T17:41:17-0400"
state="deleted"
/>
<entry urlName="Q1_2012.ppt"
utf8Name="Q1_2012.ppt"
type="object"
size="678400"
hashScheme="SHA-256"
hash="E830B86212A66A792A79D58BB185EE63A4FADA76BB8A1C257C01..."
retention="0"
retentionString="Deletion Allowed"
retentionClass=""
ingestTime="1334847117"
ingestTimeString="4/19/2012 9:51AM"
hold="false"
shred="false"
dpl="2"
index="true"
customMetadata="false"
customMetadataAnnotations=""
version="80238376132993"
replicated="false"
changeTimeMilliseconds="1334847117598.00"
changeTimeString="2012-04-19T09:51:57-0400"
owner="lgreen"
domain=""
hasAcl="false"
state="created"
/>
</directory>
Notice that the obsolete directory was deleted. It does not appear in a directory listing if the URL does not include the deleted=true parameter.
Trademarks and Legal Disclaimer
© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.
Deleting an empty directory
You use the HTTP DELETE method to delete an empty directory from a namespace. You cannot delete a directory that contains any objects, subdirectories, or symbolic links.
Trademarks and Legal Disclaimer
© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.
Request contents (DELETE directory)
The DELETE request to delete an empty directory has these elements:
•If you’re accessing the namespace as an authenticated user, an Authorization header
•The URL of the directory
Trademarks and Legal Disclaimer
© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.
Access permission (DELETE directory)
To delete a directory you need delete permission for the namespace.
Trademarks and Legal Disclaimer
© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.
Request-specific return codes (DELETE directory)
The table below describes the HTTP return codes that have specific meanings for this request. For descriptions of all possible return codes, see HTTP return codes.
Code | Meaning | Description |
---|---|---|
200 | OK |
HCP successfully deleted the directory. |
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 specified directory is not empty. •The user doesn’t have delete permission. •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 a directory, object, or version at the specified URL. The specified directory does not exist, or the request specified a directory that has been deleted. •Any component of the URL except for the last component in the path is a symbolic link to a directory. |
409 | Conflict |
HCP could not delete the specified directory because the directory is currently being written to the namespace. |
Trademarks and Legal Disclaimer
© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.
Request-specific response headers (DELETE directory)
This operation does not return any request-specific response headers. For information on 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 empty directory
Here’s a sample HTTP DELETE request that deletes the directory named obsolete from the quarterly_rpts directory in the namespace.
Request with curl command line
curl -k -iX DELETE
-H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
"https://finance.europe.hcp.example.c..._rpts/obsolete”
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/obsolete")
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/obsolete 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: 1334829227
Content-Length: 00
Trademarks and Legal Disclaimer
© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.