From cd98f1acd84be27cca2c0348599a5084f0a8f01f Mon Sep 17 00:00:00 2001 From: Diane Fleming Date: Tue, 31 Dec 2013 14:05:11 -0600 Subject: [PATCH] Update Object Storage API Reference to point to wadl in api-site Partial-Bug: #1187119 Change-Id: I94054b046a94260ba8825bdb42439adfcaf9fdce author: diane fleming --- .../ch_object-api-general.xml | 294 ++--- .../ch_object-api-overview.xml | 2 +- .../ch_object-api-storage-services.xml | 76 +- ...ch_object-api-troubleshooting-examples.xml | 1122 +++++++---------- .../samples/server-post-req.xml | 25 + .../samples/server-post-resp.xml | 15 + .../samples/xml_curl.txt | 7 + .../section_authentication.xml | 74 ++ .../section_curl_how_curl_works.xml | 203 +++ .../section_curl_xml.xml | 119 ++ .../section_gs_curl_how_curl_works.xml | 203 +++ .../section_gs_curl_xml.xml | 122 ++ .../section_large_lists_objects.xml | 46 + .../section_object-api-create-website.xml | 7 +- .../section_object-api-dochistory.xml | 2 +- ...ction_object-api-storage-container-svc.xml | 190 +-- .../section_object-api-storage-object-svc.xml | 185 +-- ...section_object-api-storage_account_svc.xml | 332 +---- .../section_serialized_list_output.xml | 32 + 19 files changed, 1537 insertions(+), 1519 deletions(-) create mode 100644 openstack-object-storage-dev/samples/server-post-req.xml create mode 100644 openstack-object-storage-dev/samples/server-post-resp.xml create mode 100644 openstack-object-storage-dev/samples/xml_curl.txt create mode 100644 openstack-object-storage-dev/section_authentication.xml create mode 100644 openstack-object-storage-dev/section_curl_how_curl_works.xml create mode 100644 openstack-object-storage-dev/section_curl_xml.xml create mode 100644 openstack-object-storage-dev/section_gs_curl_how_curl_works.xml create mode 100644 openstack-object-storage-dev/section_gs_curl_xml.xml create mode 100644 openstack-object-storage-dev/section_large_lists_objects.xml create mode 100644 openstack-object-storage-dev/section_serialized_list_output.xml diff --git a/openstack-object-storage-dev/ch_object-api-general.xml b/openstack-object-storage-dev/ch_object-api-general.xml index 1ef5120..eadc294 100644 --- a/openstack-object-storage-dev/ch_object-api-general.xml +++ b/openstack-object-storage-dev/ch_object-api-general.xml @@ -1,192 +1,122 @@ - - - - -GET'> -HEAD'> PUT'> -POST'> -DELETE'> - - - - - -'> - - - - - -'> ]> - General API Information -
- Authentication - Client authentication is provided via a ReST interface - using the &GET; method, with v1.0 supplied as - the path. Additionally, two headers are required, - X-Auth-User and X-Auth-Key - with values for the username and API Access Key - respectively. - Each ReST request against the OpenStack Object Storage - system requires the inclusion of a specific authorization - token HTTP x-header, defined as X-Auth-Token. - Clients obtain this token, along with the Cloud Servers - API URL, by first using an authentication service and - supplying a valid username and API access key. - - Request - To authenticate, you must supply your username and - API access key in x-headers: - - - - Use your OpenStack Object Storage - (Swift) username as the username for the - API. Place it in the - X-Auth-User x-header. - - - - Get your API access key from - authentication service you chose when - installing. You have some options for - auth, including tempauth (which is - included with Swift), swauth (an auth - service for Swift as WSGI middleware that - uses Swift itself as a backing store that - is provided via download from Github), the - OpenStack Identity Service (project named - Keystone), or you can use your own - authentication system. Place your access - key in the X-Auth-Key - x-header. - - - - - - Authentication HTTP Request - - - - - Response - When authentication is successful, an HTTP status - 204 (No Content) is returned with the - X-Storage-Url and - X-Auth-Token headers. Any 2xx - response is a good response. For example, a 202 - response means the request has been accepted. Also, - additional X- headers may be returned. - These additional headers are related to other - Rackspace services and can be ignored. An HTTP status - of 401 (Unauthorized) is returned upon authentication - failure. All subsequent container/object operations - against OpenStack Object Storage should be made - against the URI specified in - X-Storage-Url and must include the - X-Auth-Token header. - - Authentication HTTP Response - - - The X-Storage-Url will need to be - parsed and used in the connection and request line of - all subsequent requests against Object Storage. In the - example response above, users connecting to OpenStack - Object Storage would send most container/object - requests with a host header of - storage.swiftdrive.com and the - request line's version and account as - /v1/CF_xer7_34. Note that - authentication tokens are valid for a 24 hour period - for many authentication configurations. - -
- -
- Overview of API Operations - The OpenStack Object Storage API is implemented as a set - of ReSTful (Representational State Transfer) web services. - All authentication and container/object operations can be - performed with standard HTTP calls. See the Representational State Transfer on ReST for - more information - The following constraints apply to the ReST API's HTTP - requests: - - - Maximum number of HTTP headers per request: - 90 - - - Maximum length of all HTTP headers: 4096 - bytes - - - Maximum length per HTTP request line: 8192 - bytes - - - Maximum length of HTTP request: 5 - gigabytes - - - Maximum length of container name: 256 - bytes - - - Maximum length of object name: 1024 bytes - - - Container and object names must be UTF-8 encoded and then should be properly - URL-encoded prior to interacting with the ReST interface. You may be using an API - binding that performs the URL-encoding on your behalf. If so, do not URL-encode before - calling the API binding otherwise you will double-encode container and object names. The - length restrictions should be checked against the URL-encoded string. - Each ReST request against the OpenStack Object Storage - system requires the inclusion of a specific - authorization token HTTP header - defined as X-Auth-Token. Clients obtain this - token, along with the OpenStack Object Storage URLs, by - first using the Authentication service and supplying a - valid Username and API Access Key. - - The ReST service identified with - X-Storage-Url is used for managing the - data stored in the system. Example operations are creating - containers and uploading objects. - - In the following sections, the purpose of each HTTP - method depends upon which service the call is made - against. For example, a &PUT; request against - X-Storage-Url can be used to create a - container or upload an - object. - The language-specific APIs mask this system separation - from the programmer. They simply create a container and - mark it public and it handles calling - out to the appropriate back-end services using the - appropriate ReST API. - - All requests to authenticate and operate against - OpenStack Object Storage are performed using SSL over - HTTP (HTTPS) on TCP port 443. - - -
- + General API information + The Object Storage API is implemented as a set of + Representational state transfer (REST) web services. You use + standard HTTP calls to perform authentication and + account-level, container-level, and object-level operations. + For more information, see Representational state transfer. + Object Storage HTTP requests have the following + constraints: + + + + Item + Maximum value + Notes + + + + + Number of HTTP headers + 90 + + + + Length of HTTP headers + 4096 bytes + + + + Length per HTTP request line + 8192 bytes + + + + Length of HTTP request + 5 GBs + + + + Length of container names + 256 bytes + Cannot contain the / + character. + + + Length of object names + 1024 bytes + No character restrictions. + + + + Container and object names must be UTF-8 encoded and + properly URL-encoded before you call the API binding. If you + use an API binding that performs the URL-encoding for you, do + not URL-encode the container and object names before you call + the API binding. Otherwise, you double-encode these names. + Check the length restrictions against the URL-encoded + string. + Each Object Storage API request must include an + authentication token in the + X-Auth-Token HTTP header. Clients use an + authentication service to obtain this token and the OpenStack + Object Storage URLs. For information, see . + You + specify the Object Storage URL in the + X-Storage-Url header. This service manages + the system data. Example operations include creating + containers and uploading objects. + + The purpose of each HTTP method depends on which service the + call is made against. For example, a &PUT; request against the + service specified in the X-Storage-Url header is + used to create containers and upload + objects. + The language-specific APIs mask this system separation from + the programmer. They simply create a container and mark it + public and it handles calling out to + the appropriate back-end services using the appropriate ReST + API. + + All requests to authenticate and operate against + OpenStack Object Storage are performed using SSL over HTTP + (HTTPS) on TCP port 443. + + Use the ReST API to interact with the storage component of + OpenStack Object Storage. All requests are directed to the + host and URL described in the X-Storage-Url HTTP + header obtained during successful authentication. + The following sections describe the tasks that you can + perform in the storage system: + + + Storage + account services. Use to perform + account-level tasks. + + + Storage container services. Use to perform + container-level tasks. + + + Storage + object services. Use to perform + object-level tasks. + + + + + diff --git a/openstack-object-storage-dev/ch_object-api-overview.xml b/openstack-object-storage-dev/ch_object-api-overview.xml index caa2cd7..4613eb9 100644 --- a/openstack-object-storage-dev/ch_object-api-overview.xml +++ b/openstack-object-storage-dev/ch_object-api-overview.xml @@ -53,7 +53,7 @@ format="SVG" scale="60"/> xlink:href="http://bugs.launchpad.net/swift" >http://bugs.launchpad.net/swift.
- Intended Audience + Intended audience This guide is intended to assist software developers who want to develop applications using the OpenStack Object Storage API. It fully documents the ReST application diff --git a/openstack-object-storage-dev/ch_object-api-storage-services.xml b/openstack-object-storage-dev/ch_object-api-storage-services.xml index 07e83a8..9b77db7 100644 --- a/openstack-object-storage-dev/ch_object-api-storage-services.xml +++ b/openstack-object-storage-dev/ch_object-api-storage-services.xml @@ -1,82 +1,10 @@ - - - - - - - -COPY'> -GET'> -HEAD'> -PUT'> -POST'> -DELETE'> - - - - - -'> - - - - - -'> -]> - API Operations for Storage Services - Use the ReST API to interact with the storage component of - OpenStack Object Storage. All requests are directed to the host - and URL described in the X-Storage-Url HTTP header - obtained during successful authentication. - Review the following requirements for using storage - services: - - - Container names cannot exceed 256 bytes and cannot contain - the / character. - - - Object names cannot exceed 1024 bytes, and have no - character restrictions. - - - Object and container names must be UTF-8 encoded and then - URL-encoded to interact with the ReST API. - - - The - following sections describe the actions that you can perform in - the storage system. - - - . Actions that - you can perform at the account level of the storage system. - - - - . Actions that - you can perform on containers. - - - . How to - use your swift account to create a static website. - - - . Actions that - you can perform on objects. - - + xml:id="ch_object-storage-dev-api-storage" role="api-reference"> + API operations - diff --git a/openstack-object-storage-dev/ch_object-api-troubleshooting-examples.xml b/openstack-object-storage-dev/ch_object-api-troubleshooting-examples.xml index 81998c9..f2265a4 100644 --- a/openstack-object-storage-dev/ch_object-api-troubleshooting-examples.xml +++ b/openstack-object-storage-dev/ch_object-api-troubleshooting-examples.xml @@ -1,10 +1,6 @@ - - - GET'> @@ -12,31 +8,17 @@ PUT'> POST'> DELETE'> - - - - - -'> - - - - - -'> ]> - Troubleshooting and Examples - This section introduces a command-line utility, cURL, and - demonstrates interacting with the ReST interfaces through that - utility. -
- Using cURL + Object Storage examples + This section introduces the cURL command-line utility and + demonstrates how to use cURL to make API calls. + + +
+ Authenticate with the OpenStack Identity + Service + This section provides a overview of the authentication + process. For request and response details, see Authenticate in the OpenStack + Identity Service API v2.0 + Reference. + + + Send your credentials and a tenant ID or tenant + name to the Identity Service. + The response includes an authentication token + and service catalog. + + + Select the service catalog entry where + type is + object-store. Use the + publicURL endpoint, which + contains a URL with the full path to the Object + Storage account. The URL has the format, + https://hostname/v1/account. + +
-
- Authentication - To use the ReST API, you must obtain a authorization - token, which you pass to each request in the - X-Auth-Token header. The following - example demonstrates how to use cURL to obtain the - authorization token and the URL of the storage - system. - - cURL Authenticate - -curl \ - \ - \ - https://auth.api.yourcloud.com/v1.0 - - - -HTTP/1.1 204 No Content -Date: Thu, 09 Jul 2009 15:31:39 GMT -Server: Apache/2.2.3 -X-Storage-Url: https://storage.swiftdrive.com/v1/CF_xer7_343 -X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae +
+ Authenticate with Tempauth + + + Supply your user name and API access key in + headers, as follows: + + + X-Auth-User header. + Specify your Object Storage user + name. + + + + X-Auth-Key header. + Specify your access key.. + + + The following example shows a sample + request: + GET /v1/auth HTTP/1.1 +Host: swift.yourcloud.com +X-Auth-User: jdoe +X-Auth-Key: jdoepassword + + + When authentication is successful, you receive + an HTTP 204 + (No Content) status code. + Any + 2nn + response indicates success. + The X-Auth-Token response + header contains the authentication token. The + X-Storage-Url response + header contains a URL that includes a full path to + the Object Storage account. The URL has the + format, + https://hostname/v1/account. + The following example shows a sample + response: + HTTP/1.1 204 No Content +Date: Mon, 12 Nov 2010 15:32:21 +Server: Apache +X-Storage-Url: https://swift.yourcloud.com/v1/AUTH_123456789_12345 +X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb Content-Length: 0 -Connection: close -Content-Type: application/octet-stream - - - - The storage URL and authentication token are returned in - the headers of the response. After authentication, you can - use cURL to perform &HEAD;, &GET;, &DELETE;, &POST; and - &PUT; requests on the storage service. +Content-Type: text/plain; charset=UTF-8 + +
- Determining Storage Usage + Determine storage usage A &HEAD; request can be sent to the storage service to determine how much data you have stored in the system and the number of containers you are using. Use the -X switch to specify the correct HTTP method and the -i to dump the HTTP response headers to terminal output (stdout). - - cURL Get Storage Space - -curl \ - \ - https://storage.swiftdrive.com/v1/CF_xer7_343 - - - -HTTP/1.1 204 No Content -Date: Thu, 09 Jul 2009 15:38:14 GMT -Server: Apache -X-Account-Container-Count: 22 -X-Account-Bytes-Used: 9891628380 -Content-Type: text/plain - - - + $ curl –X HEAD -i \ + -H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae" \ + https://storage.swiftdrive.com/v1/CF_xer7_343 + HTTP/1.1 204 No Content + Date: Thu, 09 Jul 2009 15:38:14 GMT + Server: Apache + X-Account-Container-Count: 22 + X-Account-Bytes-Used: 9891628380 + Content-Type: text/plain The HTTP request must include a header to specify the authentication token. The HTTP headers in the response indicate the number of containers in this storage account and the total bytes stored for the entire account.
- Listing and Creating Containers + List and create containers The simplest operation for Object Storage is to simply list the containers you have, which when you don't have any containers yet isn't terribly exciting: - - cURL List Storage Container - -curl \ - \ - https://storage.swiftdrive.com/v1/CF_xer7_343 - - - -HTTP/1.1 204 No Content -X-Account-Object-Count: 0 -X-Account-Bytes-Used: 0 -X-Account-Container-Count: 0 -Accept-Ranges: bytes -X-Trans-Id: txe8ca5138ac8643ec84070543a0c9c91e -Content-Length: 0 -Date: Mon, 07 Nov 2011 17:07:01 GMT - - - + $ curl –X GET -i \ + -H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae" \ + https://storage.swiftdrive.com/v1/CF_xer7_343 + HTTP/1.1 204 No Content + X-Account-Object-Count: 0 + X-Account-Bytes-Used: 0 + X-Account-Container-Count: 0 + Accept-Ranges: bytes + X-Trans-Id: txe8ca5138ac8643ec84070543a0c9c91e + Content-Length: 0 + Date: Mon, 07 Nov 2011 17:07:01 GMT So, you take the X-Auth-Token obtained from the authentication operation, pass it as a header value, execute the operation against the URL obtained from the @@ -170,39 +178,23 @@ Date: Mon, 07 Nov 2011 17:07:01 GMT containers. Next, let's create a container and then do the listing again: - - cURL Create Storage Container - -curl \ - \ - https://storage.swiftdrive.com/v1/CF_xer7_343/george - - - -HTTP/1.1 201 Created + $ curl –X &PUT; -i \ + -H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae" \ + https://storage.swiftdrive.com/v1/CF_xer7_343/george +HTTP/1.1 201 Created Content-Length: 18 Content-Type: text/html; charset=UTF-8 X-Trans-Id: txb25576385284476d9fa6c73835f21650 Date: Mon, 07 Nov 2011 17:44:20 GMT -201 Created - - - - Append the container name to the URL and force the PUT - verb. That creates a container, which we can now see when - we do a listing: - - cURL List Storage Container After a - Creation - -curl \ - \ - https://storage.swiftdrive.com/v1/CF_xer7_343 - - - -HTTP/1.1 200 OK +201 Created + Append the container name to the URL and force the &PUT; + verb. That creates a container, which you see when you do + a listing: + $ curl –X GET -i \ + -H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae" \ + https://storage.swiftdrive.com/v1/CF_xer7_343 +HTTP/1.1 200 OK X-Account-Object-Count: 0 X-Account-Bytes-Used: 0 X-Account-Container-Count: 1 @@ -212,32 +204,23 @@ Content-Type: text/plain; charset=utf-8 X-Trans-Id: txaedd6b080626453399c9f5febbddb73b Date: Mon, 07 Nov 2011 17:44:23 GMT -george - - - +george You may have noticed the account metadata that comes back from the listing call. As you'd guess, it'll tell you how many objects you have, how much space you are using, and how many containers you are using.
- Paging Lists of Containers + Page through lists of containers If you have a large number of containers, it is sometimes more convenient to page through them than getting some big long list of them. If I create more containers and then do a regular listing, here's what it looks like with five containers: - - cURL List Storage Container (long list) - -curl \ - \ - https://storage.swiftdrive.com/v1/CF_xer7_343 - - - -HTTP/1.1 200 OK + $ curl –X GET -i \ + -H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae" \ + https://storage.swiftdrive.com/v1/CF_xer7_343 +HTTP/1.1 200 OK X-Account-Object-Count: 0 X-Account-Bytes-Used: 0 X-Account-Container-Count: 5 @@ -254,20 +237,12 @@ george jerry - Suppose I want a page size of 2, all I do is append a ""?limit=2"" to my URL: - - cURL List Storage Container with Paging (first - page) - -curl \ - \ - https://storage.swiftdrive.com/v1/CF_xer7_343?limit=2 - - - -HTTP/1.1 200 OK + $ curl –X GET -i \ + -H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae" \ + https://storage.swiftdrive.com/v1/CF_xer7_343?limit=2 +HTTP/1.1 200 OK X-Account-Object-Count: 0 X-Account-Bytes-Used: 0 X-Account-Container-Count: 5 @@ -279,23 +254,15 @@ Date: Mon, 07 Nov 2011 19:05:30 GMT cosmo dogs - - - + Not surprisingly, I only get two containers. To get the next page, you tell the system which item you last saw with the "marker=" specifier: - - cURL List Storage Container with Paging (later - pages) - -curl \ - \ - https://storage.swiftdrive.com/v1/CF_xer7_343?marker=dogs\&limit=2 - - - -HTTP/1.1 200 OK + $ curl –X GET -i \ + -H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae" \ + https://storage.swiftdrive.com/v1/CF_xer7_343?marker=dogs\&limit=2 + +HTTP/1.1 200 OK X-Account-Object-Count: 0 X-Account-Bytes-Used: 0 X-Account-Container-Count: 5 @@ -307,9 +274,7 @@ Date: Mon, 07 Nov 2011 19:15:00 GMT elaine george - - - + Notice that I had to use \& so that my bash shell didn't try to interpret the & as wanting to run something in its own thread. With that in place, you get @@ -317,23 +282,17 @@ george marker.
- Serialized Output + Serialized output In other situations, like if you are working on a language binding on top of the REST API, you might want more structured data back from the method calls. By appending a "format=" and then choosing either json or xml, you can get that structured data back you've been dreaming about. - - cURL List Storage Container (JSON output) - -curl \ - \ - https://storage.swiftdrive.com/v1/CF_xer7_343?format=json - - - -HTTP/1.1 200 OK + $ curl –X GET -i \ + -H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae" \ + https://storage.swiftdrive.com/v1/CF_xer7_343?format=json +HTTP/1.1 200 OK X-Account-Object-Count: 0 X-Account-Bytes-Used: 0 X-Account-Container-Count: 5 @@ -350,17 +309,10 @@ Date: Mon, 07 Nov 2011 19:17:33 GMT {"name":"jerry","count":0,"bytes":0}] - - - cURL List Storage Container (XML output) - -curl \ - \ - https://storage.swiftdrive.com/v1/CF_xer7_343?format=xml - - - -HTTP/1.1 200 OK + $ curl –X GET -i \ + -H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae" \ + https://storage.swiftdrive.com/v1/CF_xer7_343?format=xml +HTTP/1.1 200 OK X-Account-Object-Count: 0 X-Account-Bytes-Used: 0 X-Account-Container-Count: 5 @@ -378,9 +330,7 @@ Date: Mon, 07 Nov 2011 19:17:38 GMT <container><name>george</name><count>0</count><bytes>0</bytes></container> <container><name>jerry</name><count>0</count><bytes>0</bytes></container> </account> - - - + The remainder of the examples in this document will use the standard, non-serialized output but all operations accept the format argument. You might notice that when you @@ -390,20 +340,15 @@ Date: Mon, 07 Nov 2011 19:17:38 GMT
- Container Metadata and Deleting Containers + Get container metadata and delete containers You can get at container metadata directly simply by appending the name of the container to a HEAD request: - - cURL List Container Metadata - -curl \ - \ - https://storage.swiftdrive.com/v1/CF_xer7_343/dogs - - - -HTTP/1.1 204 No Content + + $ curl –X HEAD -i \ + -H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae" \ + https://storage.swiftdrive.com/v1/CF_xer7_343/dogs + HTTP/1.1 204 No Content X-Container-Object-Count: 0 X-Container-Bytes-Used: 0 Accept-Ranges: bytes @@ -412,39 +357,24 @@ Content-Length: 0 Date: Mon, 07 Nov 2011 20:39:41 GMT - Not very exciting without any objects in the container, but you get the idea. While you cannot update or delete container metadata, you can delete a container: - - cURL Delete Storage Container - -curl \ - \ - https://storage.swiftdrive.com/v1/CF_xer7_343/george - - - -HTTP/1.1 204 No Content + $ curl –X DELETE -i \ + -H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae" \ + https://storage.swiftdrive.com/v1/CF_xer7_343/george + HTTP/1.1 204 No Content Content-Length: 0 Content-Type: text/html; charset=UTF-8 X-Trans-Id: tx3fa3857f266f44319d9b8f4bf7ce7fc8 Date: Mon, 07 Nov 2011 20:42:58 GMT - - - + Then let's confirm the delete by listing the containers again: - - cURL List Containers After a Delete - -curl \ - \ - https://storage.swiftdrive.com/v1/CF_xer7_343 - - - -HTTP/1.1 200 OK + $ curl –X GET -i \ + -H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae" \ + https://storage.swiftdrive.com/v1/CF_xer7_343 + HTTP/1.1 200 OK X-Account-Object-Count: 0 X-Account-Bytes-Used: 0 X-Account-Container-Count: 4 @@ -458,12 +388,10 @@ cosmo dogs elaine jerry - - - +
- Special Metadata: Container ACLs + Special metadata: container ACLs A particularly important metadata element for containers is X-Container-Read, which establishes the ACL permissions on who can read objects in the container. Prior to being @@ -472,16 +400,11 @@ jerry question. Doing a simple listing of a container shows us the absence of X-Container-Read in this default situation: - - cURL List Container Showing Lack of ACL - -curl \ - \ - https://storage.swiftdrive.com/v1/CF_xer7_343/jerry - - - -HTTP/1.1 204 No Content + + $ curl –X GET -i \ + -H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae" \ + https://storage.swiftdrive.com/v1/CF_xer7_343/jerry + HTTP/1.1 204 No Content X-Container-Object-Count: 0 X-Container-Bytes-Used: 0 Accept-Ranges: bytes @@ -490,23 +413,16 @@ Content-Length: 0 Date: Tue, 15 Nov 2011 03:29:22 GMT - - Now we'll set the X-Container-Read. For a full - explanation of valid values, see: - http://swift.openstack.org/misc.html#acls but for our - simple needs, we'll enable read access and listing access - to anybody: - - cURL Setting an ACL on a Container - -curl \ - \ - \ - https://storage.swiftdrive.com/v1/CF_xer7_343/jerry - - - -HTTP/1.1 202 Accepted + Now set the X-Container-Read header. + For a full explanation of valid values, see http://swift.openstack.org/misc.html#acls. + Enable read access and listing access to anybody: + $ curl –X &PUT; -i \ + -H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae" \ + -H "X-Container-Read: .r:*,.rlistings" \ + https://storage.swiftdrive.com/v1/CF_xer7_343/jerry + HTTP/1.1 202 Accepted Content-Length: 58 Content-Type: text/html; charset=UTF-8 X-Trans-Id: txf2befb56b1854a50995f710f2db48089 @@ -515,20 +431,12 @@ Date: Tue, 15 Nov 2011 03:33:16 GMT 202 Accepted The request is accepted for processing. - - - + To see the metadata change, do a listing again: - - cURL List Container Showing with an ACL - -curl \ - \ - https://storage.swiftdrive.com/v1/CF_xer7_343/jerry - - - -HTTP/1.1 204 No Content + $ curl –X GET -i \ + -H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae" \ + https://storage.swiftdrive.com/v1/CF_xer7_343/jerry + HTTP/1.1 204 No Content X-Container-Object-Count: 0 X-Container-Read: .r:*,.rlistings X-Container-Bytes-Used: 0 @@ -536,9 +444,7 @@ Accept-Ranges: bytes X-Trans-Id: txb40eb86d949345f7bc66b01e8b63c3a5 Content-Length: 0 Date: Tue, 15 Nov 2011 03:33:36 GMT - - - + The side effect of giving anybody read access is that any object in the container is now accessible from a browser simply by entering the X-Storage-URL used @@ -550,36 +456,23 @@ Date: Tue, 15 Nov 2011 03:33:36 GMT using this method.
- Creating Objects + Create objects Enough with containers already, let's start to upload some objects. Suppose you had a local directory full of dog pictures: - - Sample File Listing - - -$ ls -l -total 504 + $ ls -l + total 504 -rw-r--r--@ 1 petecj2 staff 44765 Nov 7 14:49 JingleRocky.jpg -rw-r--r--@ 1 petecj2 staff 100864 Nov 7 14:47 RockyAndBuster.jpg --rw-r--r--@ 1 petecj2 staff 107103 Nov 7 14:47 SittingBuster.jpg - - - - In order to put one of them in a container called "dogs" - with cURL, you'd do this: - - Creating and Uploading an Object to a - Container - -curl \ - \ - \ - https://storage.swiftdrive.com/v1/CF_xer7_343/dogs/JingleRocky.jpg - - - -HTTP/1.1 201 Created +-rw-r--r--@ 1 petecj2 staff 107103 Nov 7 14:47 SittingBuster.jpg + To put one of them in a container called "dogs" with + cURL, you'd do this: + + $ curl –X &PUT; -i \ + -H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae" \ + -T JingleRocky.jpg \ + https://storage.swiftdrive.com/v1/CF_xer7_343/dogs/JingleRocky.jpg + HTTP/1.1 201 Created Content-Length: 118 Content-Type: text/html; charset=UTF-8 Etag: f7d40eceffdd9c2ecab226105737b2a6 @@ -599,25 +492,17 @@ Date: Mon, 07 Nov 2011 22:51:30 GMT </body> </html> - - - - The object gets named from whatever we append to the URL - path beyond the container name and the -T switch lets us - name a file to push with the operation as the request - body. We can confirm the upload by checking the container + + The name of the object comes from whatever you append to + the URL path beyond the container name. The -T switch lets + you name a file to push with the operation as the request + body. Confirm the upload by checking the container again: - - cURL List Container Showing Newly Uploaded - Object - -curl \ - \ - https://storage.swiftdrive.com/v1/CF_xer7_343/dogs - - - -HTTP/1.1 200 OK + + $ curl –X GET -i \ + -H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae" \ + https://storage.swiftdrive.com/v1/CF_xer7_343/dogs + HTTP/1.1 200 OK X-Container-Object-Count: 1 X-Container-Read: .r:*,.rlistings X-Container-Bytes-Used: 44765 @@ -628,24 +513,13 @@ X-Trans-Id: tx83be89d4e1a34eacbfeebcdfc7a7f2e7 Date: Mon, 07 Nov 2011 22:56:25 GMT JingleRocky.jpg - - - + Notice that the container metadata now reflects the - number of objects and the bytes match what we saw when we - did the directory listing. After uploading the other two - similarly, we get a full object listing: - - cURL List Container Showing Multiple Newly Uploaded - Objects - -curl \ - \ - https://storage.swiftdrive.com/v1/CF_xer7_343/dogs - - - -HTTP/1.1 200 OK + number of objects and the bytes match what you saw when + you did the directory listing. After uploading the other + two similarly, you get a full object listing: + $ curl –X GET -i -H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae" https://storage.swiftdrive.com/v1/CF_xer7_343/dogs +HTTP/1.1 200 OK X-Container-Object-Count: 3 X-Container-Read: .r:*,.rlistings X-Container-Bytes-Used: 252732 @@ -657,76 +531,39 @@ Date: Mon, 07 Nov 2011 23:00:56 GMT JingleRocky.jpg RockyAndBuster.jpg -SittingBuster.jpg - - - +SittingBuster.jpg
- Creating Static Large Objects + Create static large objects Creation of a static large object is done in several - steps. First we divide the content into pieces and upload - each piece into a segment object. Then we create a - manifest object. In this example, we will place the - segment objects into the "segments" container and the - manifest object into the "images" container. We are not - required to do this, but using a dedicated container for - segment objects is convenient. - Assuming we've already divided our image into three - files, let's upload them. We have removed non-essential + steps. First, divide the content into pieces and upload + each piece into a segment object. Then, create a manifest + object. In this example, you place the segment objects + into the "segments" container and the manifest object into + the "images" container. You are not required to do this, + but using a dedicated container for segment objects is + convenient. + Assuming you have already divided the image into three + files, you can upload them. You have removed non-essential response headers so you can see the important details. - - Uploading first segment - -curl - https://storage.swiftdrive.com/v1/CF_xer7_343/segments/terrier-jpg-one - - - -HTTP/1.1 201 Created + $ curl –X &PUT; -i -H "X-Auth-Token: 12345" -T ./piece1 https://storage.swiftdrive.com/v1/CF_xer7_343/segments/terrier-jpg-one +HTTP/1.1 201 Created Content-Length: 4000000 -Etag: f7365c1419b4f349592c00bd0cfb9b9a - - - - - Uploading second segment - -curl - https://storage.swiftdrive.com/v1/CF_xer7_343/segments/terrier-jpg-two - - - -HTTP/1.1 201 Created +Etag: f7365c1419b4f349592c00bd0cfb9b9a + $ curl –X &PUT; -i -H "X-Auth-Token: 12345" -T ./piece2 https://storage.swiftdrive.com/v1/CF_xer7_343/segments/terrier-jpg-two +HTTP/1.1 201 Created Content-Length: 2000000 -Etag: ad81e97b10e870613aecb5ced52adbaa - - - - - Uploading final segment - -curl - https://storage.swiftdrive.com/v1/CF_xer7_343/segments/terrier-jpg-three - - - -HTTP/1.1 201 Created +Etag: ad81e97b10e870613aecb5ced52adbaa + $ curl –X &PUT; -i -H "X-Auth-Token: 12345" -T ./piece3 https://storage.swiftdrive.com/v1/CF_xer7_343/segments/terrier-jpg-three +HTTP/1.1 201 Created Content-Length: 1000 -Etag: 00b046c9d74c3e8f93b320c5e5fdc2c3 - - - - At this stage we are ready to create the manifest - listing. Notice that the size and ETag are copied from - uploads above. Lets use an editor to create a file called - manifest.json with the following - content: - - Manifest List Example - - +Etag: 00b046c9d74c3e8f93b320c5e5fdc2c3 + At this stage, you can create the manifest listing. + Notice that the size and ETag are copied from the previous + uploads. Create a file called manifest.json + with the following content: + [ { "path": "segments/terrier-jpg-one", @@ -743,56 +580,30 @@ Etag: 00b046c9d74c3e8f93b320c5e5fdc2c3 "size_bytes": 1000 { } - ] - - - + ] The final operation is to upload this content into a manifest object. To indicate that this is a manifest object, you need to specify the ?multipart-manifest=put query string. - - Uploading manifest object - -curl - https://storage.swiftdrive.com/v1/CF_xer7_343/images/terrier-jpg?multipart-manifest=put - - - We can now examine our static large object. Notice that - the size is the total size of all the segments. - - Examining a manifest object - -curl - https://storage.swiftdrive.com/v1/CF_xer7_343/images/terrier-jpg - - - -HTTP/1.1 200 OK + $ curl –X &PUT; -i -H "X-Auth-Token: 12345" -T ./manifest.json https://storage.swiftdrive.com/v1/CF_xer7_343/images/terrier-jpg?multipart-manifest=put + Now, examine the static large object. Notice that the + size is the total size of all the segments. + $ curl –X HEAD -i -H "X-Auth-Token: 12345" https://storage.swiftdrive.com/v1/CF_xer7_343/images/terrier-jpg + HTTP/1.1 200 OK Content-Length: 6001000 Etag: "0c922c37f915efb1c9b97e6328b3e660" - - - +
- Paging Lists of Objects + Page through lists of objects Exactly like listing containers, objects can be listed in pages at a time using markers to denote pages. From the previous example with 3 objects in the container "dogs", the list can be paged with the "limit" query string variable: - - cURL List Objects (first page) - -curl \ - \ - https://storage.swiftdrive.com/v1/CF_xer7_343/dogs?limit=2 - - - -HTTP/1.1 200 OK + $ curl –X GET -i -H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae" https://storage.swiftdrive.com/v1/CF_xer7_343/dogs?limit=2 +HTTP/1.1 200 OK X-Container-Object-Count: 3 X-Container-Read: .r:*,.rlistings X-Container-Bytes-Used: 252732 @@ -803,21 +614,12 @@ X-Trans-Id: tx5e00fa9fa895423198bc814cb0c6162d Date: Tue, 15 Nov 2011 03:53:51 GMT JingleRocky.jpg -RockyAndBuster.jpg - - - +RockyAndBuster.jpg And the second page fetched with: - - cURL List Objects with Paging (later pages) - -curl \ - \ - https://storage.swiftdrive.com/v1/CF_xer7_343/dogs?marker=RockyAndBuster.jpg\&limit=2 - - - -HTTP/1.1 200 OK + $ curl –X GET -i \ + -H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae" \ + https://storage.swiftdrive.com/v1/CF_xer7_343/dogs?marker=RockyAndBuster.jpg\&limit=2 +HTTP/1.1 200 OK X-Container-Object-Count: 3 X-Container-Read: .r:*,.rlistings X-Container-Bytes-Used: 252732 @@ -828,67 +630,44 @@ X-Trans-Id: txe1287a7179dc4dfd98610850a0fff157 Date: Tue, 15 Nov 2011 03:54:21 GMT SittingBuster.jpg - - - +
- Retrieve, Copy, and Delete Objects - Now we'll retrieve an object previously uploaded. First, - we'll remove the local copy: - - Removing Local Copies - - -$ ls -l -total 504 + Get, copy, and delete objects + Now, retrieve an object that you previously uploaded. + First, remove the local copy: + $ ls -l + total 504 -rw-r--r--@ 1 petecj2 staff 44765 Nov 7 14:49 JingleRocky.jpg -rw-r--r--@ 1 petecj2 staff 100864 Nov 7 14:47 RockyAndBuster.jpg --rw-r--r--@ 1 petecj2 staff 107103 Nov 7 14:47 SittingBuster.jpg -$ rm JingleRocky.jpg -$ ls -l -total 416 --rw-r--r--@ 1 petecj2 staff 100864 Nov 7 14:47 RockyAndBuster.jpg --rw-r--r--@ 1 petecj2 staff 107103 Nov 7 14:47 SittingBuster.jpg - - - - Be sure not to use -i switch here since what we want is - the raw data, which we'll then pipe to a file: - - cURL Retrieve an Object - -curl \ - \ - https://storage.swiftdrive.com/v1/CF_xer7_343/dogs/JingleRocky.jpg > JingleRocky.jpg - - - -$ ls -l +-rw-r--r--@ 1 petecj2 staff 107103 Nov 7 14:47 SittingBuster.jpg + $ rm JingleRocky.jpg + $ ls -l + total 416 + -rw-r--r--@ 1 petecj2 staff 100864 Nov 7 14:47 RockyAndBuster.jpg +-rw-r--r--@ 1 petecj2 staff 107103 Nov 7 14:47 SittingBuster.jpg + + Be sure not to use -i switch here because you want the + raw data, which you pipe to a file: + $ curl –X GET \ + -H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae" \ + https://storage.swiftdrive.com/v1/CF_xer7_343/dogs/JingleRocky.jpg > JingleRocky.jpg + $ ls -l total 504 -rw-r--r-- 1 petecj2 staff 44765 Nov 7 15:11 JingleRocky.jpg -rw-r--r--@ 1 petecj2 staff 100864 Nov 7 14:47 RockyAndBuster.jpg --rw-r--r--@ 1 petecj2 staff 107103 Nov 7 14:47 SittingBuster.jpg - - - +-rw-r--r--@ 1 petecj2 staff 107103 Nov 7 14:47 SittingBuster.jpg Next, Object Storage provides a facility to copy objects from one container to another entirely on the server side. - To do this, you do a PUT with the destination container + To do this, you do a &PUT; with the destination container and new object name while passing a special X-Copy-From header and a Content-Length of zero: - - cURL Server-side Copy an Object - -curl \ - \ - \ - \ - https://storage.swiftdrive.com/v1/CF_xer7_343/elaine/JingleRocky.jpg - - - -HTTP/1.1 201 Created + $ curl –X &PUT; -i \ + -H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae" \ + -H "X-Copy-From: /dogs/JingleRocky.jpg" \ + -H "Content-Length: 0" \ + https://storage.swiftdrive.com/v1/CF_xer7_343/elaine/JingleRocky.jpg +HTTP/1.1 201 Created Content-Length: 118 Content-Type: text/html; charset=UTF-8 Etag: f7d40eceffdd9c2ecab226105737b2a6 @@ -905,27 +684,15 @@ Date: Mon, 07 Nov 2011 23:23:54 GMT <h1>201 Created</h1> <br /><br /> - - </body> -</html> - - - +</html> You can then confirm the new location of the object. To do this, you do a GET with the destination container to see the listing of the object: - - cURL Confirming the Server-side Copy an - Object - -curl \ - \ - https://storage.swiftdrive.com/v1/CF_xer7_343/elaine/ - - - -HTTP/1.1 200 OK + $ curl –X GET -i \ + -H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae" \ + https://storage.swiftdrive.com/v1/CF_xer7_343/elaine/ +HTTP/1.1 200 OK X-Container-Object-Count: 1 X-Container-Bytes-Used: 44765 Accept-Ranges: bytes @@ -934,67 +701,44 @@ Content-Type: text/plain; charset=utf-8 X-Trans-Id: tx46986b4a09b34790924fd43842b2b0dd Date: Mon, 07 Nov 2011 23:24:05 GMT -JingleRocky.jpg - - - +JingleRocky.jpg To delete an object from its container, simply use the DELETE verb: - - cURL Delete an Object - -curl \ - \ - https://storage.swiftdrive.com/v1/CF_xer7_343/elaine/JingleRocky.jpg - - - -HTTP/1.1 204 No Content + $ curl –X DELETE -i \ + -H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae" \ + https://storage.swiftdrive.com/v1/CF_xer7_343/elaine/JingleRocky.jpg + HTTP/1.1 204 No Content Content-Length: 0 Content-Type: text/html; charset=UTF-8 X-Trans-Id: txd45f04422b034e6f8447de400b78cbf3 Date: Mon, 07 Nov 2011 23:32:39 GMT - - - + Confirming the deletion by doing a container listing: - - cURL Confirming the Delete an Object - -curl \ - \ - https://storage.swiftdrive.com/v1/CF_xer7_343/elaine/ - - - -HTTP/1.1 204 No Content + + $ curl –X GET -i \ + -H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae" \ + https://storage.swiftdrive.com/v1/CF_xer7_343/elaine/ + HTTP/1.1 204 No Content X-Container-Object-Count: 0 X-Container-Bytes-Used: 0 Accept-Ranges: bytes X-Trans-Id: txc9b43bf4d896405eb9a88ca468bf7b2d Content-Length: 0 Date: Mon, 07 Nov 2011 23:32:41 GMT - - - +
- Object Metadata + Object metadata Objects can have whatever metadata keys/values you choose. Simply POST an HTTP Header to the object in the form of X-Object-Meta-<key>: <value>. Like this: - - cURL Set Object Metadata - -curl \ - \ - \ - https://storage.swiftdrive.com/v1/CF_xer7_343/dogs/JingleRocky.jpg - - - + $ curl –X POST -i \ + -H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae" \ + -H "X-Object-Meta-Breed: Terrier pit bull mix"" \ + https://storage.swiftdrive.com/v1/CF_xer7_343/dogs/JingleRocky.jpg + <html> <head> <title>202 Accepted</title> @@ -1007,20 +751,14 @@ Date: Mon, 07 Nov 2011 23:32:41 GMT </body> </html> - - - + And then read the object metadata with a HEAD on the object path: - - cURL Reading Object Metadata - -curl \ - \ - https://storage.swiftdrive.com/v1/CF_xer7_343/dogs/JingleRocky.jpg - - - + + $ curl –X HEAD -i \ + -H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae" \ + https://storage.swiftdrive.com/v1/CF_xer7_343/dogs/JingleRocky.jpg + HTTP/1.1 200 OK X-Object-Meta-Breed: Terrier pit bull mix Last-Modified: Tue, 08 Nov 2011 01:26:49 GMT @@ -1030,14 +768,11 @@ Date: Mon, 07 Nov 2011 23:32:41 GMT Content-Type: image/jpeg X-Trans-Id: txa8bff9ad7ef844829103c1f9b8c20781 Date: Tue, 08 Nov 2011 01:29:35 GMT - - - +
-
- Pseudo-Hierarchical Folders/Directories - For the last section, we come to the most confusing - concept in Object Storage. In most storage systems, you + +
+ Pseudo-hierarchical folders and directories + + Although you cannot nest directories in OpenStack Object + Storage, you can simulate a hierarchical structure within + a single container by adding forward slash characters + (/) in the object name. To navigate + the pseudo-directory structure, you may use the + delimiter query parameter. See the + following examples for an illustration. + + In the following example, the objects reside in a + container called backups. Within that + container, the objects are organized in a + pseudo-directory called photos. Keep in + mind that the container name is not displayed in the + example, but that it is a part of the object URLs. For + instance, the URL of the picture me.jpg + is + https://storage.swiftdrive.com/v1/CF_xer7_343/backups/photos/me.jpg. + + + + List pseudo-hierarchical folders request: + HTTP + To display a list of all the objects in the storage + container, use &GET; without a delimiter + or prefix. + GET /v1/AccountString/backups + The system returns status code 2xx (between 200 and + 299, inclusive) and the requested list of the + objects. + photos/animals/cats/persian.jpg +photos/animals/cats/siamese.jpg +photos/animals/dogs/corgi.jpg +photos/animals/dogs/poodle.jpg +photos/animals/dogs/terrier.jpg +photos/me.jpg +photos/plants/fern.jpg +photos/plants/rose.jpg + + Use + the delimiter parameter to limit the displayed + results. You can use any character as a delimiter. + However, to use delimiter with + pseudo-directories, use the parameter slash + (/). + GET /v1/AccountString/backups?delimiter=/ + The system returns status code 2xx (between 200 and + 299, inclusive) and the requested matching objects. + Because you use the slash, only the pseudo-directory + photos/ displays. Keep in mind that + the returned values from a slash + delimiter query are not real objects. + They have a content-type of + application/directory and are + in the subdir section of json and + xml results. + photos/ + Use the prefix parameter with the + delimiter parameter to view the + objects inside a pseudo-directory, including further + nested pseudo-directories. + GET /v1/AccountString/backups?prefix=photos/&delimiter=/ + The system returns status code 2xx (between 200 and + 299, inclusive) and the objects and pseudo-directories + within the top level pseudo-directory. + photos/animals/ +photos/me.jpg +photos/plants/ + You can create an unlimited number of nested + pseudo-directories. To navigate through them, use a + longer prefix parameter coupled with the + delimiter parameter. In the following + sample output, there is a pseudo-directory called + dogs within the pseudo-directory + animals. To navigate directly to the + files contained within dogs, enter the + following command: + GET /v1/AccountString/backups?prefix=photos/animals/dogs/&delimiter=/ + The system returns status code 2xx (between 200 and + 299, inclusive) and the objects and pseudo-directories + within the nested pseudo-directory. + photos/animals/dogs/corgi.jpg +photos/animals/dogs/poodle.jpg +photos/animals/dogs/terrier.jpg + +
+ diff --git a/openstack-object-storage-dev/samples/server-post-req.xml b/openstack-object-storage-dev/samples/server-post-req.xml new file mode 100644 index 0000000..5482815 --- /dev/null +++ b/openstack-object-storage-dev/samples/server-post-req.xml @@ -0,0 +1,25 @@ + + + + API Test Server XML + + + + ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBp + dCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5k + IGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVs + c2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4g + QnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRo + ZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlv + dSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vy + c2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6 + b25zLiINCg0KLVJpY2hhcmQgQmFjaA== + + + 0ef47ac7-6797-4e01-8a47-ed26ec3aaa56 + 00000000-0000-0000-0000-000000000000 + 11111111-1111-1111-1111-111111111111 + + diff --git a/openstack-object-storage-dev/samples/server-post-resp.xml b/openstack-object-storage-dev/samples/server-post-resp.xml new file mode 100644 index 0000000..57c3f8e --- /dev/null +++ b/openstack-object-storage-dev/samples/server-post-resp.xml @@ -0,0 +1,15 @@ + + + + + + diff --git a/openstack-object-storage-dev/samples/xml_curl.txt b/openstack-object-storage-dev/samples/xml_curl.txt new file mode 100644 index 0000000..8ac95f0 --- /dev/null +++ b/openstack-object-storage-dev/samples/xml_curl.txt @@ -0,0 +1,7 @@ +curl -i https://dfw.servers.api.rackspacecloud.com/v2/$account/servers.xml \ + -X POST \ + -H "X-Auth-Project-Id: $account" \ + -H "Content-Type: application/xml" \ + -H "Accept: application/xml" \ + -H "X-Auth-Token: $token" \ + -T server_post_req.xml | ppxml \ No newline at end of file diff --git a/openstack-object-storage-dev/section_authentication.xml b/openstack-object-storage-dev/section_authentication.xml new file mode 100644 index 0000000..19ad98c --- /dev/null +++ b/openstack-object-storage-dev/section_authentication.xml @@ -0,0 +1,74 @@ + +
+ Authentication + The owner of an Object Storage account controls access to + that account and its containers and objects. + By default, you have no access to accounts, containers, or + objects. However, an account owner can grant account, + container, and object access to users through access control lists + (ACLs). For more information about ACLs, see . + As the account owner, you can modify the account metadata + and create, modify, and delete containers and objects. + To identity yourself as the owner of an account, include an + authentication token in the X-Auth-Token + header in your API requests. If you omit this header or supply + an incorrect authentication token, your access is + restricted. + The following table describes the authentication services + that you can use: + + + + Authentication service + Description + + + + + + OpenStack Identity Service + (Keystone) + The Object Storage account name is the same + as the tenant ID.For information about the + Identity Service, see . + + + + + Tempauth middleware + Object Storage includes this middleware. + User and account management is performed in + the Object Storage system itself. + For information about Tempauth, see . + + + + + swauth (in GitHub) or other custom + middleware + This custom middleware is modeled on + Tempauth, so usage is typically similar to + Tempauth.Specifically, you use the + X-Auth-Token header to + pass an authentication token to an API + request. + Authentication tokens expire after a time + period that the Identity Service defines.When + a token expires, use of the token causes + requests to fail with a + 401 + Unauthorized response. + To continue, you must obtain a new + token. + + + + +
diff --git a/openstack-object-storage-dev/section_curl_how_curl_works.xml b/openstack-object-storage-dev/section_curl_how_curl_works.xml new file mode 100644 index 0000000..0c2c638 --- /dev/null +++ b/openstack-object-storage-dev/section_curl_how_curl_works.xml @@ -0,0 +1,203 @@ + + + + + + + + +GET'> +PUT'> +POST'> +DELETE'> + + + + + +'> + + + + + +'> +]> +
+ How cURL commands work + cURL is a command-line tool that you can use to interact + with REST interfaces. cURL lets you to + transmit and receive HTTP requests and + responses from the command line or a shell script, which + enables you to work with the API directly. It is available for + Linux distributions, Mac OS X, and Windows. For information + about cURL, see http://curl.haxx.se/. + To use XML requests and responses, see + . + + To run the cURL request examples shown in this guide, copy + each example from the HTML version of this guide directly to + the command line or a script. + + The following command is an example cURL command that + provisions a server with an isolated network: + + $ curl https://dfw.servers.api.rackspacecloud.com/v2/$account/servers \ + -X POST \ + -H "X-Auth-Project-Id: $account" \ + -H "Content-Type: application/json" \ + -H "Accept: application/json" \ + -H "X-Auth-Token: $token" \ + -d '{"server": {"name": "my_server_with_network", "imageRef": "d42f821e-c2d1-4796-9f07-af5ed7912d0e", "flavorRef": "2", "max_count": 1, "min_count": 1, "networks": [{"uuid": "538a112a-34d1-47ff-bf1e-c40639e886e2"}, {"uuid": "00000000-0000-0000-0000-000000000000"}, {"uuid": "11111111-1111-1111-1111-111111111111"}]}}' \ + | python -m json.tool + + The carriage returns in the cURL request examples are + escaped with a backslash (\) character. + The escape character allows continuation of the command + across multiple lines. However, do not include the escape + character in the JSON or XML request body within the cURL + command. + + + The cURL examples in this guide use the following + command-line options: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
cURL Command-Line Options
OptionDescription
+ + + Sends the specified data in a &POST; request + to the HTTP server. Use this option to send a + JSON or XML request body to the server. +
+ + + Specifies an extra HTTP header in the + request. You can specify any number of extra + headers. Precede each header with the + option. + Common headers in Rackspace API requests are: + + Content-Type. + Required for operations with a + request body. + Specifies the format of the + request body. The syntax for the + Content-Type + header is: + Content-Type: application/format + Where + format is + either json or + xml. + + + X-Auth-Project-Id. + Optional. Specifies the project ID, + which can be your account number or + another value. + + + Accept. + Optional. + Specifies the format of the + response body. The syntax for the + Accept header + is: + Accept: application/format + Where + format is + either json or + xml. Default is + json. + + + X-Auth-Token. + Required. Specifies the + authentication token. + + +
+ + + Includes the HTTP header in the output. + +
+ + + Silent or quiet mode. Does not show progress + or error messages. Makes cURL mute. +
+ + + Transfers the specified local file to the + remote URL. +
+ + + Specifies the request method to use when + communicating with the HTTP server. The + specified request is used instead of the + default method, which is &GET;. +
+ + json.tool + For commands that return a response, you can append the + following code to the command to call the json.tool to + pretty-print output: + | python -m json.tool + To use the json.tool, import the json module. For + information about the json.tool, see json — JSON encoder and decoder. + If you run a Python version older than 2.6, import the + simplejson module and use the simplejson.tool. For + information about the simple.json tool, see simplejson — JSON encoder and decoder. + If you do not want to pretty-print JSON output, omit + this code. + + + +
diff --git a/openstack-object-storage-dev/section_curl_xml.xml b/openstack-object-storage-dev/section_curl_xml.xml new file mode 100644 index 0000000..a750c35 --- /dev/null +++ b/openstack-object-storage-dev/section_curl_xml.xml @@ -0,0 +1,119 @@ + + + + + + + + +GET'> +PUT'> +POST'> +DELETE'> + + + + + + + + +'> + + + + + + + + +'> +]> +
+ + XML requests and responses + The following example shows a cURL command that specifies an + XML request body and returns an XML response. The command + creates a server: + + cURL Command Example: XML Request and Response + + + + + + + + + $ + + + The example, , includes the + following changes: + + Append .xml to the endpoint + in the cURL command to return an XML + response. + + + The Content-Type: header + specifies application/xml + instead of application/json. + + + + The Accept: header specifies + application/xml instead of + application/json. + + + If the request requires a request body, specify + it in XML format. In this example, the XML body is + passed in the + server_post_req.xml + file. + + + To pretty-print the XML output, set the ppxml alias, as follows: + $ alias ppxml='python -c "import sys, xml.dom.minidom; print xml.dom.minidom.parseString(sys.stdin.read()).toprettyxml()"' + Then, + append the ppxml alias to your + cURL command. + + + The following example shows the contents of the + server_post_req.xml file: + + + Output: The cURL command + returns information about the new server in XML format, as + shown in the following example: + + + + + + + +
diff --git a/openstack-object-storage-dev/section_gs_curl_how_curl_works.xml b/openstack-object-storage-dev/section_gs_curl_how_curl_works.xml new file mode 100644 index 0000000..5df1706 --- /dev/null +++ b/openstack-object-storage-dev/section_gs_curl_how_curl_works.xml @@ -0,0 +1,203 @@ + + + + + + + + +GET'> +PUT'> +POST'> +DELETE'> + + + + + +'> + + + + + +'> +]> +
+ How cURL Commands Work + cURL is a command-line tool that you can use to interact + with REST interfaces. cURL lets you to + transmit and receive HTTP requests and + responses from the command line or a shell script, which + enables you to work with the API directly. It is available for + Linux distributions, Mac OS X, and Windows. For information + about cURL, see http://curl.haxx.se/. + To use XML requests and responses, see + . + + To run the cURL request examples shown in this guide, copy + each example from the HTML version of this guide directly to + the command line or a script. + + The following command is an example cURL command that + provisions a server with an isolated network: + + $ curl https://dfw.servers.api.rackspacecloud.com/v2/$account/servers \ + -X POST \ + -H "X-Auth-Project-Id: $account" \ + -H "Content-Type: application/json" \ + -H "Accept: application/json" \ + -H "X-Auth-Token: $token" \ + -d '{"server": {"name": "my_server_with_network", "imageRef": "d42f821e-c2d1-4796-9f07-af5ed7912d0e", "flavorRef": "2", "max_count": 1, "min_count": 1, "networks": [{"uuid": "538a112a-34d1-47ff-bf1e-c40639e886e2"}, {"uuid": "00000000-0000-0000-0000-000000000000"}, {"uuid": "11111111-1111-1111-1111-111111111111"}]}}' \ + | python -m json.tool + + The carriage returns in the cURL request examples are + escaped with a backslash (\) character. + The escape character allows continuation of the command + across multiple lines. However, do not include the escape + character in the JSON or XML request body within the cURL + command. + + + The cURL examples in this guide use the following + command-line options: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
cURL Command-Line Options
OptionDescription
+ + + Sends the specified data in a &POST; request + to the HTTP server. Use this option to send a + JSON or XML request body to the server. +
+ + + Specifies an extra HTTP header in the + request. You can specify any number of extra + headers. Precede each header with the + option. + Common headers in Rackspace API requests are: + + Content-Type. + Required for operations with a + request body. + Specifies the format of the + request body. The syntax for the + Content-Type + header is: + Content-Type: application/format + Where + format is + either json or + xml. + + + X-Auth-Project-Id. + Optional. Specifies the project ID, + which can be your account number or + another value. + + + Accept. + Optional. + Specifies the format of the + response body. The syntax for the + Accept header + is: + Accept: application/format + Where + format is + either json or + xml. Default is + json. + + + X-Auth-Token. + Required. Specifies the + authentication token. + + +
+ + + Includes the HTTP header in the output. + +
+ + + Silent or quiet mode. Does not show progress + or error messages. Makes cURL mute. +
+ + + Transfers the specified local file to the + remote URL. +
+ + + Specifies the request method to use when + communicating with the HTTP server. The + specified request is used instead of the + default method, which is &GET;. +
+ + json.tool + For commands that return a response, you can append the + following code to the command to call the json.tool to + pretty-print output: + | python -m json.tool + To use the json.tool, import the json module. For + information about the json.tool, see json — JSON encoder and decoder. + If you run a Python version older than 2.6, import the + simplejson module and use the simplejson.tool. For + information about the simple.json tool, see simplejson — JSON encoder and decoder. + If you do not want to pretty-print JSON output, omit + this code. + + + +
diff --git a/openstack-object-storage-dev/section_gs_curl_xml.xml b/openstack-object-storage-dev/section_gs_curl_xml.xml new file mode 100644 index 0000000..df3fafb --- /dev/null +++ b/openstack-object-storage-dev/section_gs_curl_xml.xml @@ -0,0 +1,122 @@ + + + + + + + + +GET'> +PUT'> +POST'> +DELETE'> + + + + + + + + +'> + + + + + + + + +'> +]> +
+ + XML Requests and Responses + The following example shows a cURL command that specifies an + XML request body and returns an XML response. The command + creates a server: + + cURL Command Example: XML Request and Response + + + + + + + + + $ + + + The example, , includes the + following changes: + + Append .xml to the endpoint + in the cURL command to return an XML + response. + + + The Content-Type: header + specifies application/xml + instead of application/json. + + + + The Accept: header specifies + application/xml instead of + application/json. + + + If the request requires a request body, specify + it in XML format. In this example, the XML body is + passed in the + server_post_req.xml + file. + + + To pretty-print the XML output, set the ppxml alias, as follows: + $ alias ppxml='python -c "import sys, xml.dom.minidom; print xml.dom.minidom.parseString(sys.stdin.read()).toprettyxml()"' + Then, + append the ppxml alias to your + cURL command. + + + + + + The following example shows the contents of the + server_post_req.xml file: + + + Output: The cURL command + returns information about the new server in XML format, as + shown in the following example: + + + + + + + +
diff --git a/openstack-object-storage-dev/section_large_lists_objects.xml b/openstack-object-storage-dev/section_large_lists_objects.xml new file mode 100644 index 0000000..2633108 --- /dev/null +++ b/openstack-object-storage-dev/section_large_lists_objects.xml @@ -0,0 +1,46 @@ + +
+ Control a large list of objects + The system returns a maximum of 10,000 container names for + each request. To get subsequent container names, you must make + another request with the marker parameter. The marker + indicates where the last list left off; the system returns + container names greater than this marker, up to 10,000 names + again. Note that the marker value should be URL-encoded before + you send the HTTP request. + If 10,000 is more than desired, use the limit parameter. If + the number of container names returned equals the specified + limit, or 10,000 if no limit is specified, you can assume + there are more container names. + For example, for a list of five container names, if you + specify a limit of two, two items are returned. You can assume + there are more container names to list, so make another + request with a marker of the last item returned. + + List large number of objects + For example, use a listing of five object names: + gala +grannysmith +honeycrisp +jonagold +reddelicious + Use a limit of two: + + Because we received two items back, we can assume there + are more object names to list. So, we make another request + with a marker of the last item returned: + + Again, two items are returned, and there might be + more. + + You now receive a one-item response, which is fewer than + the limit number of container names. This indicates that + this is the end of the list. By using + end_marker, you can limit the result set + to container names less than the specified value. + + +
diff --git a/openstack-object-storage-dev/section_object-api-create-website.xml b/openstack-object-storage-dev/section_object-api-create-website.xml index c992927..3e9d264 100644 --- a/openstack-object-storage-dev/section_object-api-create-website.xml +++ b/openstack-object-storage-dev/section_object-api-create-website.xml @@ -31,7 +31,7 @@ format="SVG" scale="60"/> xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="Create_Static_Website-dle4000"> - Create Static Website + Create static website You can use your swift account to create a static website. This mode is normally only active for anonymous requests. To use it with authenticated requests, set the header @@ -100,9 +100,10 @@ format="SVG" scale="60"/> You can create and set custom error pages for visitors to your website; currently, only 401 (Unauthorized) and 404 (Not Found) errors are supported. To do this, set the - metadata header, X-Container-Meta-Web-Error. + metadata header, + X-Container-Meta-Web-Error. Error pages are served with the <status> code - prepended to the name of the error page you set. For + pre-pended to the name of the error page you set. For instance, if you set X-Container-Meta-Web-Error to error.html, 401 errors will display the diff --git a/openstack-object-storage-dev/section_object-api-dochistory.xml b/openstack-object-storage-dev/section_object-api-dochistory.xml index a551e92..5a2a6a0 100644 --- a/openstack-object-storage-dev/section_object-api-dochistory.xml +++ b/openstack-object-storage-dev/section_object-api-dochistory.xml @@ -29,7 +29,7 @@ format="SVG" scale="60"/> xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="doc_history"> - Document Change History + Document change history This version of the document replaces and obsoletes all previous versions. The following table describes the latest changes: diff --git a/openstack-object-storage-dev/section_object-api-storage-container-svc.xml b/openstack-object-storage-dev/section_object-api-storage-container-svc.xml index 03d6aae..eccabee 100644 --- a/openstack-object-storage-dev/section_object-api-storage-container-svc.xml +++ b/openstack-object-storage-dev/section_object-api-storage-container-svc.xml @@ -31,8 +31,21 @@ format="SVG" scale="60"/> xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="storage-container-services"> - Storage Container Services - You can perform the following operations for + Storage container services + Lists objects, creates and delete containers, and gets, creates, updates, or deletes container + metadata. + + + + + + + + + + + - Although you cannot nest directories in OpenStack - Object Storage, you can simulate a hierarchical - structure within a single container by adding forward - slash characters (/) in the object - name. To navigate the pseudo-directory structure, you - may use the delimiter query parameter. - See the below examples for an illustration. - - In the example below, the objects reside in a - container called backups. Within that - container, the objects are organized in a - pseudo-directory called photos. Keep - in mind that the container name is not displayed - in the example, but that it is a part of the - object URLs. For instance, the URL of the picture - me.jpg is - https://storage.swiftdrive.com/v1/CF_xer7_343/backups/photos/me.jpg. - - - - List Pseudo-Hierarchical Folders/Directories - Request - To display a list of all the objects in the - storage container, use &GET; without a - delimiter or prefix. - GET /v1/AccountString/backups - The system returns status code 2xx (between 200 - and 299, inclusive) and the requested list of the - objects. - photos/animals/cats/persian.jpg -photos/animals/cats/siamese.jpg -photos/animals/dogs/corgi.jpg -photos/animals/dogs/poodle.jpg -photos/animals/dogs/terrier.jpg -photos/me.jpg -photos/plants/fern.jpg -photos/plants/rose.jpg - - Use - the delimiter parameter to limit the displayed - results. Any character may be used as a delimiter. - However, to use delimiter with - pseudo-directories, use the parameter slash - (/). - GET /v1/AccountString/backups?delimiter=/ - The system returns status code 2xx (between 200 - and 299, inclusive) and the requested matching - objects. Because we use the slash, only the - pseudo-directory photos/ displays. Keep - in mind that the returned values from a slash - delimiter query are not real objects. - They have a content-type of - application/directory and are in - the subdir section of json and xml - results. - photos/ - Use the prefix parameter with the - delimiter parameter to view the - objects inside a pseudo-directory, including - further nested pseudo-directories. - GET /v1/AccountString/backups?prefix=photos/&delimiter=/ - The system returns status code 2xx (between 200 - and 299, inclusive) and the objects and - pseudo-directories within the top level - pseudo-directory. - photos/animals/ -photos/me.jpg -photos/plants/ - You can create an unlimited number of nested - pseudo-directories. To navigate through them, use - a longer prefix parameter coupled - with the delimiter parameter. In the - sample output below, there is a pseudo-directory - called dogs within the - pseudo-directory animals. In order to - navigate directly to the files contained within - dogs, enter the below command. - GET /v1/AccountString/backups?prefix=photos/animals/dogs/&delimiter=/ - The system returns status code 2xx (between 200 - and 299, inclusive) and the objects and - pseudo-directories within the nested pseudo-directory. - - photos/animals/dogs/corgi.jpg -photos/animals/dogs/poodle.jpg -photos/animals/dogs/terrier.jpg - -
+
Create Container @@ -489,11 +337,11 @@ photos/animals/dogs/terrier.jpg View Container Metadata HTTP Response - + --> -
+
diff --git a/openstack-object-storage-dev/section_object-api-storage-object-svc.xml b/openstack-object-storage-dev/section_object-api-storage-object-svc.xml index 9d8b8c9..ef60489 100644 --- a/openstack-object-storage-dev/section_object-api-storage-object-svc.xml +++ b/openstack-object-storage-dev/section_object-api-storage-object-svc.xml @@ -16,7 +16,9 @@ xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="storage-object-services"> - Storage Object Services + Storage object services + Creates, updates, gets details for, and deletes objects. + Gets and updates object metadata. An object represents the data and metadata for the files stored in the system. Through the ReST interface, you can include metadata for an object by adding custom HTTP headers @@ -27,7 +29,19 @@ Then, you can download the segments as a single concatenated object. You can use HTTP requests to work with the segments and manifests directly. - + + + + + + + + + + + +
- Create Large Objects + Create large objects The content of an object cannot be larger than 5GB (by default). However, you can store larger content using two types of objects: @@ -338,7 +351,7 @@ Segment objects do not have any special features and can be created, updated, downloaded and deleted as described elsewhere in this document. However, a manifest object is - special -- when you download, the system concatenates the + special. When you download, the system concatenates the contents of the segment objects and returns this in the response body of the request. This behavior extends to the response headers returned by &GET; and &HEAD; operations. @@ -378,13 +391,13 @@ behavior, there are differences as explained in the following table. - + - - + + @@ -423,8 +436,8 @@ completely new manifest object of the same name with a different manifest list. @@ -480,7 +493,7 @@
Comparison of Static and Dynamic Large - ObjectsComparison of static and dynamic large + objects
FeatureStatic Large ObjectDynamic Large ObjectStatic large objectDynamic large object
You can upload new segment objects or remove - existing segments --- the names must simply - match the <prefix> supplied in + existing segments. The names must simply match + the <prefix> supplied in X-Object-Manifest.
- Dynamic Large Objects + Dynamic large objects Objects that are larger than 5GB must be segmented, prior to upload. You then upload the segments like you would any other object and create a dynamic large @@ -513,13 +526,13 @@ manifest will still be available to download the first set of segments. - Upload Segment of Large Object HTTP - Request + Upload segment of large object request: + HTTP - Upload Segment of Large Object HTTP - Response + Upload segment of large object response: + HTTP s No response body is returned. A status code of 2xx @@ -534,13 +547,13 @@ You can continue uploading segments like this example shows, prior to uploading the manifest. - Upload Next Segment of Large Object HTTP - Request + Upload next segment of large object request: + HTTP - Upload Next Segment of Large Object HTTP - Response + Upload next segment of large object response: + HTTP w Next, upload the manifest you created that indicates @@ -551,11 +564,11 @@ manifest file for subsequent additional segments. - Upload Manifest HTTP Request + Upload manifest request: HTTP - Upload Manifest HTTP Response + Upload manifest response: HTTP The response's Content-Type for a &GET; or &HEAD; on @@ -565,10 +578,11 @@ &PUT; request.
- Static Large Objects - To create a static large object: - - + Static large objects + + + To create a static large object + Divide your content into pieces and create (upload) a segment object to contain each piece. You must record the ETag @@ -579,8 +593,8 @@ ETag request header. This ensures that the upload cannot corrupt your data. - - + + List the name of each segment object along with its size and MD5 checksum in order. Create a manifest object. You indicate that @@ -588,8 +602,8 @@ ?multipart-manifest=put query string at the end of the manifest object name. - - + + The body of the &PUT; request on the manifest object comprises a json list, where each element contains the following: @@ -613,7 +627,7 @@ - Static Large Object Manifest List + Static large object manifest list This is an example containing three segment objects. In this example, you can use several containers and the object names do not have to @@ -622,17 +636,16 @@ The Content-Length request header must - contain the length of the json content -- not the - length of the segment objects. However, after the - &PUT; operation completes, the - Content-Length metadata is set to the - total length of all the object segments. A similar - situation applies to the ETag. If used in - the &PUT; operation, it must contain the MD5 checksum - of the json content. The ETag metadata - value is then set to be the MD5 checksum of the - concatenated ETag values of the object - segments. You may also set the + contain the length of the json content. Not the length + of the segment objects. However, after the &PUT; + operation completes, the Content-Length + metadata is set to the total length of all the object + segments. A similar situation applies to the + ETag. If used in the &PUT; operation, + it must contain the MD5 checksum of the json content. + The ETag metadata value is then set to be + the MD5 checksum of the concatenated ETag + values of the object segments. You may also set the Content-Type request header and custom object metadata. When the &PUT; operation sees the @@ -654,7 +667,7 @@ the manifest you originally used in the &PUT; operation. If you use the &DELETE; operation on a manifest - object, the manifest object is deleted -- the segment + object, the manifest object is deleted. The segment objects are not affected. However, if you add the query parameter ?multipart-manifest=delete, the @@ -669,7 +682,7 @@
- Assigning CORS Headers to Requests + Assign CORS headers to requests CORS is a specification that stands for Cross-Origin Resource Sharing. It defines how browsers and servers communicate across origins using HTTP headers, such as @@ -706,7 +719,7 @@ You can assign these headers to objects only. - Assign CORS Header HTTP Request + Assign CORS header request: HTTP In the example, the origin header is assigned that indicates where the file came from. This allows you to provide security that requests to your Object Storage @@ -717,13 +730,13 @@
- Enabling File Compression with the Content-Encoding - Header - The Content-Encoding header allows a file to be + Enable file compression with the Content-Encoding + header + The Content-Encoding header enables a file to be compressed without losing the identity of the underlying media type of the file, for example, a video. - Content-Encoding Header HTTP Request + Content-Encoding header request: HTTP In the example, the content-encoding header is assigned with an attachment type that indicates how the file should be downloaded: @@ -732,14 +745,14 @@
- Enabling Browser Bypass with the Content-Disposition - Header + Enable browser bypass with the Content-Disposition + header When an object is assigned the Content-Disposition header you can override a browser's default behavior for a file so that the download program saves the file rather than displaying it using default browser settings. - Content-Disposition Header HTTP Request + Content-Disposition header request: HTTP In the example, the content-encoding header is assigned with an attachment type that indicates how the file should be downloaded. @@ -747,8 +760,8 @@
- Expiring Objects with the X-Delete-After and - X-Delete-At Headers + Expire objects with the X-Delete-After and X-Delete-At + headers When an object is assigned either an X-Delete-After or X-Delete-At header when doing a &PUT; or @@ -759,11 +772,10 @@ be outdated at a future time. The X-Delete-At header requires a Unix Epoch timestamp, in integer form; for example: 1348691905 - represents Wed, 26 Sep 2012 20:38:25 GMT. - By - setting the header to a specific Epoch time, you indicate - when you want the object to expire, not be served, and be - deleted completely from the storage system. + represents Wed, 26 Sep 2012 20:38:25 GMT. setting the + header to a specific Epoch time, you indicate when you + want the object to expire, not be served, and be deleted + completely from the storage system. The X-Delete-After header takes an integer number of seconds and calculates the amount of time from now that you want the object to be deleted. The proxy @@ -774,7 +786,7 @@ For existing objects that you want to assign expiration headers to, use the &POST; operation. - Delete Object at HTTP Request + Delete object at request: HTTP In the example, the X-Delete-At header is assigned with a Unix Epoch timestamp in integer form for Mon, 11 Jun 2012 15:38:25 GMT. Use - Delete Object after HTTP Request - In - this example, the X-Delete-After header - is assigned a value in seconds, equivalent to 10 days. - After this time, the object expires. - + Delete object after request: HTTP + In this example, the X-Delete-After + header is assigned a value in seconds, equivalent to + 10 days. After this time, the object expires.
- - Object Versioning + Object versioning Object versioning allows you to store multiple versions of your content to recover from unintended overwrites. It provides an easy method to implement version control which @@ -869,7 +878,7 @@ container, remove its X-Versions-Location metadata by sending an empty key value. - Object Versioning with cURL + Object versioning with cURL Make sure a version-storing container exists, creating it if necessary (this example names it "versions"). Then create a container with the @@ -904,7 +913,7 @@ http://<storage_url>/versions?prefix=008myobject/
-
+
diff --git a/openstack-object-storage-dev/section_object-api-storage_account_svc.xml b/openstack-object-storage-dev/section_object-api-storage_account_svc.xml index 2a93f73..dd1b228 100644 --- a/openstack-object-storage-dev/section_object-api-storage_account_svc.xml +++ b/openstack-object-storage-dev/section_object-api-storage_account_svc.xml @@ -1,325 +1,19 @@ - - - - - - -COPY'> -GET'> -HEAD'> -PUT'> -POST'> -DELETE'> - - - - - -'> - - - - - -'> -]>
- Storage Account Services - Perform the following operations at the account level of the - URL: - - - - Verb - URI - Description - - - - - &GET; - /account - Lists containers. - - - &HEAD; - /account - Gets account metadata. - - - &POST; - /account - Creates or updates account - metadata. - - - &POST; - /account - Deletes account metadata. - - - - - - Optional headers for HEAD and GET - - X-Newest - - Set the optional X-newest header to - True in HEAD and GET requests to have - Object Storage return the latest version of the account. - If set to True, Object Storage queries all - replicas to return the most recent one. Without this header, - Object Storage responds faster after it finds one valid replica. - Because setting this header to True is more - expensive for the back end, use it only when it is - absolutely needed. - - - - - For example, the URL for the requests end with the OpenStack - Object Storage account string, as follows: - - Storage Account Services HTTP Request - - -
- List Containers - &GET; operations against the X-Storage-Url - for an account are performed to list storage containers - sorted by name. The sort order for the name is based on a - binary comparison, a single built-in collating - sequence that compares string data by using the SQLite - memcmp() function, regardless of text encoding. The - following list describes the optional query parameters - that are supported with this request. - - Query Parameters - - limit - - For an integer value - n - , limits the number of - results to - n - values. - - - - marker - - Given a string value - x - , return container names - greater in value than the specified - marker. - - - - end_marker - - Given a string value - x - , return container names less - in value than the specified marker. - - - - format - - Specify either json or - xml to return the respective - serialized response. - - - - At this time, a prefix query parameter is - not supported at the account level. - - List Containers HTTP Request - - - A list of containers is returned in the response body, - one container per line. The HTTP response's status code - will be 2xx (between 200 and 299, inclusive). - - List Containers HTTP Response - - -
- Serialized List Output - If a format=xml or - format=json argument is appended to - the storage account URL, the service serves extended - container information serialized in the chosen format. - The sample responses are formatted for readability. - The following HTTP request asks for a JSON response, - so the response returns an HTTP header and a JSON - response. - - Get Containers Details HTTP and JSON - Request - - - - Get Containers Details HTTP and JSON - Response - - - - The following HTTP request asks for an XML response, - so the response returns an HTTP header and an XML - response. - - Containers Details HTTP and XML Request - - - - Containers Details HTTP and XML - Response - - - -
-
- Controlling a Large List of Containers - The system returns a maximum of 10,000 container - names per request. To retrieve subsequent container - names, another request must be made with the 'marker' - parameter. The marker indicates where the last list - left off; the system returns container names greater - than this marker, up to 10,000 again. Note that the - ‘marker’ value should be URL-encoded prior to sending - the HTTP request. - If 10,000 is larger than desired, use the 'limit' - parameter. - If the number of container names returned equals the - limit given (or 10,000 if no limit is given), you may - assume there are more container names. - - List Large Number of Containers - For example, let's use a listing of five - container names: - apples -bananas -kiwis -oranges -pears - We'll use a limit of two to show how things - work: - - apples -bananas - Because we received two items back, we can - assume there are more container names to list, so - we make another request with a marker of the last - item returned: - - kiwis -oranges - Again, two items are returned; there might be - more: - - pears - With this one-item response we received less - than the limit number of container names, - indicating that this is the end of the - list. - By using end_marker we can limit - the result set to container names less than the - given value. - - apples -bananas -kiwis - -
-
-
- Get Account Metadata - &HEAD; operations against an account are performed to - retrieve the number of containers and the total bytes - stored in OpenStack Object Storage for the account. This - information is returned in two custom headers, - X-Account-Container-Count and - X-Account-Bytes-Used. Since the storage - system is designed to store large amounts of data, care - should be taken when representing the total bytes response - as an integer; when possible, convert it to a 64-bit - unsigned integer if your platform supports that primitive - type. - - Get Account Metadata HTTP Request - - - The HTTP return code will be 2xx (between 200 and 299, - inclusive) if the request succeeds. A 401 (Unauthorized) - will be returned for an invalid account or access - key. - - Get Account Metadata HTTP Response - - -
-
- Create or Update Account Metadata - You can associate custom metadata headers with the - account level URI. These headers must take the format - X-Account-Meta-*. - To create or update an account metadata header use the - &POST; query. Subsequent requests for the same key/value - pair overwrite the previous value. - - Update Account Metadata HTTP Request - - - No response body is returned. A status code of 2xx - (between 200 and 299, inclusive) indicates success. - - Update Account Metadata HTTP Response - - - To confirm your metadata changes, perform a &HEAD; - request on the account. Do not send the metadata in your - &HEAD; request. - - View Account Metadata HTTP Request - - - - View Account Metadata HTTP Response - - -
-
- Delete Account Metadata - To delete a metadata header, send an empty value for - that particular header, such as for the - X-Account-Meta-Book header. - If the tool you use to communicate with Object Storage, - such as older versions of cURL, does not support empty - headers, send the - X-Remove-Account-Meta-name: - arbitrary value header. For - example, X-Remove-Account-Meta-Book: x. The - arbitrary value is - ignored. - - Delete Account Metadata HTTP Request - - No response body is returned. A status code from 200 - to 299 indicates success. - -
+ Storage account services + Lists containers and gets, creates, updates, or deletes + account metadata. You can perform these actions at the account + level of the storage system. + + + + + + + +
diff --git a/openstack-object-storage-dev/section_serialized_list_output.xml b/openstack-object-storage-dev/section_serialized_list_output.xml new file mode 100644 index 0000000..e5d5d4b --- /dev/null +++ b/openstack-object-storage-dev/section_serialized_list_output.xml @@ -0,0 +1,32 @@ + +
+ Serialized list output + If you append the format=xml or + format=json argument to the storage + account URL, the service serves extended container + information serialized in the specified format. The sample + responses are formatted for readability. The following + example HTTP request asks for a JSON response, so the + response returns an HTTP header and a JSON + response. + + Get object details request: HTTP and JSON + + + + Get object details response: HTTP and JSON + + + + + Get object details request: XML + + + + Get object details request: XML + + + +