HCP System Management Help


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.

Note: This 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

© 2017 Hitachi Vantara Corporation. All rights reserved.