From d80560cf95f07ba49bf7207d30e214d09acf7b33 Mon Sep 17 00:00:00 2001 From: Erik Wilson Date: Mon, 15 Dec 2014 16:17:10 -0600 Subject: [PATCH] Adds retrieving large lists info to End User Guide With the moving of the Object Storage API content from a long-form dev guide to a specification, some topics needed To be added to the End User Guide. Change-Id: I0ee8366bc88985ba985518c8c014a03af6bdc05a Partial-bug: 1392382 --- doc/user-guide/section_cli_swift_howto.xml | 1 + .../section_object-api-large-lists.xml | 107 ++++++++++++++++++ 2 files changed, 108 insertions(+) create mode 100644 doc/user-guide/section_object-api-large-lists.xml diff --git a/doc/user-guide/section_cli_swift_howto.xml b/doc/user-guide/section_cli_swift_howto.xml index 999aca00b4..c1e09e57de 100644 --- a/doc/user-guide/section_cli_swift_howto.xml +++ b/doc/user-guide/section_cli_swift_howto.xml @@ -132,4 +132,5 @@ X-Timestamp: 1392684036.33306 + diff --git a/doc/user-guide/section_object-api-large-lists.xml b/doc/user-guide/section_object-api-large-lists.xml new file mode 100644 index 0000000000..349f884988 --- /dev/null +++ b/doc/user-guide/section_object-api-large-lists.xml @@ -0,0 +1,107 @@ + + %openstack; ]> +
+ Page through large lists of containers or objects + If you have a large number of containers or objects, you can + use the marker, + limit, and + end_marker parameters to control + how many items are returned in a list and where the list + starts or ends. + + + marker + + When you request a list of containers or + objects, Object Storage returns a maximum of + 10,000 names for each request. To get subsequent + names, you must make another request with the + marker parameter. Set + the marker parameter to the + name of the last item returned in the previous + list. You must URL-encode the + marker value before you + send the HTTP request. Object Storage returns a + maximum of 10,000 names starting after the last + item returned. + + + + limit + + To return fewer than 10,000 names, use the + limit parameter. If the + number of names returned equals the specified + limit (or 10,000 if you + omit the limit parameter), + you can assume there are more names to list. If + the number of names in the list is exactly + divisible by the limit + value, the last request has no content. + + + + end_marker + + Limits the result set to names that are less + than the end_marker + parameter value. You must URL-encode the + end_marker value before + you send the HTTP request. + + + + + To page through a large list of containers + Assume the following list of container names: + apples +bananas +kiwis +oranges +pears + + Use a limit of two: + # curl -i $publicURL/?limit=2 -X GET -H "X-Auth-Token: $token" + apples +bananas + Because two container names are returned, there are + more names to list. + + + Make another request with a + marker parameter set to the + name of the last item returned: + # curl -i $publicURL/?limit=2&marker=bananas -X GET -H "X-Auth-Token: $token" + kiwis +oranges + Again, two items are returned, and there might be + more. + + + Make another request with a + marker of the last item + returned: + # curl -i $publicURL/?limit=2&marker=oranges -X GET -H "X-Auth-Token: $token" + pears + You receive a one-item response, which is fewer than + the limit number of names. This + indicates that this is the end of the list. + + + Use the end_marker parameter + to limit the result set to object names that are less + than the end_marker parameter + value: + # curl -i $publicURL/?end_marker=oranges -X GET -H "X-Auth-Token: $token" + apples +bananas +kiwis + You receive a result set of all container names + before the end-marker + value. + + +