Skip to main content
Hitachi Vantara Knowledge

Container and object properties

Containers and objects have various properties that affect what you can do with them and what happens when you take action on them. Some of these properties are visible through the HSwift API. Others, such as versioning, aren’t visible through HSwift but still affect that API.

This chapter describes container and object properties that have an impact on the HSwift API.

Containers and objects have additional properties that have no impact on the HSwift API and are, therefore, not described in this book.

Container names

When you create a container, you give it a name. The name you specify for a container must be from one through 63 characters long and can contain only alphanumeric characters and hyphens (-) but cannot start or end with a hyphen.

Container names cannot contain white space or special characters other than hyphens.

Container names are not case sensitive. However, if you will be accessing a container through an interface that does not automatically convert URLs to all lowercase, you should use lowercase for all letters in the container name.

Container names cannot start with xn-- (that is, the characters x and n followed by two hyphens).

The name you give a container must be unique for the tenant (account) for which you create the container. Different tenants can have containers with the same name.

You can reuse container names that are not currently in use. So, for example, if you delete a container, you can give a new container the same name as the deleted container had.

Tenant administrators can change the name of a container any time after you create the container. When the name of a container changes, the URL for the container changes as well.

Object names

When you create an object, you give it a name. Object names:

  • Can contain any characters except the NULL character (ASCII 0 (zero)). This includes nonprinting characters such as spaces and line breaks although they are not recommended for use.
  • Are case sensitive.
  • Cannot consist of a single period (.) or a single forward slash (/).

.directory-metadata is a reserved name. You cannot create an object with this name.

You cannot directly change the name of an object. However, you can effectively rename an object by making a copy of it with a different name and then deleting the original.

Forward slashes in object names

When using the HSwift API, you can view objects as being in a flat space or in a structured space:

  • In a flat space, objects are not grouped by any sort of structural elements, such as directories, and forward slashes (/) in object names are simply part of those names.
  • In a structured space, forward slashes in object names serve as directory separators, and objects can be grouped into directories.

To support the structured view, when you use HSwift to store an object that has forward slashes in its name, HCP also creates directories and subdirectories that conform to the pattern of those forward slashes. For example, if you store an object named quarterly_rpts/Q4_2012, HCP not only stores that object but also creates a directory named quarterly_rpts.

HCP does not create duplicate directories. If, after storing the object named quarterly_rpts/Q4_2012, you store an object named quarterly_rpts/Q3_2012, the single quarterly_rpts directory appears to contain two objects: Q4_2012 and Q3_2012.

Names cannot be shared between directories and objects in the same container. If a container has a directory called quarterly_rpts, it cannot have an object with the name quarterly_rpts. If a container has an object by that name already, you cannot create a directory with that name.

Directories provide a method for organizing the objects you store in a container. By using meaningful names for the portions of object names from which HCP creates directories, you can more easily manage the contents of the container.

You can also use HSwift to create directories and subdirectories by themselves. For example, you could create a directory named mktg with a subdirectory named budget_proposals. If you then store an object named mktg/budget_proposals/BudgProp-2013, that object appears to be in the mktg/budget_proposals directory. Directory names follow the same rules as object names.

When you use HCP interfaces other than HSwift to view or manage objects stored through HSwift, HCP always treats forward slashes in object names as directory separators. So, for example, in the Namespace Browser, the object you stored as quarterly_rpts/Q4_2012 shows up as an object named Q4_2012 in the quarterly_rpts directory.

Grouping objects into directories not only lets you easily manage those objects; it can also enhance HCP performance.

Object naming considerations

The following considerations apply to object names.

Names ending with a forward slash

A forward slash at the end of a name indicates that the item is a directory. So, for example, if you include a forward slash at the end of the object name in a request to store an object, HCP creates an empty directory with that name and does not store the object.

Object names with non-ASCII, nonprintable characters

When you store an object with non-ASCII, nonprintable characters in its name, those characters are percent-encoded in the name displayed back to you.

Regardless of how the name is displayed, the object is stored with its original name, and you can access it either by its original name or by the names with the percent-encoded characters.

Object names and access through the CIFS and NFS protocols

The CIFS and NFS protocols cannot handle object or directory names that are longer than 255 bytes. An object stored through HSwift is inaccessible through CIFS and NFS if:

  • The object name is longer than 255 bytes and does not include any forward slashes.
  • The object name includes one or more forward slashes and any part of the name is longer than 255 bytes. In this case, a part of an object name is any character string that either precedes the first forward slash, comes between two forward slashes, or follows the last forward slash.
Percent-encoding special characters

With the HSwift API, object names are specified in URLs. Some characters have special meaning in URLs and may be interpreted incorrectly when used for other purposes. To avoid ambiguity, percent-encode the special characters listed in the table below.

CharacterPercent-encoded values
Space%20
Tab%09
New line%0A
Carriage return%0D
+%2B
%%25
#%23
?%3F
&%26
\&5C
UTF-8 encoding

These considerations apply to using UTF-8 encoding for object names:

  • Some character-set encoding schemes, such as UTF-8, can require more than one byte to encode a single character. As a result, such encoding can invisibly increase the length of an object name, causing it to exceed the HCP limit of 4,095 bytes.
  • When searching containers, Data Discovery Suite and HCP rely on UTF-8 encoding conventions to find objects by name. If the name of an object is not UTF-8 encoded, searches for the object by name may return unexpected results.
  • When the metadata query engine or HCP search facility indexes an object with a name that includes certain characters that cannot be UTF‑8 encoded, it percent-encodes those characters. Searches for such objects by name must explicitly include the percent-encoded characters in the name.

Retention

Every object has a retention setting. This setting determines how long the object must remain in the container before it can be deleted. This can range from allowing the object to be deleted at any time to preventing the object from ever being deleted. While an object cannot be deleted due to retention, it is said to be under retention.

You cannot use the HSwiftAPI to change the retention setting for an object.

Default retention setting

Each container in HCP has a default retention setting. This is the setting that’s applied to objects when they’re first stored in the container. When you create a container, its default retention setting is to allow deletion at any time.

You cannot use the HSwift API to change the default retention setting for a container. However, tenant administrators can change this setting for the containers you create.

Custom metadata

Objects can optionally have custom metadata in the form of one or more annotations. Annotations are a powerful means for understanding and analyzing the contents of containers. Using the HCP metadata query API or Search Console, you can search for objects based on the content of their annotations.

Storing custom metadata with HSwift

With the HSwift API, you use X-Object-Meta- request headers to specify custom metadata. You can use these headers when you store or copy an object. With the X-Object-Meta- request headers, you specify custom metadata as property/value pairs. You append the property name to the header and specify the value of the property as the value of the header. For example, to give an object a department property with a value of Sales&Mktg and a year property with a value of 2015, you would specify these headers:

X-Object-Meta-department: Sales&Mktg
X-Object-Meta-year: 2015

HCP stores the custom metadata you specify with HSwift as an annotation named .metapairs. In this annotation, the property/value pairs are stored as well-formed XML in which each property is represented by an element. For example, the XML stored for the headers shown above is:

<metapairs version="600">
     <meta-department><![CDATA[Sales&Mktg]]></meta-department>
     <meta-year><![CDATA[2015]]></meta-year>
</metapairs>

The root element in the .metapairs annotation is metapairs.

For each property/value pair, the name of the corresponding element in the .metapairs XML annotation is the concatenation of 'meta-' and the metadata key, modified, if necessary, to be a valid XML element name. Valid XML element names can contain alphanumeric characters, periods (.), hyphens (-), underscores (_), and colons (:). When creating element names for property names, HCP changes any other character to an underscore. For example, the property name city/town becomes the element name city_town.

For each custom metadata property/value pair, the value is enclosed in a CDATA section. This makes the property become the value of the corresponding element.

If you specify an X-Object-Meta- header with no value, HCP doesn't store an element for the property named in the header. If all the X-Object-Meta- headers you specify have no value, HCP doesn't create a .metapairs annotation for the object.

In a request to store or copy an object, you can specify the same X-Object-Meta- property multiple times with different values. In the same .metapairs annotation XML, these values are stored as comma-separated values for a single element.

Here's an example that shows three occurrences of the same property along with the resulting XML:

X-Object-Meta-author: P.D Grey
X-Object-Meta-author: Morgan White
X-Object-Meta-author: Paris Black

<metapairs>
     <meta-author>
          <![CDATA[P.D Grey,Morgan White,Paris Black]]>
     </meta-author>
</metapairs>

Property names are case sensitive, so names that differ only in case correspond to separate XML elements. For example, these X-Object-Meta- headers result in three separate XML elements: X-Object-Meta-date_written, X-Object-Meta-Date_Written, and X-Object-Meta-DATE_WRITTEN.

Retrieving custom metadata with HSwift

When you check the existence of or retrieve an object that has a .metapairs annotation containing well-formed XML, the response headers include X-Object-Meta-name headers with property/value pairs that correspond to the XML elements in the annotation. The property names in these headers are the element names with the initial meta- removed.

An element with comma-separated values is returned as multiple X-Object-Meta- headers with individual property/value pairs. Here's an example that shows an XML element with comma-separated values and the X-Object-Meta- header that results from that element:

<meta-author>
     <![CDATA[P.D Grey,Morgan White,Paris Black]]>
</meta-author>

X-Object-Meta-author: P.D Grey
X-Object-Meta-author: Morgan White
X-Object-Meta-author: Paris Black

Custom metadata usage considerations

These following considerations apply to using custom metadata with the HSwift API.

Property names

When naming properties, you should use names that, when concatenated with meta-, result in valid XML element names. That way, the X-Object-Meta- headers returned when you retrieve or check the existence of an object match the X-Object-Meta- headers you specified when you stored or copied the object.

If HCP has to modify a property name to create a valid element name, the returned X-Object-Meta- header won’t match the X-Object-Meta- header specified when the object was stored or copied. For example, if the specified header is X-Object-Meta-city/town, the returned header is X-Object-Meta-city_town.

Custom metadata size

When you use HSwift to store or copy an object, you can specify at most two kilobytes of custom metadata. The size of the custom metadata you specify is the sum of the number of bytes in the UTF-8 encoding of each property name and value.

Allowed operations

Whether you can add, replace, or delete custom metadata for an object under retention depends on a container setting. When you create a container, it's set to allow only the addition of custom metadata for objects under retention. You cannot use the HSwift API to change this setting. However, tenant administrators can change this setting for the containers you create.

.metapairs annotations with unexpected content

You could use HCP interfaces other than HSwift to store annotations named .metapairs, although it is not recommended. As a result, annotations named .metapairs are not guaranteed to be compatible with HSwift.

Here are some ways in which HCP responds to HSwift requests for object that have .metapairs annotations with unexpected content:

If the .metapairs annotation doesn't contain valid XML or if the first line in the annotation doesn't begin with the metapairs element, HCP returns an X-Object-Missing-Meta- header with a value of 1 (one) and does not return any X-Object-Meta- headers.

If an element name doesn't start with meta-, HCP doesn't return an X-Object-Meta- header for the element.

If a meta- element has no value, HCP doesn't return an X-Object-Meta- header for the element.

If a meta- element has an attribute, HCP ignores the attribute and returns the applicable X-Object-Meta- header.

If the XML contains nested elements and the lowest-level element is a meta- element, HCP returns an X-Object-Meta- header for the element. It does not return X-Object-Meta- headers for any other elements in that nested structure.

Access control lists

HCP supports access control lists (ACLs) only for containers. An ACL grants specified Keystone authenticated users permissions to perform specific operations within a container. ACLs can also make containers public.

A container ACL grants permissions to perform operations on a container and on all objects in the container. For example, an ACL for a container could grant public read permission for that container. In this case any authenticated users can retrieve any objects in that container. Unauthenticated users may also be granted read access in this case, but only if the HCP tenant administrator has allowed unauthenticated users access to the namespace via namespace protocol settings.

Through HSwift ACLs, you can either grant container permissions to specific Keystone users or make containers public. User ACLs that have been set on a container may be viewed by an authorized user by using the GET or HEAD method on the container. User ACLs are not visible through the Tenant Management Console. If you make a container public, its permissions appear in the Protocol tab of the Namespace page, under the Minimum Data Access Permissions panel on the Tenant Management Console.

You can add an ACL to a container when you create the container or in a separate operation. When you add an ACL to an existing container that already has an ACL, the new ACL replaces the old one in its in entirety.

Permissions granted by HSwift ACLs apply to the container regardless of the protocol or API used to access the container.

NoteHSwift does not support the configuration of object ACLs although they can be set through other interfaces.

ACL permissions

Adding an ACL to a container gives the Keystone user certain data access permissions for that container.

The table below lists the permissions you can give in an ACL through the HSwift API and shows the data access permissions that correspond to each ACL permission.

ACL permissionData access permissions
ReadBrowse and read
WriteWrite and delete

When you grant ACL permissions, you either assign these permissions to individual Keystone users or make the container public. Public containers are accessible by all authenticated users unless the Tenant Administrator has allowed unauthenticated users access to the namespace through namespace protocols settings.

ACLs can only be set by a Keystone HCP tenant admin or an HCP user with tenant management privileges.

Setting ACL permissions

You can grant ACLs to individual Keystone users or you can use them to make the permissions they grant public to anyone accessing the container.

In the following example, the X-Container-Write request header is used to give Keystone users P.D.Grey and Megan White the read permission:

"X-Container-Write: P.D.Grey, Megan White"
NoteThe character limit to the header string is 8192 characters. You cannot add more Keystone users to the list once you have used all the characters available.

In order to make a container public you enter the asterisk (*) as the request header's value.

In the following example, the X-Container-Read request header is used to make the Read ACL public for the container:

"X-Container-Read: *"

Removing an ACL

You can remove an ACL from a container by using the X-Remove-Container-name header. This header can also be used to remove any other form of container metadata. When writing the header, substitute name with the ACL permission you want to remove (read or write). This is the format of the header:

"X-Remove-Container-name"

Replication collision handling

If clients can write to multiple systems in a replication topology, collisions can occur when different changes are made to the same objects on different systems. Similarly, if you can make configuration changes to the tenant and its namespaces on multiple systems in a replication topology, configuration collisions can occur.

The way HCP handles collisions that occur due to replication depends on the type of collision. However, the general rule is that more recent changes have priority over conflicting less recent changes.

Object content collisions

An object content collision occurs when, for a namespace without versioning enabled, these events occur in the order shown:

  1. An object is created with the same name in that namespace on two systems in a replication topology, but the object has different content on the two systems.
  2. The object on one of the systems is replicated to the other system.

If versioning is enabled, no collision occurs. Instead, the less recently created of the two objects becomes an old version of the more recently created object.

When an object content collision occurs, the more recently created object keeps its name and location. The other object is either moved to the .lost+found directory in the same namespace or renamed, depending on the namespace configuration.

When HCP moves an object to the .lost+found directory, the full object path becomes .lost+found/replication/system-generated-directory/ old-object-path.

When renaming an object due to a content collision, HCP changes the object name to object-name.collision or object-name.version-id.collision, where version-id is the version ID of the object. HCP uses the second format only if versioning has ever been enabled for the namespace that contains the object but is not currently enabled.

If the new name is already in use, HCP changes the object name to object-name.1.collision or object-name.version-id.1.collision, as applicable. If that name is already in use, HCP successively increments the middle integer by one until a unique name is formed.

Objects that have been relocated or renamed due to content collisions are flagged as replication collisions in their system metadata. Clients can use the metadata query API to search for objects that are flagged as replication collisions.

If an object that’s flagged as a replication collision changes (for example, if its retention period is extended), its collision flag is removed. If a client creates a copy of a flagged object with a new name, the collision flag is not set on the copy.

Depending on the container configuration, objects flagged as replication collisions may be automatically deleted after a set number of days. The days are counted from the time the collision flag is set. If the collision flag is removed from an object, the object is no longer eligible for automatic deletion.

You cannot use the HSwift API to change the way HCP handles objects that are flagged as replication collisions. However, tenant administrators can change this configuration for the containers you create.

Custom metadata collisions

A custom metadata collision occurs when these events occur in the order shown:

  1. One of these changes occurs:
    • An annotation is added with the same name to a given object on each of two systems in a replication topology, but the annotation has different content on the two systems.

      The addition of an annotation to a given object on only one of the systems does not result in a custom metadata collision if the object does not have an annotation with the same name on the other system. In this case, the new annotation is replicated without conflict.

    • Different changes are made to the content of a given annotation for a given object on each of the two systems in a replication topology.
    • A change is made to the content of a given annotation for a given object on one system in a replication topology, and the same annotation is deleted on another system in the topology.
  2. The change made on one of the systems is replicated to the other system.

If a collision occurs when a custom metadata change for a given object is replicated from one system (system A) in a replication topology to another system (system B) in the topology:

  • If the last change on system A is more recent than the last change on system B, HCP applies the change from system A to the custom metadata on system B
  • If the last change on system B is more recent than the last change on system A, HCP does not change the custom metadata on system B
Here are two examples of how HCP handles collisions when custom metadata changes for a given object are replicated from one system (system A) in a replication topology to another system (system B) in the topology.
Example 1

The object starts out with annotations named a1 and a2 on both system A and system B.

The list below shows a sequence of events in which the annotations for the object are changed and the changes are then replicated.

  1. On system B, a client changes the content of a1.
  2. On system A, a client makes a different change to the content of a1.
  3. On system A, a client adds annotation a3 to the object.
  4. On system B, a client adds annotation a3 with different content from the a3 added on system A.
  5. The changes on system A are replicated to system B. The resulting annotations for the object on system B are:
    • a1 with the changed content from system A
    • a2 (unchanged)
    • a3 with the content added on system B
  6. The changes on system B are replicated to system A. The resulting annotations for the object on system A are:
    • a1 with the changed content from system A
    • a2 (unchanged)
    • a3 with the content added on system B
Example 2

The object starts out with the annotations named a1, a2, and a3 on both system A and system B.

The list below shows a sequence of events in which the annotations for the object are changed and the changes are then replicated.

  1. On system B, a client changes the content of a1.
  2. On system A, a client deletes a1.
  3. On system A, a client changes the content of a2.
  4. On system B, a client changes the content of a2.
  5. On system A, a client deletes a3.
  6. On system B, a client changes the content of a3.
  7. The changes on system A are replicated to system B. The resulting annotations for the object on system B are:
    • a2 with the changed content from system B
    • a3 with the changed content from system B
  8. The changes on system B are replicated to system A, the resulting annotations for the object on system A are:
    • a2 with the changed content from system B
    • a3 with the changed content from system B

Access control list collisions

An ACL collision occurs when these events occur in the order shown:

  1. Different changes are made to the ACL for a given object on each of two systems in a replication topology.
  2. The changed ACL on one of the systems is replicated to the other system.

An ACL is treated as a single unit. If a collision occurs when a changed ACL for a given object is replicated from one system (system A) in a replication topology to another system (system B) in the topology:

  • If the last change to the ACL on system A is more recent than the last change to the ACL on system B, HCP changes the ACL on system B to match the changed ACL on system A
  • If the last change to the ACL on system B is more recent than the last change to the ACL on system A, HCP does not change the ACL on system B
For example, suppose the ACL for a given object starts out with these grants on both system A and system B:
  • All users: read
  • User lgreen: write
  • User mwhite: write, delete

The list below shows a sequence of events in which the ACL for the object is changed and the change is then replicated.

  1. On system B, a client changes the grants in the ACL to:
    • All users: read
    • User lgreen: write, delete
    • User pdgrey: write
  2. On system A, a client changes the grants in the ACL to:
    • All users: read
    • User mwhite: write
    • User pdgrey: write
  3. The changed ACL on system A is replicated to system B. The resulting ACL for the object on system B contains these grants:
    • All users: read
    • User mwhite: write
    • User pdgrey: write

Versioning

Versioning enables the creation and management of multiple versions of an object. Each version of an object has its own system metadata and can have custom metadata and an ACL.

You can enable versioning on HCP to store multiple versions on an object with the same name, but you cannot list or access versioned objects through the HSwift API. In order to list or access older versions of an object, you need to use other REST APIs.

If versioning is disabled and you attempt to store a new version of an object, you receive a 409 error code and the operation fails. Whether versioning is initially enabled when you create a container is determined by a tenant-level configuration setting.

Allocating space

When you create a container, the container is allocated storage space based on the default quota set by the tenant administrator. Quota is the amount of space available for storing objects in the container.

The container quota may be changed by the tenant administrator through the Tenant Management Console, a Keystone Tenant admin through the HSwift API, or by an HCP user with tenant namespace management privileges.

URLs for access to HCP

With the HSwift API, the endpoint is a tenant. Every request you make to access HCP using HSwift is made within the context of a tenant.

The URL in a request identifies the target of the request. This target can be the tenant, a container within the tenant, or an object within a container within the tenant. The format you use for a URL depends on the target of the request and the authentication method being used.

An HCP system can have multiple tenants and, therefore, multiple endpoints. Each tenant has its own default configuration settings for new containers. Containers, therefore, can have different characteristics depending on the tenants within which you create them.

When accessing a tenant that requires you to be an authenticated user, you need to provide Keystone authenticated credentials or HCP user credentials.

Using SSL encryption

When you create a container or list the containers you own, HCP does not require the use of SSL security with the HSwift request; that is, you can start the URL in the request with either HTTP or HTTPS. Whether the use of SSL security with other HSwift requests is required, optional, or not supported depends on the configuration of the HSwift API for the target container.

By default, the use of SSL security is optional for requests for operations other than creating a container or listing the containers you own. You cannot use HSwift to change this configuration. However, tenant administrators can use other HCP interfaces to reconfigure the HSwift API to require or not support the use of SSL security.

Account-level operations such as creating, updating or listing the objects of a container in an account can be done with both HTTP and HTTPS.

URL considerations

The following considerations apply to URLs in HSwift API requests.

Case sensitivity in URLs

In the URLs you specify in HSwift requests:

  • HTTP and HTTPS are not case sensitive.
  • Hostnames are not case sensitive.
  • Container names are not case sensitive.
  • Unlike the items above, object names are case sensitive.
Quotation marks with URLs in command lines

When using the HCP management API, you work in a Windows, Unix, or Mac OS X shell. Some characters in the commands you enter may have special meaning to the shell. For example, the ampersand (&) used in URLs to join multiple query parameters may indicate that a process should be put in the background.

To avoid the possibility of the Windows, Unix, or Mac OS X shell misinterpreting special characters in a URL, always enclose the entire URL in double quotation marks.

Disabling SSL certificate verification

If you’re using HTTPS in your request URLs, check with your tenant administrator as to whether you need to disable SSL certificate verification. You would need to do this if the SSL server certificate presented by the HCP system is not signed by a trusted certificate authority.

With cURL, you disable SSL certificate verification by including the -k or ‑‑insecure command in the request command line.

Resource path line

The resource path line for an HSwift request specifies the operation target, whether it be an account, container, or object.

In the resource path for an HSwift request that uses Keystone authentication, the account name is interchangeable with the Tenant Id Prefix (default is AUTH_) followed by the Keystone Tenant ID. For example:

api.hcp.example.com/swift/v1/AUTH_6b6884ebb6f441cfbb7e740f6a927c9e/finance

In the resource path, the tenant ID prefix and Keystone tenant ID can be replaced with the HSwift account name. For example:

api.hcp.example.com/swift/v1/europe/finance

If the target of the request is a container, the resource path includes a forward slash followed by the container name.

If the target of the operation is an object, the request line includes a forward slash followed by the object name following the container name.

For example, here are the Keystone tenant authentication token and account name resource paths for a request to create an object named Q4_2012.ppt:

api.hcp.example.com/swift/v1/AUTH_6b6884ebb6f441cfbb7e740f6a927c9e/finance/Q4_2012.ppt
api.hcp.example.com/swift/v1/europe/finance/Q4_2012.ppt

If the request uses any query parameters, those parameters are appended to the resource path.

For example, here is a request URL to alphabetically list all containers in the europe account between the letters E and S:

http://api.hcp.example.com/swift/v1/AUTH_6b6884ebb6f441cfbb7e740f6a927c9e?marker=e&end_marker=s
http://api.hcp.example.com/swift/v1/europe?marker=e&end_marker=s

If the request includes invalid query parameters, those parameters are ignored.

Targeting an account

In an HSwift request, if the target is an account, you use a URL in this format:

http[s]://api.hcp-domain-name/swift/v1/AUTH_ID

In the format above, the account name is replaced with the Keystone Prefix tenant ID (AUTH_) and the Keystone tenant ID. This is interchangeable with the HSwift account name.

Here’s an example in which the HSwift account is europe and the account name is used in place of the Keystone Prefix tenant ID and the Keystone tenant ID:

https://api.hcp.example.com/swift/v1/europe
Targeting a container

In an HSwift request that uses Keystone authentication, if the target is a container, you use a URL in this format:

http[s]://api.hcp-domain-name/swift/v1/AUTH_ID/container-name

In the format above, the account name is replaced with the Keystone Prefix tenant ID (AUTH_) and the Keystone tenant ID. This is interchangeable with the HSwift account name.

Here’s an example in which the HSwift account name is europe and the container name is finance. The account name is used in place of the Keystone Prefix tenant ID and the Keystone tenant ID:

https://api.hcp.example.com/swift/v1/europe/finance
Targeting an object

In an HSwift request that uses Keystone authentication, if the target is an object, you use a URL in the following format:

http[s]://api.hcp-domain-name/swift/v1/AUTH_ID/container-name/object-name

In the format above, the account name is replaced with the Keystone Prefix tenant ID (AUTH_) and the Keystone tenant ID. This is interchangeable with the HSwift account name.

Here’s an example in which the HSwift account name is europe, the container name is finance, and the object name is Q4_2012.ppt. The account name is used in place of the Keystone Prefix tenant ID and the Keystone tenant ID:

https://api.hcp.example.com/swift/v1/europe/finance/Q4_2012.ppt

Query parameters

Some HSwift requests accept query parameters. Query parameters are appended to a resource URL following a question mark (?). Multiple parameters are joined by ampersands (&).

The following considerations apply to query parameters:

  • If you specify an invalid value for any query parameter, HCP returns a status code of 400 (Bad Request)
  • If you specify a query parameter that's not valid for the request, HCP ignores it.
Limiting a listing of current items

You can use the delimiter, format, limit, marker, end_marker, path, and prefix query parameters, alone or in combination with each other, to limit the list of the current objects in an account or container and control the format in which the response body is returned.

  • delimiter

    The delimiter parameter is a single alphanumeric character used to request all objects in a container up through the first occurrence of the character specified by the parameter.

    The delimiter parameter may be used to request directory listings where the forward (/) slash character is the path delimiter. Using the forward slash delimiter in combination with the prefix parameter, you can list the contents of any directory in the container. Omit the path parameter to list the root directory.

    When you use the delimiter query parameter, the listing includes both objects and directories. If you omit the delimiter query parameter, GET requests only list objects.

    For example, this is the content of an container:

    Items:

    AcctgBestPractices.doc
    acctg/
    hum_res/
    mktg/
    mktg/campaign_GoGetEm_expenses.xls
    mktg/campaign_LiveIt_expenses.xls
    quarterly_rpts/
    quarterly_rpts/budget_proposals/Q2_2012.ppt
    quarterly_rpts/budget_proposals/Q3_2012.ppt
    quarterly_rpts/budget_proposals/quotas/Q4_2012.ppt
    sales/
    sales_quotas_2013.pdf

    The container listing returned in response to a GET request with the delimiter=/ query parameter contains these items:

    Returned values:

    AcctgBestPractices.doc
    acctg/
    hum_res/
    mktg/
    quarterly_rpts/
    sales/
    sales_quotas_2013.pdf

    The lists of named items included in a listing are subject to any other character specified in the request.

    NoteThis query parameter can only be used to request a container listing, not an account listing.
  • format

    You use the format query parameter to determine the way the response body is formatted. The default method is plain text, but this can be changed to either XML or JSON.

    The Accept request header serves the same function as the format query parameter. If they are both used, the Accept header is ignored.

    Here is an example of how to use the query parameter:

    format=xml
  • limit

    You use the limit query parameter to limit the number of items in the returned container listing to fewer than 10,000.

    For example, the container listing returned in response to a GET request with the limit=5 query parameter contains these items:

    AcctgBestPractices.doc
    mktg/campaign_GoGetEm_expenses.xls
    mktg/campaign_LiveIt_expenses.xls
    quarterly_rpts/budget_proposals/Q2_2012.ppt
    quarterly_rpts/budget_proposals/Q3_2012.ppt
  • marker

    A container listing is returned in alphabetical order. You use the marker query parameter to only list the items that sort alphabetically after the value of the marker parameter.

    This is useful for paging through long lists of objects in a container. Using the name of the last object in the current page as the marker parameter retrieves the next page of objects.

    For example, the container listing returned in response to a GET request with the marker=mktg/campaign_LiveIt_expenses.xls query parameter contains these items because they all appear after mktg/campaign_LiveIt_expenses.xls:

    quarterly_rpts/budget_proposals/Q2_2012.ppt
    quarterly_rpts/budget_proposals/Q3_2012.ppt
    quarterly_rpts/budget_proposals/quotas/Q4_2012.ppt
    sales/budget_proposals/BudgProp-2013
    sales_quotas_2013.pdf

    If the string you specify as the value of the marker query parameter is the name of a directory and does not end with a forward slash (/), items that begin with that string followed by a forward slash are omitted from the listing.

  • end_marker

    You use the end_marker query parameter to only list the items that sort alphabetically before the value of the end_marker parameter.

    For example, the container listing returned in response to a GET request with the end_marker=quarterly_rpts/ query parameter contains these items:

    AcctgBestPractices.doc
    mktg/campaign_GoGetEm_expenses.xls
    mktg/campaign_LiveIt_expenses.xls
  • path

    You use the path query parameter to list all objects within the directory of a specified path. If there are subdirectories in the selected path the contents of the subdirectories are not listed. For instance, the following objects are returned in response to GET container request:

    AcctgBestPractices.doc
    acctg/
    hum_res/
    mktg/
    mktg/campaign_GoGetEm_expenses.xls
    mktg/campaign_LiveIt_expenses.xls
    quarterly_rpts/
    quarterly_rpts/budget_proposals/Q2_2012.ppt
    quarterly_rpts/budget_proposals/Q3_2012.ppt
    quarterly_rpts/budget_proposals/quotas/Q4_2012.ppt
    sales/
    sales_quotas_2013.pdf

    path=quarterly_rpts returns:

    quarterly_rpts/
    quarterly_rpts/budget_proposals/
  • prefix

    You use the prefix query parameter to request a container listing that contains only items with names that begin with the specified character string (the prefix).

    The prefix query parameter is used in conjunction with the delimiter parameter to list the contents of directories.

    For example, the container listing returned in response to a GET request with the prefix=sales query parameter contains only these items:

    sales/budget_proposals/BudgProp-2013
    sales_quotas_2013.pdf

Using an IP address in a URL

Normally, you let HCP choose the node on which to process an HSwift API request. You can, however, use an IP address in the request URL to access the system on a specific node. To do this, you replace the fully qualified hostname in the URL with the IP address of an HCP node.

Here's an example of a curl command that uses a URL with an IP address. In this instance, the tenant name is replaced by its Keystone Prefix tenant ID and the Keystone tenant ID:

curl -X PUT -T http://192.168.210.16/swift/v1/AUTH_6b6884ebb6f441cfbb7e740f6a927c9e/finance /Q4_2012.ppt -H "X-Auth-Token: dc5efec8f546455eac974e7bbfd0dd87" -H "Content-Length: 63"

The formats for IP address URLs are:

https://ip-address/swift/v1/tenant-name/namespace-name/object-name
https://ip-address/swift/v1/AUTH_tenant-id/namespace-name/object-name

For the IP addresses of the HCP nodes, contact your tenant administrator.

 

  • Was this article helpful?