From ed4f3c4db9ba6b597d12925279c47868998238de 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 Point to WADL files that generate the API Reference page so that the method descriptions and request and response parameters are consistent between these two docs: http://api.openstack.org/api-ref-objectstorage.html (API Reference page for Object Storage) http://docs.openstack.org/api/openstack-object-storage/1.0/ (API Reference (or spec) for Object Storage) Add descriptions of ACLs, FormPOST, TempURLs, StaticWeb, Bulk Upload, Bulk Delete, the OPTIONS operation (though this is implicit in CORS support) Validate all code examples Remove duplication. Co-Author: Donagh McCabe Closes-Bug: #1187119 Closes-Bug: #1214139 Closes-Bug: #1074198 Partial-Bug: #1255770 Change-Id: I94054b046a94260ba8825bdb42439adfcaf9fdce author: diane fleming --- .gitignore | 15 +- .../bk_os-objectstorage-devguide.xml | 59 +- .../ch_object-api-concepts-and-features.xml | 27 + .../ch_object-api-examples.xml | 530 +++++++++ .../ch_object-api-general.xml | 192 --- .../ch_object-api-operations.xml | 59 + .../ch_object-api-storage-services.xml | 82 -- ...ch_object-api-troubleshooting-examples.xml | 993 ---------------- openstack-object-storage-dev/preface.xml | 25 +- .../samples/bulk-delete-request.xml | 11 + .../samples/bulk-delete-response.xml | 11 + .../samples/container-get-details-resp.xml | 14 +- .../samples/get_containers_details_resp.xml | 13 + .../samples/manifest.json | 17 + .../samples/object-delete-at-req.txt | 6 +- .../samples/server-post-req.xml | 25 + .../samples/server-post-resp.xml | 15 + ...ection_object-api-archive-auto-extract.xml | 114 ++ .../section_object-api-authentication.xml | 96 ++ .../section_object-api-browser-bypass.xml | 28 + .../section_object-api-bulk-delete.xml | 162 +++ .../section_object-api-compress-files.xml | 20 + .../section_object-api-container-quotas.xml | 51 + .../section_object-api-container-sync.xml | 104 ++ .../section_object-api-cors-headers.xml | 48 + ...ection_object-api-create-large-objects.xml | 369 ++++++ .../section_object-api-create-website.xml | 121 +- .../section_object-api-curl-commands.xml | 211 ++++ .../section_object-api-discoverability.xml | 66 ++ .../section_object-api-dochistory.xml | 2 +- .../section_object-api-env-vars.xml | 38 + .../section_object-api-expire-objects.xml | 61 + ...st.xml => section_object-api-formpost.xml} | 3 + ... section_object-api-language-bindings.xml} | 0 .../section_object-api-large-lists.xml | 58 + .../section_object-api-overview.xml | 257 ++++ ...section_object-api-pseudo-hier-folders.xml | 94 ++ .../section_object-api-response-formats.xml | 136 +++ ...ction_object-api-storage-container-svc.xml | 526 +------- .../section_object-api-storage-object-svc.xml | 1053 +---------------- ...section_object-api-storage_account_svc.xml | 332 +----- ...url.xml => section_object-api-tempurl.xml} | 6 +- .../section_object-api-versioning.xml | 184 +++ 43 files changed, 2963 insertions(+), 3271 deletions(-) create mode 100644 openstack-object-storage-dev/ch_object-api-concepts-and-features.xml create mode 100644 openstack-object-storage-dev/ch_object-api-examples.xml delete mode 100644 openstack-object-storage-dev/ch_object-api-general.xml create mode 100644 openstack-object-storage-dev/ch_object-api-operations.xml delete mode 100644 openstack-object-storage-dev/ch_object-api-storage-services.xml delete mode 100644 openstack-object-storage-dev/ch_object-api-troubleshooting-examples.xml create mode 100644 openstack-object-storage-dev/samples/bulk-delete-request.xml create mode 100644 openstack-object-storage-dev/samples/bulk-delete-response.xml create mode 100644 openstack-object-storage-dev/samples/get_containers_details_resp.xml create mode 100644 openstack-object-storage-dev/samples/manifest.json 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/section_object-api-archive-auto-extract.xml create mode 100644 openstack-object-storage-dev/section_object-api-authentication.xml create mode 100644 openstack-object-storage-dev/section_object-api-browser-bypass.xml create mode 100644 openstack-object-storage-dev/section_object-api-bulk-delete.xml create mode 100644 openstack-object-storage-dev/section_object-api-compress-files.xml create mode 100644 openstack-object-storage-dev/section_object-api-container-quotas.xml create mode 100644 openstack-object-storage-dev/section_object-api-container-sync.xml create mode 100644 openstack-object-storage-dev/section_object-api-cors-headers.xml create mode 100644 openstack-object-storage-dev/section_object-api-create-large-objects.xml create mode 100644 openstack-object-storage-dev/section_object-api-curl-commands.xml create mode 100644 openstack-object-storage-dev/section_object-api-discoverability.xml create mode 100644 openstack-object-storage-dev/section_object-api-env-vars.xml create mode 100644 openstack-object-storage-dev/section_object-api-expire-objects.xml rename openstack-object-storage-dev/{section_object_api_formpost.xml => section_object-api-formpost.xml} (98%) rename openstack-object-storage-dev/{src/docbkx/object-api-language-bindings.xml => section_object-api-language-bindings.xml} (100%) create mode 100644 openstack-object-storage-dev/section_object-api-large-lists.xml create mode 100644 openstack-object-storage-dev/section_object-api-overview.xml create mode 100644 openstack-object-storage-dev/section_object-api-pseudo-hier-folders.xml create mode 100644 openstack-object-storage-dev/section_object-api-response-formats.xml rename openstack-object-storage-dev/{section_object_api_tempurl.xml => section_object-api-tempurl.xml} (97%) create mode 100644 openstack-object-storage-dev/section_object-api-versioning.xml diff --git a/.gitignore b/.gitignore index 3c98b38..3ba914d 100644 --- a/.gitignore +++ b/.gitignore @@ -1,16 +1,23 @@ -.DS_Store? +.DS_Store +*.xpr +.idea # Build results target/ publish-docs/ -# NetBeans user-specific build actions -nbactions.xml +# Ignore Vagrant Related Files +acceptance_config.yml +boxes/* +/.vagrant # Testenvironment -.tox +.tox/ # Editors *~ .*.swp .bak + +# NetBeans user-specific build actions +nbactions.xml diff --git a/openstack-object-storage-dev/bk_os-objectstorage-devguide.xml b/openstack-object-storage-dev/bk_os-objectstorage-devguide.xml index 479e169..079a920 100644 --- a/openstack-object-storage-dev/bk_os-objectstorage-devguide.xml +++ b/openstack-object-storage-dev/bk_os-objectstorage-devguide.xml @@ -1,30 +1,6 @@ - - - - - - GET'> - HEAD'> - PUT'> - POST'> - DELETE'> - - - - - - '> - - - - - - '> +POST'> ]> + + 2014-02-03 + + + + Rewrote introduction and validated all code + examples. + + + + 2014-01-24 - Added information about form &POST; and - temporary URL middleware. + Added information about form &POST; and temporary + URL middleware. @@ -159,7 +146,7 @@ - Fixed bugs 890435 and 907563 - Add/Update + Fixed bugs 890435 and 907563; Add/Update Container Metadata and Expiring Objects. Changed to Maven 1.0.10. @@ -196,9 +183,9 @@ - Removed references to ACL (Access Control List). - Fixed error in examples referring to X-Auth-Key where - it should be X-Auth-Token. Added section + Removed references to Access Control List (ACL). + Fixed error in examples referring to X-Auth-Key where + it should be X-Auth-Token. Added section numbers. @@ -210,7 +197,7 @@ Expanded authentication information for UK - release. Added "delimiter" as a Query Parameter and + release. Added delimiter as a query parameter and server-side object copy example. @@ -221,7 +208,7 @@ - Initial Release. + Initial release. @@ -230,7 +217,7 @@ - - - + + + diff --git a/openstack-object-storage-dev/ch_object-api-concepts-and-features.xml b/openstack-object-storage-dev/ch_object-api-concepts-and-features.xml new file mode 100644 index 0000000..fbfd4b9 --- /dev/null +++ b/openstack-object-storage-dev/ch_object-api-concepts-and-features.xml @@ -0,0 +1,27 @@ + + + Object Storage API concepts and features + + + + + + + + + + + + + + + + + + + + + diff --git a/openstack-object-storage-dev/ch_object-api-examples.xml b/openstack-object-storage-dev/ch_object-api-examples.xml new file mode 100644 index 0000000..611c05b --- /dev/null +++ b/openstack-object-storage-dev/ch_object-api-examples.xml @@ -0,0 +1,530 @@ + + +GET'> +COPY'> +HEAD'> +PUT'> +POST'> +DELETE'> +]> + + + Object Storage API examples + This section introduces the cURL command language and + demonstrates how to use cURL commands to make Object Storage + API calls. + + For more examples, see Object Storage API v1. + + +
+ Authenticate + The following examples show you how to authenticate with + the Identity Service or Tempauth. +
+ Authenticate with the Identity Service + This section provides an overview of the + authentication process. For request and response + details, see Authenticate in the OpenStack + Identity Service API v2.0 + Reference. + + To authenticate with the Identity + Service + + 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. + + +
+
+ Authenticate with Tempauth + + To 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: + # curl -i https://storage.clouddrive.com/v1/auth \ +-H "X-Auth-User: jdoe" -H "X-Auth-Key: jdoepassword" + + + When authentication succeeds, you receive a + 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: $publicURL +X-Auth-Token: $token +Content-Length: 0 +Content-Type: text/plain; charset=UTF-8 + + +
+
+
+ Account services +
+ Show storage usage + To show how much data you have stored in the system + and the number of containers that you are using, send + a &HEAD; request to the Object Storage service. + Use the -X switch to specify + the &HEAD; method. + Use the -i switch to send the + HTTP response to terminal output. + Include the authentication token in the + X-Auth-Token header. + # curl -i $publicURL -X HEAD -H "X-Auth-Token: $token" + HTTP/1.1 204 No Content +Content-Length: 0 +X-Account-Object-Count: 1 +X-Account-Meta-Book: MobyDick +X-Timestamp: 1389453423.35964 +X-Account-Bytes-Used: 14 +X-Account-Container-Count: 2 +Content-Type: text/plain; charset=utf-8 +Accept-Ranges: bytes +X-Trans-Id: txafb3504870144b8ca40f7-0052d955d4 +Date: Fri, 17 Jan 2014 16:09:56 GMT + The X-Account-Bytes-Used response + header shows the total bytes stored for the entire + account. + The X-Account-Container-Count + response header shows the number of containers in this + storage account. +
+
+ Show account details + This example shows account details, lists + containers, and asks for a JSON response: + # curl -i $publicURL?format=json -X GET -H "X-Auth-Token: $token" + HTTP/1.1 200 OK +Content-Length: 96 +X-Account-Object-Count: 1 +X-Timestamp: 1389453423.35964 +X-Account-Meta-Subject: Literature +X-Account-Bytes-Used: 14 +X-Account-Container-Count: 2 +Content-Type: application/json; charset=utf-8 +Accept-Ranges: bytes +X-Trans-Id: tx274a77a8975c4a66aeb24-0052d95365 +Date: Fri, 17 Jan 2014 15:59:33 GMT + [ + { + "count":0, + "bytes":0, + "name":"janeausten" + }, + { + "count":1, + "bytes":14, + "name":"marktwain" + } +] + This example shows account details, lists + containers, and asks for an XML response: + # curl -i $publicURL?format=xml -X GET -H "X-Auth-Token: $token" + HTTP/1.1 200 OK +Content-Length: 262 +X-Account-Object-Count: 1 +X-Timestamp: 1389453423.35964 +X-Account-Meta-Subject: Literature +X-Account-Bytes-Used: 14 +X-Account-Container-Count: 2 +Content-Type: application/xml; charset=utf-8 +Accept-Ranges: bytes +X-Trans-Id: tx69f60bc9f7634a01988e6-0052d9544b +Date: Fri, 17 Jan 2014 16:03:23 GMT + +
+
+
+ Container services +
+ Container ACLs + The X-Container-Read metadata + header defines the access control list (ACL) + permissions for who can read objects in a container. + Before you set this header, only users with a valid + authentication token for the account can read objects + in that container. + List containers to show the absence of the + X-Container-Read header: + # curl –X GET -i -H "X-Auth-Token: $token" $publicURL/jerry + HTTP/1.1 204 No Content +X-Container-Object-Count: 0 +X-Container-Bytes-Used: 0 +Accept-Ranges: bytes +X-Trans-Id: tx3aa52e951fc64b63bc1fda27902b9bd3 +Content-Length: 0 +Date: Tue, 15 Nov 2011 03:29:22 GMT + Set the X-Container-Read header + to enable read and list access to everyone: + # curl –X &PUT; -i \ +-H "X-Auth-Token: $token" \ +-H "X-Container-Read: .r:*,.rlistings" \ +$publicURL/jerry + HTTP/1.1 202 Accepted +Content-Length: 58 +Content-Type: text/html; charset=UTF-8 +X-Trans-Id: txf2befb56b1854a50995f710f2db48089 +Date: Tue, 15 Nov 2011 03:33:16 GMT + +202 Accepted + +The request is accepted for processing. + For a list of valid + X-Container-Read header values, + see ACLs. + To see the metadata change: + # curl –X GET -i -H "X-Auth-Token: $token" $publicURL/jerry + HTTP/1.1 204 No Content +X-Container-Object-Count: 0 +X-Container-Read: .r:*,.rlistings +X-Container-Bytes-Used: 0 +Accept-Ranges: bytes +X-Trans-Id: txb40eb86d949345f7bc66b01e8b63c3a5 +Content-Length: 0 +Date: Tue, 15 Nov 2011 03:33:36 GMT + After you give everyone read access, anyone can + access any object in the container from a browser. To + do so, a user appends the object name to the + X-Storage-URL header value used + in the session. For example: + $publicURL/jerry/cereal.jpg +
+
+ Create a container + To create a container, issue a &PUT; request. You do + not need to check if a container already exists before + you issue a &PUT; request. The operation creates a + container or updates an existing container, as + appropriate. + Example requests and responses: + + + Create a container with no metadata: + # curl -i $publicURL/steven -X PUT -H "Content-Length: 0" -H "X-Auth-Token: $token" + HTTP/1.1 201 Created +Content-Length: 0 +Content-Type: text/html; charset=UTF-8 +X-Trans-Id: tx7f6b7fa09bc2443a94df0-0052d58b56 +Date: Tue, 14 Jan 2014 19:09:10 GMT + + + Create a container with metadata: + # curl -i $publicURL/marktwain -X PUT -H "X-Auth-Token: $token" -H "X-Container-Meta-Book: TomSawyer" + HTTP/1.1 201 Created +Content-Length: 0 +Content-Type: text/html; charset=UTF-8 +X-Trans-Id: tx06021f10fc8642b2901e7-0052d58f37 +Date: Tue, 14 Jan 2014 19:25:43 GMT + + + For a complete description of HTTP 1.1 header + definitions, see Header Field Definitions. +
+
+ Page through large lists of containers + + You can also use this technique to page through + large lists of objects. + + For more information about how to page through large + lists of containers and objects, see . + For a list of five container names, if you specify a + limit of two, two items are + returned. You can assume there are more names to list, + so make another request with a + marker of the last item + returned. + For example, assume the following list of container + names: + apples +bananas +kiwis +oranges +pears + + To page through a large list of + containers + + Use a limit of + two: + GET $publicURL?limit=2 +Host: storage.swiftdrive.com +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: + GET $publicURL?limit=2&marker=bananas +Host: storage.swiftdrive.com +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: + GET $publicURL?limit=2&marker=oranges +Host: storage.swiftdrive.com +X-Auth-Token: $token + + pears + You now 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: + GET $publicURL/?end_marker=oranges +Host: storage.swiftdrive.com +X-Auth-Token: $token + apples +bananas +kiwis + + +
+
+ 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 because you want + the raw data, which you pipe to a file: + # curl –X GET -H "X-Auth-Token: $token" $publicURL/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 + 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 and new object name while + passing a special X-Copy-From header and a + Content-Length of zero: + # curl –X PUT -i -H "X-Auth-Token: $token" -H "X-Copy-From: /dogs/JingleRocky.jpg" -H "Content-Length: 0" $publicURL/elaine/JingleRocky.jpg + HTTP/1.1 201 Created +Content-Length: 118 +Content-Type: text/html; charset=UTF-8 +Etag: f7d40eceffdd9c2ecab226105737b2a6 +X-Copied-From: dogs/JingleRocky.jpg +Last-Modified: Mon, 07 Nov 2011 23:23:53 GMT +X-Trans-Id: tx244cd14df1b94d8c91ec5dcf8c5f9da4 +Date: Mon, 07 Nov 2011 23:23:54 GMT + +<html><head><title>201 Created</title></head><body><h1>201 Created</h1><br /><br /></body></html> + You can then confirm the new location of the object. + Issue a &GET; request with the destination + container: + # curl –X GET -i -H "X-Auth-Token: $token" $publicURL/elaine/ + HTTP/1.1 200 OK +X-Container-Object-Count: 1 +X-Container-Bytes-Used: 44765 +Accept-Ranges: bytes +Content-Length: 16 +Content-Type: text/plain; charset=utf-8 +X-Trans-Id: tx46986b4a09b34790924fd43842b2b0dd +Date: Mon, 07 Nov 2011 23:24:05 GMT + +JingleRocky.jpg + To delete an object from its container: + # curl –X DELETE -i -H "X-Auth-Token: $token" $publicURL/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 + List containers to confirm the deletion: + # curl –X GET -i -H "X-Auth-Token: $token" $publicURL/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 +
+
+ 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 –X HEAD -i \ + -H "X-Auth-Token: $token" \ + $publicURL/dogs +HTTP/1.1 204 No Content +X-Container-Object-Count: 0 +X-Container-Bytes-Used: 0 +Accept-Ranges: bytes +X-Trans-Id: tx3dd984f9482341dd97546e9d49d65e90 +Content-Length: 0 +Date: Mon, 07 Nov 2011 20:39:41 GMT + To delete a container: + # curl –X DELETE -i \ + -H "X-Auth-Token: $token" \ + $publicURL/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 –X GET -i \ + -H "X-Auth-Token: $token" \ + $publicURL +HTTP/1.1 200 OK +X-Account-Object-Count: 0 +X-Account-Bytes-Used: 0 +X-Account-Container-Count: 4 +Accept-Ranges: bytes +Content-Length: 24 +Content-Type: text/plain; charset=utf-8 +X-Trans-Id: tx2475741852b849ce9403e382fe3f8015 +Date: Mon, 07 Nov 2011 20:43:08 GMT + +cosmo +dogs +elaine +jerry +
+
+
+ Object services +
+ Create static large objects + To create a static large object: + + + Split the content into pieces. + + + Upload each piece into a segment + object. + + + Create a manifest object. + + + This example places the segment objects into the + segments container and the + manifest object into the images + container. Using a dedicated container for segment + objects is convenient. + Assuming you have already split the image into three + files, you can upload them. You have removed + non-essential response headers so you can see the + important details. + # curl –X &PUT; -i -H "X-Auth-Token: $token" -T ./piece1 $publicURL/segments/terrier-jpg-one + HTTP/1.1 201 Created +Content-Length: 4000000 +Etag: f7365c1419b4f349592c00bd0cfb9b9a + # curl –X &PUT; -i -H "X-Auth-Token: $token" -T ./piece2 $publicURL/segments/terrier-jpg-two + HTTP/1.1 201 Created +Content-Length: 2000000 +Etag: ad81e97b10e870613aecb5ced52adbaa + # curl –X &PUT; -i -H "X-Auth-Token: $token" -T ./piece3 $publicURL/segments/terrier-jpg-three + HTTP/1.1 201 Created +Content-Length: 1000 +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: + + The final operation is to upload this content into a + manifest object. To indicate that this is a manifest + object, you must specify the + multipart-manifest=put + query parameter. + # curl –X &PUT; -i -H "X-Auth-Token: $token" -T ./manifest.json $publicURL/images/terrier-jpg?multipart-manifest=put + Examine the static large object. Notice that its + size is the total size of all the segments: + # curl –X HEAD -i -H "X-Auth-Token: $token" $publicURL/images/terrier-jpg + HTTP/1.1 200 OK +Content-Length: 6001000 +Etag: "0c922c37f915efb1c9b97e6328b3e660" +
+
+ diff --git a/openstack-object-storage-dev/ch_object-api-general.xml b/openstack-object-storage-dev/ch_object-api-general.xml deleted file mode 100644 index 9a68c24..0000000 --- a/openstack-object-storage-dev/ch_object-api-general.xml +++ /dev/null @@ -1,192 +0,0 @@ - - - - - - - -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. - -
- - - diff --git a/openstack-object-storage-dev/ch_object-api-operations.xml b/openstack-object-storage-dev/ch_object-api-operations.xml new file mode 100644 index 0000000..0493994 --- /dev/null +++ b/openstack-object-storage-dev/ch_object-api-operations.xml @@ -0,0 +1,59 @@ + + + Object Storage API operations + Manage the accounts, containers, and objects in the Object + Storage system. + For a complete description of HTTP 1.1 header definitions, see + Header Field Definitions. +
+ Accounts + List containers for a specified account. Create, update, + and delete account metadata. Show account metadata. + + + + + + + +
+
+ Containers + List objects in a specified container. Create, show + details for, and delete containers. Create, update, show, + and delete container metadata. + + + + + + + + + +
+
+ Objects + Create, replace, show details for, and delete objects. + Copy objects with another object with a new or different name. + Update object metadata. + + + + + + + + + + +
+ diff --git a/openstack-object-storage-dev/ch_object-api-storage-services.xml b/openstack-object-storage-dev/ch_object-api-storage-services.xml deleted file mode 100644 index 07e83a8..0000000 --- a/openstack-object-storage-dev/ch_object-api-storage-services.xml +++ /dev/null @@ -1,82 +0,0 @@ - - - - - - - - -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. - - - - - - - diff --git a/openstack-object-storage-dev/ch_object-api-troubleshooting-examples.xml b/openstack-object-storage-dev/ch_object-api-troubleshooting-examples.xml deleted file mode 100644 index d33f112..0000000 --- a/openstack-object-storage-dev/ch_object-api-troubleshooting-examples.xml +++ /dev/null @@ -1,993 +0,0 @@ - - - - - - - - -GET'> -HEAD'> -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 - cURL is a command-line tool which is available on most - UNIX®-like environments and Mac OS X® and can be - downloaded for Windows®. For more information on cURL, - visit http://curl.haxx.se/. - cURL allows you to transmit and receive HTTP requests - and responses from the command-line or from within a shell - script. This makes it possible to work with the ReST API - directly without using one of the client APIs. - The following cURL command-line options will be - used - - cURL Command-Line Options - - - - Specify the HTTP method to request (&HEAD;, - &GET;, etc.) - - - - - - Dump HTTP response headers to stdout. - - - - - - Specify an HTTP header in the - request. - - - -
-
- 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 -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. -
-
- Determining 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 - - 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 - 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 - - 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 - authentication operation, and force the GET verb with the - -X switch. What you get back tells you there aren't any - 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 -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 -X-Account-Object-Count: 0 -X-Account-Bytes-Used: 0 -X-Account-Container-Count: 1 -Accept-Ranges: bytes -Content-Length: 7 -Content-Type: text/plain; charset=utf-8 -X-Trans-Id: txaedd6b080626453399c9f5febbddb73b -Date: Mon, 07 Nov 2011 17:44:23 GMT - -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 - 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 -X-Account-Object-Count: 0 -X-Account-Bytes-Used: 0 -X-Account-Container-Count: 5 -Accept-Ranges: bytes -Content-Length: 31 -Content-Type: text/plain; charset=utf-8 -X-Trans-Id: txb28795cc25b04f0dbce408dfa5a3cfc9 -Date: Mon, 07 Nov 2011 19:03:06 GMT - -cosmo -dogs -elaine -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 -X-Account-Object-Count: 0 -X-Account-Bytes-Used: 0 -X-Account-Container-Count: 5 -Accept-Ranges: bytes -Content-Length: 11 -Content-Type: text/plain; charset=utf-8 -X-Trans-Id: tx940ee02c1a65451e96a2a2532e3a7ce7 -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 -X-Account-Object-Count: 0 -X-Account-Bytes-Used: 0 -X-Account-Container-Count: 5 -Accept-Ranges: bytes -Content-Length: 14 -Content-Type: text/plain; charset=utf-8 -X-Trans-Id: tx2a69f7ec38c34078a185c5875a4c0e34 -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 - the next page of items that appear after the - marker. -
-
- 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 -X-Account-Object-Count: 0 -X-Account-Bytes-Used: 0 -X-Account-Container-Count: 5 -Accept-Ranges: bytes -Content-Length: 187 -Content-Type: application/json; charset=utf-8 -X-Trans-Id: txd408573a51d2423c848cba191fbede9b -Date: Mon, 07 Nov 2011 19:17:33 GMT - -[{"name":"cosmo", "count":0,"bytes":0}, -{"name":"dogs","count":0,"bytes":0}, -{"name":"elaine","count":0,"bytes":0}, -{"name":"george","count":0,"bytes":0}, -{"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 -X-Account-Object-Count: 0 -X-Account-Bytes-Used: 0 -X-Account-Container-Count: 5 -Accept-Ranges: bytes -Content-Length: 479 -Content-Type: application/xml; charset=utf-8 -X-Trans-Id: tx5e5685a15d0b406799b6a425b1150e4c -Date: Mon, 07 Nov 2011 19:17:38 GMT - -<?xml version="1.0" encoding="UTF-8"?> -<account name="AUTH_a23f73d2-abfb-4656-af94-32ddec35dab8"> -<container><name>cosmo</name><count>0</count><bytes>0</bytes></container> -<container><name>dogs</name><count>0</count><bytes>0</bytes></container> -<container><name>elaine</name><count>0</count><bytes>0</bytes></container> -<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 - use one of the formats, you get more information about the - containers. That's the per-container metadata, which is - covered in the next section. -
- -
- Container Metadata and Deleting 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 -X-Container-Object-Count: 0 -X-Container-Bytes-Used: 0 -Accept-Ranges: bytes -X-Trans-Id: tx3dd984f9482341dd97546e9d49d65e90 -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 -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 -X-Account-Object-Count: 0 -X-Account-Bytes-Used: 0 -X-Account-Container-Count: 4 -Accept-Ranges: bytes -Content-Length: 24 -Content-Type: text/plain; charset=utf-8 -X-Trans-Id: tx2475741852b849ce9403e382fe3f8015 -Date: Mon, 07 Nov 2011 20:43:08 GMT - -cosmo -dogs -elaine -jerry - -
-
- 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 - set, the ACL logic default to only be accessible to - someone with a valid X-Auth-Token for the account in - 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 -X-Container-Object-Count: 0 -X-Container-Bytes-Used: 0 -Accept-Ranges: bytes -X-Trans-Id: tx3aa52e951fc64b63bc1fda27902b9bd3 -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 -Content-Length: 58 -Content-Type: text/html; charset=UTF-8 -X-Trans-Id: txf2befb56b1854a50995f710f2db48089 -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 -X-Container-Object-Count: 0 -X-Container-Read: .r:*,.rlistings -X-Container-Bytes-Used: 0 -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 - throughout the session and append the object name. For - example: - https://storage.swiftdrive.com/v1/CF_xer7_343/jerry/cereal.jpg - would be the URL of an object named "cereal.jpg" in the - container "jerry" that has been made publicly accessible - using this method. -
-
- Creating 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 --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 -Content-Length: 118 -Content-Type: text/html; charset=UTF-8 -Etag: f7d40eceffdd9c2ecab226105737b2a6 -Last-Modified: Mon, 07 Nov 2011 22:51:29 GMT -X-Trans-Id: txd131cc897c78403daf5fad010d4d7152 -Date: Mon, 07 Nov 2011 22:51:30 GMT - -<html> - <head> - <title>201 Created</title> - </head> - <body> - <h1>201 Created</h1> - <br /><br /> - - - - </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 - again: - - cURL List Container Showing Newly Uploaded - Object - $ curl \ - \ - 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 -Accept-Ranges: bytes -Content-Length: 16 -Content-Type: text/plain; charset=utf-8 -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 -X-Container-Object-Count: 3 -X-Container-Read: .r:*,.rlistings -X-Container-Bytes-Used: 252732 -Accept-Ranges: bytes -Content-Length: 53 -Content-Type: text/plain; charset=utf-8 -X-Trans-Id: txae17dfa78da64117aaf07585a1b02115 -Date: Mon, 07 Nov 2011 23:00:56 GMT - -JingleRocky.jpg -RockyAndBuster.jpg -SittingBuster.jpg - -
-
- Creating 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 - 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 -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 -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 -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 - [ - { - "path": "segments/terrier-jpg-one", - "etag": "f7365c1419b4f349592c00bd0cfb9b9a", - "size_bytes": 4000000 - }, - { - "path": "segments/terrier-jpg-two", - "etag": "ad81e97b10e870613aecb5ced52adbaa", - "size_bytes": 2000000 - }, - "path": "segments/terrier-jpg-three", - "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 -Content-Length: 6001000 -Etag: "0c922c37f915efb1c9b97e6328b3e660" - -
-
- Paging 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 -X-Container-Object-Count: 3 -X-Container-Read: .r:*,.rlistings -X-Container-Bytes-Used: 252732 -Accept-Ranges: bytes -Content-Length: 35 -Content-Type: text/plain; charset=utf-8 -X-Trans-Id: tx5e00fa9fa895423198bc814cb0c6162d -Date: Tue, 15 Nov 2011 03:53:51 GMT - -JingleRocky.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 -X-Container-Object-Count: 3 -X-Container-Read: .r:*,.rlistings -X-Container-Bytes-Used: 252732 -Accept-Ranges: bytes -Content-Length: 18 -Content-Type: text/plain; charset=utf-8 -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 --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 - -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 - - 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 - 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 -Content-Length: 118 -Content-Type: text/html; charset=UTF-8 -Etag: f7d40eceffdd9c2ecab226105737b2a6 -X-Copied-From: dogs/JingleRocky.jpg -Last-Modified: Mon, 07 Nov 2011 23:23:53 GMT -X-Trans-Id: tx244cd14df1b94d8c91ec5dcf8c5f9da4 -Date: Mon, 07 Nov 2011 23:23:54 GMT - -<html> - <head> - <title>201 Created</title> - </head> - <body> - <h1>201 Created</h1> - <br /><br /> - - - - </body> -</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 -X-Container-Object-Count: 1 -X-Container-Bytes-Used: 44765 -Accept-Ranges: bytes -Content-Length: 16 -Content-Type: text/plain; charset=utf-8 -X-Trans-Id: tx46986b4a09b34790924fd43842b2b0dd -Date: Mon, 07 Nov 2011 23:24:05 GMT - -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 -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 -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 - 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 - <html> - <head> - <title>202 Accepted</title> - </head> - <body> - <h1>202 Accepted</h1> - The request is accepted for processing.<br /><br /> - - - - </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 - HTTP/1.1 200 OK - X-Object-Meta-Breed: Terrier pit bull mix - Last-Modified: Tue, 08 Nov 2011 01:26:49 GMT - Etag: f7d40eceffdd9c2ecab226105737b2a6 - Accept-Ranges: bytes - Content-Length: 44765 - 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 - have the ability to create custom hierarchies of files so - that you can better organize them. On its surface, Object - Storage only gives you one level of hierarchy in the form - of containers. However, it turns out that you can get - creative with naming your objects to give yourself the - same effect as having hierarchical containers. - Let's start with a fresh container without any objects - in it: - - cURL Create New Container for Folders - $ curl \ - \ - https://storage.swiftdrive.com/v1/CF_xer7_343/photos - HTTP/1.1 201 Created -Content-Length: 18 -Content-Type: text/html; charset=UTF-8 -X-Trans-Id: txc78254a41b374b6ea10590d90874f769 -Date: Wed, 16 Nov 2011 00:06:22 GMT - -201 Created - - Now list the new container: - - cURL Listing the New Container - $ curl \ - \ - https://storage.swiftdrive.com/v1/CF_xer7_343/photos - HTTP/1.1 204 No Content -X-Container-Object-Count: 0 -X-Container-Bytes-Used: 0 -Accept-Ranges: bytes -X-Trans-Id: tx49112200f7934c2bab1de3ae103c368e -Content-Length: 0 -Date: Wed, 16 Nov 2011 00:06:26 GMT - - Next, add an object but prefix the name with the - hierarchy desired: - - cURL Upload an Object with a Prefix - $ curl \ - \ - \ - https://storage.swiftdrive.com/v1/CF_xer7_343/photos/terriers/JingleRocky.jpg - HTTP/1.1 201 Created -Content-Length: 118 -Content-Type: text/html; charset=UTF-8 -Etag: f7d40eceffdd9c2ecab226105737b2a6 -Last-Modified: Wed, 16 Nov 2011 00:09:18 GMT -X-Trans-Id: txe34fdf2704f044e3a7102256386b1cb7 -Date: Wed, 16 Nov 2011 00:09:19 GMT - -<html> - <head> - <title>201 Created</title> - </head> - <body> - <h1>201 Created</h1> - <br /><br /> - - - - </body> -</html> - - Do it again with a different object and prefix: - - cURL Upload a Different Object with a Different - Prefix - $ curl \ - \ - \ - https://storage.swiftdrive.com/v1/CF_xer7_343/photos/chihuahuas/SittingBuster.jpg - HTTP/1.1 201 Created -Content-Length: 118 -Content-Type: text/html; charset=UTF-8 -Etag: e692e744c7180ee368166a24f1a2fa9b -Last-Modified: Wed, 16 Nov 2011 00:52:25 GMT -X-Trans-Id: txe229d03af5ea4d2ea1071def213c3f02 -Date: Wed, 16 Nov 2011 00:52:25 GMT - -<html> - <head> - <title>201 Created</title> - </head> - <body> - <h1>201 Created</h1> - <br /><br /> - - - - </body> -</html> - - Now list the container, revealing the prefixes: - - cURL Listing a Container with Object Prefix - $ curl \ - \ - https://storage.swiftdrive.com/v1/CF_xer7_343/photos - HTTP/1.1 200 OK -X-Container-Object-Count: 2 -X-Container-Bytes-Used: 151868 -Accept-Ranges: bytes -Content-Length: 54 -Content-Type: text/plain; charset=utf-8 -X-Trans-Id: tx8544a17e8b1e4da693145fb5f2e6db43 -Date: Wed, 16 Nov 2011 00:53:43 GMT - -chihuahuas/SittingBuster.jpg -terriers/JingleRocky.jpg - - If you want to perform hierarchical listings, with the - prefixes in place, you can use the "path" query string - variable: - - cURL Listing a Container with a Path - $ curl \ - \ - https://storage.swiftdrive.com/v1/CF_xer7_343/photos?path=terriers - HTTP/1.1 200 OK -X-Container-Object-Count: 2 -X-Container-Bytes-Used: 151868 -Accept-Ranges: bytes -Content-Length: 25 -Content-Type: text/plain; charset=utf-8 -X-Trans-Id: tx3f1b9575d4de4a7d97ba3f9ad81923cc -Date: Wed, 16 Nov 2011 00:55:12 GMT - -terriers/JingleRocky.jpg - - If you wanted to see what prefixes were in place, you - can use the "delimiter" query string variable to - distinguish prefix paths from object names: - - cURL Listing a Container with a Delimiter - $ curl \ - \ - https://storage.swiftdrive.com/v1/CF_xer7_343/photos?delimiter=/ - HTTP/1.1 200 OK -X-Container-Object-Count: 2 -X-Container-Bytes-Used: 151868 -Accept-Ranges: bytes -Content-Length: 22 -Content-Type: text/plain; charset=utf-8 -X-Trans-Id: tx7222a3dd73fe44b888db4e58cc647d1e -Date: Wed, 16 Nov 2011 00:57:40 GMT - -chihuahuas/ -terriers/ - - Using these in combination allows you to discover - directories within a particular path and then further - drill down based on the results. -
- - diff --git a/openstack-object-storage-dev/preface.xml b/openstack-object-storage-dev/preface.xml index caa2cd7..70c9228 100644 --- a/openstack-object-storage-dev/preface.xml +++ b/openstack-object-storage-dev/preface.xml @@ -4,7 +4,7 @@ - + GET'> PUT'> @@ -35,15 +35,14 @@ format="SVG" scale="60"/> storage system is designed to provide a safe, secure, automatically re-sizing and network-accessible way to store data. You can store an unlimited quantity of files and each - file can be as large as 5 GBs, plus with large object + file can be as large as 5 GB, plus with large object creation, you can upload and store objects of virtually any size. - OpenStack Object Storage allows users to store and retrieve - files and content through a simple Web Service interface - (ReST: Representational State Transfer). There are also - language-specific APIs that utilize the ReSTful API but make - it much easier for developers to integrate into their - applications. + OpenStack Object Storage enables you to store and get files + and content through the Representational State Transfer (REST) + interface. There are also language-specific APIs that utilize + the RESTful API but make it much easier for developers to + integrate into their applications. For more details on the OpenStack Object Storage service, please refer to 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 + Storage API. It fully documents the REST application programming interface (API) that allows developers to interact with the storage components of the OpenStack Object Storage system. To use the information provided @@ -66,7 +65,7 @@ format="SVG" scale="60"/> be familiar with: - ReSTful web services + RESTful web services HTTP/1.1 @@ -74,12 +73,12 @@ format="SVG" scale="60"/> You can also find language-specific APIs in several popular programming languages such as C#/.NET, Java, PHP, - Python, and Ruby. These APIs utilize the ReST API and are + Python, and Ruby. These APIs utilize the REST API and are provided to help developers rapidly integrate OpenStack Object Storage support into their applications without - needing to write at the ReST interface. Each API includes + needing to write at the REST interface. Each API includes its own documentation in its native format. For example, the Java API includes Javadoc documentation. - + diff --git a/openstack-object-storage-dev/samples/bulk-delete-request.xml b/openstack-object-storage-dev/samples/bulk-delete-request.xml new file mode 100644 index 0000000..2c4362f --- /dev/null +++ b/openstack-object-storage-dev/samples/bulk-delete-request.xml @@ -0,0 +1,11 @@ + + + 2 + 4 + + + /v1/12345678912345/mycontainer + 409 Conflict + + + diff --git a/openstack-object-storage-dev/samples/bulk-delete-response.xml b/openstack-object-storage-dev/samples/bulk-delete-response.xml new file mode 100644 index 0000000..2c4362f --- /dev/null +++ b/openstack-object-storage-dev/samples/bulk-delete-response.xml @@ -0,0 +1,11 @@ + + + 2 + 4 + + + /v1/12345678912345/mycontainer + 409 Conflict + + + diff --git a/openstack-object-storage-dev/samples/container-get-details-resp.xml b/openstack-object-storage-dev/samples/container-get-details-resp.xml index 86464d6..d8f51cf 100644 --- a/openstack-object-storage-dev/samples/container-get-details-resp.xml +++ b/openstack-object-storage-dev/samples/container-get-details-resp.xml @@ -1,13 +1,13 @@ - + - test_container_1 - 2 - 78 + janeausten + 0 + 0 - test_container_2 + marktwain 1 - 17 + 14 - \ No newline at end of file + diff --git a/openstack-object-storage-dev/samples/get_containers_details_resp.xml b/openstack-object-storage-dev/samples/get_containers_details_resp.xml new file mode 100644 index 0000000..6ab06cb --- /dev/null +++ b/openstack-object-storage-dev/samples/get_containers_details_resp.xml @@ -0,0 +1,13 @@ + + + + test_container_1 + 2 + 78 + + + test_container_2 + 1 + 17 + + diff --git a/openstack-object-storage-dev/samples/manifest.json b/openstack-object-storage-dev/samples/manifest.json new file mode 100644 index 0000000..05694ea --- /dev/null +++ b/openstack-object-storage-dev/samples/manifest.json @@ -0,0 +1,17 @@ +[ + { + "path":"segments/terrier-jpg-one", + "etag":"f7365c1419b4f349592c00bd0cfb9b9a", + "size_bytes":4000000 + }, + { + "path":"segments/terrier-jpg-two", + "etag":"ad81e97b10e870613aecb5ced52adbaa", + "size_bytes":2000000 + }, + { + "path":"segments/terrier-jpg-three", + "etag":"00b046c9d74c3e8f93b320c5e5fdc2c3", + "size_bytes":1000 + } +] \ No newline at end of file diff --git a/openstack-object-storage-dev/samples/object-delete-at-req.txt b/openstack-object-storage-dev/samples/object-delete-at-req.txt index 5237d1a..d1ef754 100644 --- a/openstack-object-storage-dev/samples/object-delete-at-req.txt +++ b/openstack-object-storage-dev/samples/object-delete-at-req.txt @@ -1,5 +1 @@ -PUT //// HTTP/1.1 -Host: storage.clouddrive.com -X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb -Content-Type: image/jpeg -X-Delete-At: 1339429105 \ No newline at end of file +curl -i $publicURL/marktwain/goodbye -X PUT -H "X-Auth-Token: $token" -H "X-Delete-At: 1390581073" -H "Content-Length: 14" -H "Content-Type: application/octet-stream" \ No newline at end of file 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/section_object-api-archive-auto-extract.xml b/openstack-object-storage-dev/section_object-api-archive-auto-extract.xml new file mode 100644 index 0000000..702ec12 --- /dev/null +++ b/openstack-object-storage-dev/section_object-api-archive-auto-extract.xml @@ -0,0 +1,114 @@ + + +PUT'> +]> +
+ Auto-extract archive files + To discover whether your Object Storage system supports + this feature, see . Alternatively, check with your service provider. + Use the auto-extract archive feature to upload a tar(1) + archive file. + The Object Storage system extracts files from the archive + file and creates an object. +
+ Auto-extract archive PUT request + To upload an archive file, you make a &PUT; request. Add + the + extract-archive=format + query parameter to indicate that you are uploading a + tar(1) archive file instead of normal content. + Valid values for the format + variable are tar, + tar.gz, or + tar.bz2. + The path you specify in the &PUT; request is a prefix + for the resulting object names. + For example, if the first object in the tar(1) archive + is /home/file1.txt and you specify + the + /v1/12345678912345/mybackup/castor/ + path, the operation creates the + castor/home/file1.txt object in + the mybackup container in the + 12345678912345 account. + In the &PUT; request, you can specify the path + for: + + + An account + + + Optionally, a specific container + + + Optionally, a specific object prefix + + +
+
+ Create an archive for auto-extract + You must use the tar(1) utility to create the tar(1) + archive file. + You can upload regular files but you cannot upload other + items, such as empty directories, symbolic links, and so + on. + You must UTF-8-encode the member names. + The archive auto-extract feature supports these + formats: + + + The POSIX.1-1988 Ustar format. + + + The GNU tar format. Includes the long name, long + link, and sparse extensions. + + + The POSIX.1-2001 pax format. + Use gzip(1) or bzip2(1) to compress the + archive. + Use the extract-archive + query parameter to specify the format. Valid + values for this parameter are tar, + tar.gz, or + tar.bz2. + + +
+
+ Auto-extract archive response: JSON + When Object Storage processes the request, it performs + multiple sub-operations. Even if all sub-operations fail, + the operation returns a 201 + Created status. You must examine the + response body to determine which members failed to result + in an object creation. + You can set the Accept request header + to one of these values, which defines the response format: + + + text/plain. Formats response + as plain text. If you omit the + Accept header, + text/plain is the + default. + + + application/json. Formats + response as JSON. + + + application/xml or + text/xml. Formats response + as XML. + + + For more information, see . +
+
diff --git a/openstack-object-storage-dev/section_object-api-authentication.xml b/openstack-object-storage-dev/section_object-api-authentication.xml new file mode 100644 index 0000000..fc7479a --- /dev/null +++ b/openstack-object-storage-dev/section_object-api-authentication.xml @@ -0,0 +1,96 @@ + +
+ Authentication + The owner of an Object + Storage account controls access to that account and its + containers and objects. An owner is the user who has the + admin role for that tenant. The tenant + is also known as the project or account. As the account owner, + you can modify account metadata and create, modify, and delete + containers and objects. + To identify yourself as the account owner, include an + authentication token in the X-Auth-Token + header in the API request. + Depending on the token value in the + X-Auth-Token header, one of the + following actions occur: + + + X-Auth-Token contains the token + for the account owner. + The request is permitted and has full access to make + changes to the account. + + + The X-Auth-Token header is + omitted or it contains a token for a non-owner or a + token that is not valid. + The request fails with a 401 + Unauthorized or + 403 + Forbidden response. + You have no access to accounts or containers, unless + an access control list (ACL) explicitly grants + access. + The account owner can grant account and container + access to users through access control lists (ACLs). + For more information about ACLs, see . + + + The following table describes the authentication services + that you can use with Object Storage: + + + + Authentication service + Description + + + + + + OpenStack Identity Service + (Keystone) + The Object Storage account is synonymous + with the project or 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 + authentication 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_object-api-browser-bypass.xml b/openstack-object-storage-dev/section_object-api-browser-bypass.xml new file mode 100644 index 0000000..f8908c1 --- /dev/null +++ b/openstack-object-storage-dev/section_object-api-browser-bypass.xml @@ -0,0 +1,28 @@ + +
+ Use the Content-Disposition metadata + To override the default behavior for a browser, use the + Content-Disposition header to specify + the override behavior and assign this header to an object. For + example, this header might specify that the browser use a + download program to save this file rather than show the file, + which is the default. + + Override browser default behavior request: HTTP + This example assigns an attachment type to the + Content-Disposition header. This + attachment type indicates that the file is to be + downloaded as goodbye.txt: + # curl -i $publicURL/marktwain/goodbye -X POST -H "X-Auth-Token: $token" -H "Content-Length: 14" -H "Content-Type: application/octet-stream" -H "Content-Disposition: attachment; filename=goodbye.txt" + HTTP/1.1 202 Accepted +Content-Length: 76 +Content-Type: text/html; charset=UTF-8 +X-Trans-Id: txa9b5e57d7f354d7ea9f57-0052e17e13 +Date: Thu, 23 Jan 2014 20:39:47 GMT + +<html><h1>Accepted</h1><p>The request is accepted for processing.</p></html> + +
diff --git a/openstack-object-storage-dev/section_object-api-bulk-delete.xml b/openstack-object-storage-dev/section_object-api-bulk-delete.xml new file mode 100644 index 0000000..4c19435 --- /dev/null +++ b/openstack-object-storage-dev/section_object-api-bulk-delete.xml @@ -0,0 +1,162 @@ + + +PUT'> +POST'> +]> +
+ Bulk delete + To discover whether your Object Storage system supports + this feature, see . Alternatively, check with your service provider. + With bulk delete, you can delete up to 10,000 (configurable) + objects or containers in one request. The objects to be + deleted are listed in the body of a &POST; operation. Use + the bulk-delete query parameter to + indicate that you are performing a bulk delete operation + instead of a normal delete. +
+ Bulk delete request body + To perform a bulk delete operation, add the + bulk-delete query parameter to + the path. The path should be the account, such as + /v1/12345678912345), that contains + the objects and containers. You must set the + Content-Type request header to + text/plain. + In the request body, specify a list of objects or + containers names that are separated by a newline + character. + In addition: + + + You must UTF-8-encode and then URL-encode the + names. + + + To indicate an object, specify the container and + object name as: + CONTAINER_NAME/OBJECT_NAME + + + To indicate a container, specify the container + name as: + CONTAINER_NAME + + + A container must be empty. If it contains + objects, Object Storage does not delete the + container. + + + You can include a maximum of 10,000 items in the + list. You can configure the maximum number of + items value. + + +
+
+ Bulk delete response + When Object Storage processes the request, it performs + multiple sub-operations. Even if all sub-operations fail, + the operation returns a 200 + status. You must examine the response body to determine + which members failed to result in an object + deletion. + You can set the Accept request header + to one of these values, which defines the response + format: + + + text/plain. Formats response + as plain text. If you omit the + Accept header, + text/plain is the + default. + + + application/json. Formats + response as JSON. + + + application/xml or + text/xml. Formats response + as XML. + + + For more information, see . +
+
+ Response body for bulk operations + Some bulk operations, such as bulk delete and + auto-extract archive files, perform multiple + sub-operations. Some sub-operations might succeed while + others fail. The bulk operation returns a response body + that contains details that indicate which sub-operations + have succeeded and failed. + You can set the Accept request header + to define the response format. + The response body contains the following + information: + + + The number of files actually deleted or created, + depending on context. + + + The number of not found objects. For bulk delete + only. + + + Errors. A list of object names and associated + error statuses for the objects that failed to + create or delete. The format depends on the value + you set in the Accept + header. + + + The following auto-extract archive files example shows a + text/plain response body where no + failures occurred: + Number Files Created: 10 + Errors: + The following auto-extract archive files example shows a + text/plain response where some + failures occurred. In this example, the Object Storage + system is configured to reject certain character strings + so that the 400 + Bad Request error occurs for any + objects that use the restricted strings. + Number Files Created: 8 + Errors: + /v1/12345678912345/mycontainer/home/xx%3Cyy, 400 Bad Request + /v1/12345678912345/mycontainer/../image.gif, 400 Bad Request + The following example shows the failure response in + application/json format. This + example output has been reformatted with whitespace to + make it easier to read. The actual response has no such + whitespace. + { + "Number Files Created":1, + "Errors":[ + [ + "/v1/12345678912345/mycontainer/home/xx%3Cyy", + "400 Bad Request" + ], + [ + "/v1/12345678912345/mycontainer/../image.gif", + "400 Bad Request" + ] + ] +} + The following bulk delete example response is in + application/xml format. In this + example, the mycontainer container is + not empty, so it cannot be deleted. + +
+
diff --git a/openstack-object-storage-dev/section_object-api-compress-files.xml b/openstack-object-storage-dev/section_object-api-compress-files.xml new file mode 100644 index 0000000..d704bc8 --- /dev/null +++ b/openstack-object-storage-dev/section_object-api-compress-files.xml @@ -0,0 +1,20 @@ + +
+ Use Content-Encoding metadata + When you create an object or update its metadata, you can + optionally set the Content-Encoding + metadata. This metadata enables you to indicate that the + object content is compressed without losing the identity of + the underlying media type (Content-Type) of + the file, such as a video. + + Content-Encoding header request: HTTP + This example assigns an attachment type to the + Content-Encoding header that + indicates how the file is downloaded: + + +
diff --git a/openstack-object-storage-dev/section_object-api-container-quotas.xml b/openstack-object-storage-dev/section_object-api-container-quotas.xml new file mode 100644 index 0000000..93fbd02 --- /dev/null +++ b/openstack-object-storage-dev/section_object-api-container-quotas.xml @@ -0,0 +1,51 @@ + + +GET'> +HEAD'> +PUT'> +POST'> +DELETE'> +]> +
+ Container quotas + You can set quotas on the size and number of objects stored + in a container by setting the following metadata: + + + X-Container-Meta-Quota-Bytes. The + size, in bytes, of objects that can be stored in a + container. + + + X-Container-Meta-Quota-Count. The + number of objects that can be stored in a container. + + + + When you exceed a container quota, subsequent requests to + create objects fail with a 413 + Request Entity Too Large error. + The Object Storage system uses an eventual consistency model. When you create a + new object, the container size and object count might not be + immediately updated. Consequently, you might be allowed to + create objects even though you have actually exceeded the + quota. + At some later time, the system updates the container size + and object count to the actual values. At this time, + subsequent requests fails. In addition, if you are currently + under the X-Container-Meta-Quota-Bytes + limit and a request uses chunked transfer encoding, the system + cannot know if the request will exceed the quota so the system + allows the request. However, once the quota is exceeded, any + subsequent uploads that use chunked transfer encoding + fail. +
diff --git a/openstack-object-storage-dev/section_object-api-container-sync.xml b/openstack-object-storage-dev/section_object-api-container-sync.xml new file mode 100644 index 0000000..3e658a3 --- /dev/null +++ b/openstack-object-storage-dev/section_object-api-container-sync.xml @@ -0,0 +1,104 @@ + + +GET'> +HEAD'> +PUT'> +POST'> +DELETE'> +]> +
+ + Container synchronization + To discover whether your Object Storage system supports + container synchronization, see . Alternatively, check with your service provider. + Container synchronization enables you to synchronize the + contents of a source container with a destination container. + After you set up container synchronization, the system + automatically copies objects from the source container to the + destination container. Also, the system deletes objects in the + destination container that were deleted in the source + container. + The system copies objects in a way that object metadata is + retained, such as Last-Modified and any + custom metadata you might have set for the object. + You can configure the source and destination containers, as + follows: + + + The source container can be on a different or the + same Object Storage system that the destination + container is on. + + + The destination container can be a source container + for synchronization for another destination container. + + + + The destination container can be the original source + container: both containers synchronize with each + other. Any object that you add to or delete from a + container is automatically copied to or deleted from + the other container. + + + The Object Storage system performs the synchronization in + the background, and makes no guarantees about performance or + timeliness. + Some Object Storage features, such as large object creation, + might require the use of several containers. Container + synchronization handles each container separately; if your + object segments are located in a different container, they are + not transferred unless you also set up container + synchronization on that container. However, even if both the + manifest and segment containers are synchronized, there is no + guarantee that the manifest is transferred before the segment + objects. An attempt to download the large object from the + destination container might fail, be incomplete, or have + jumbled content. Object versioning is not supported. + To configure a source + container for synchronization, set the following metadata + headers: + + + X-Container-Sync-To. Set this + metadata header to the following value: + //REALM/SYSTEM/DESTINATION_ACCOUNT/DESTINATION_CONTAINER_NAME + Your service provider can give you the appropriate + values for + REALM + and + SYSTEM. + The objects are sent to the + DESTINATION_ACCOUNT/DESTINATION_CONTAINER_NAME + container. These names can be different from the + source account and container names. + + + X-Container-Sync-Key. Set this + metadata header to an arbitrary string value. This + value serves as a shared secret. Secure this value + just as you would a password. + + + To configure a destination container to receive objects, set + the X-Container-Sync-Key metadata header to + the X-Container-Sync-Key value in the + source container. + + To configure a destination container as the source + container for another destination container, set the + X-Container-Sync-To metadata header + as you would for a source container. + +
diff --git a/openstack-object-storage-dev/section_object-api-cors-headers.xml b/openstack-object-storage-dev/section_object-api-cors-headers.xml new file mode 100644 index 0000000..1adbe69 --- /dev/null +++ b/openstack-object-storage-dev/section_object-api-cors-headers.xml @@ -0,0 +1,48 @@ + +
+ Assign CORS headers to requests + Cross-Origin Resource Sharing (CORS) is a specification that + defines how browsers and servers communicate across origins by + using HTTP headers, such as those assigned by Object Storage + API requests. The Object Storage API supports these headers. + For more information, see www.w3.org/TR/access-control/. + + + Access-Control-Allow-Credentials + + + Access-Control-Allow-Methods + + + Access-Control-Allow-Origin + + + Access-Control-Expose-Headers + + + Access-Control-Max-Age + + + Access-Control-Request-Headers + + + Access-Control-Request-Method + + + Origin + + + You can assign these headers to only objects. + + Assign CORS header request: HTTP + This example assigns the file origin to the + Origin header, which ensures that + the file originated from a reputable source: + + +
diff --git a/openstack-object-storage-dev/section_object-api-create-large-objects.xml b/openstack-object-storage-dev/section_object-api-create-large-objects.xml new file mode 100644 index 0000000..3226841 --- /dev/null +++ b/openstack-object-storage-dev/section_object-api-create-large-objects.xml @@ -0,0 +1,369 @@ + + + + + + +COPY'> +GET'> +HEAD'> +PUT'> +POST'> +DELETE'> +]> +
+ Large objects + By default, the content of an object cannot be greater than + 5 GB. However, you can use segment objects and manifest + objects to store more content. +
+ Segment objects + You can divide your content into segments, and upload + each segment into its own segment object. Segment objects + do not have any special features. You create, update, + download, and delete segment objects just as you would + normal objects. +
+
+ Manifest objects + A manifest object points to segment objects. When you + download a manifest object, Object Storage 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; requests. The + Content-Length response header + value is the total size of all segment objects. Object + Storage calculates the ETag response + header value by taking the ETag value + of each segment, concatenating them together, and + returning the MD5 checksum of the result. + + If you make a © request by using a manifest + object as the source, the new object is a normal, and + not a segment, object. If the total size of the source + segment objects exceeds 5 GB, the © request + fails. However, you can make a duplicate of the + manifest object and this new object can be larger than + 5 GB. + + The manifest object types are: + + + Static large + objects. The manifest object + content is an ordered list of the names of the + segment objects in JSON format. + + + Dynamic large + objects. The manifest object has no + content. + However, it has + X-Object-Manifest metadata + header. The value of this header is + <container>/<prefix>, + where <container> is the + name of the container where the segment objects + are stored, and <prefix> is + a string that all segment objects have in + common. + + + While both types of manifest objects have similar + behavior, the following table describes their + differences: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Static and dynamic large objects
Object typeEnd-to-end integrityUpload orderRemoval or addition of segment objectsSegment object size and numberSegment object container nameManifest Object MetadataMaking a copy of the manifest object
Static large objectAssured. The list of segments includes + the MD5 checksum (ETag) + of each segment. You cannot upload the + manifest object if the + ETag in the list + differs from the segment object already + uploaded. If a segment is somehow lost, an + attempt to download the manifest object + results in an error.The segment objects must be uploaded + before the manifest object.You cannot add or remove segment objects + from the manifest. However, you can create + a completely new manifest object of the + same name with a different manifest + list.Segment objects must be at least 1 MB in + size (by default). The final segment + object can be any size. At most 1000 + segments are supported (by + default).The manifest list includes the container + name of each object. Segment objects can + be in different containers.The object has + X-Static-Large-Object + set to true. You do not + set this metadata directly. Instead the + system sets it when you &PUT; a static + manifest object.
Dynamic large objectNot guaranteed. The eventual consistency + model means that although you have + uploaded a segment object, it might not + appear in the container listing until + later. If you download the manifest before + it appears in the container, it does not + form part of the content returned in + response to a &GET; request.You can upload manifest and segment + objects in any order. You are recommended + to upload the manifest object after the + segments in case a premature download of + the manifest occurs. However, this is not + enforced.You can upload new segment objects or + remove existing segments. The names must + simply match the + <prefix> + supplied in + X-Object-Manifest.Segment objects can be of any + size.All segment objects must be in the same + containerThe X-Object-Manifest + value is the + <container>/<prefix> + indicating where the segment objects are + located. You supply this request header in + the &PUT; operationThe © operation does not create a + manifest object. To duplicate a manifest + object, use the &GET; operation to read + the value of + X-Object-Manifest + and use this value in the + X-Object-Manifest + request header in a &PUT; operation. This + creates a new manifest object that shares + the same set of segment objects as the + original manifest object.
+
+ Dynamic large objects + You must segment objects that are larger than 5 GB + before you can upload them. You then upload the + segment objects like you would any other object and + create a dynamic large manifest object. The manifest + object tells Object Storage how to find the segment + objects that comprise the large object. The segments + remain individually addressable, but retrieving the + manifest object streams all the segments concatenated. + There is no limit to the number of segments that can + be a part of a single large object. + To ensure the download works correctly, you must + upload all the object segments to the same container + and ensure that each object name is prefixed in such a + way that it sorts in the order in which it should be + concatenated. You also create and upload a manifest + file. The manifest file is a zero-byte file with the + extra X-Object-Manifest + <container>/<prefix> header, + where <container> is the container + the object segments are in and + <prefix> is the common prefix + for all the segments. You must UTF-8-encode and then + URL-encode the container and common prefix in the + X-Object-Manifest + header. + It is best to upload all the segments first and then + create or update the manifest. With this method, the + full object is not available for downloading until the + upload is complete. Also, you can upload a new set of + segments to a second location and then update the + manifest to point to this new location. During the + upload of the new segments, the original manifest is + still available to download the first set of + segments. + + Upload segment of large object request: + HTTP + + + + Upload segment of large object response: + HTTP + s + + No response body is returned. A status code of + 2nn + (between 200 and 299, inclusive) indicates a + successful write; status 411 + Length Required denotes a + missing Content-Length or + Content-Type header in the request. + If the MD5 checksum of the data written to the storage + system does NOT match the (optionally) supplied ETag + value, a 422 + Unprocessable Entity response + is returned. + You can continue uploading segments like this + example shows, prior to uploading the manifest. + + Upload next segment of large object request: + HTTP + + + + Upload next segment of large object response: + HTTP + w + + Next, upload the manifest you created that indicates + the container the object segments reside within. Note + that uploading additional segments after the manifest + is created causes the concatenated object to be that + much larger but you do not need to recreate the + manifest file for subsequent additional + segments. + + Upload manifest request: HTTP + + + + Upload manifest response: HTTP + + + The response's Content-Type for a + &GET; or &HEAD; on the manifest is the same as the + Content-Type set during the + &PUT; request that created the manifest. You can + easily change the Content-Type by + reissuing the &PUT; request. +
+
+ 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 + response header returned by the&PUT; + operation. Alternatively, you can calculate + the MD5 checksum of the segment prior to + uploading and include this in the + 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 + this is a manifest object by including the + ?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 attributes: + + + path. The container and object + name in this format: + <container-name>/<object-name> + + + etag. The MD5 checksum of the + content of the segment object. This value must + match the ETag of that + object. + + + size_bytes. The size of the + segment object. This value must match the + Content-Length of that + object. + + + + Static large object manifest list + This example shows three segment objects. You + can use several containers and the object names do + not have to conform to a specific pattern, in + contrast to dynamic large objects. + + + 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 can also set the + Content-Type request header and + custom object metadata. + When the &PUT; operation sees the + ?multipart-manifest=put + query parameter, it reads the request body and verifies + that each segment object exists and that the sizes and + ETags match. If there is a mismatch, the + &PUT;operation fails. + If everything matches, the manifest object is + created. The X-Static-Large-Object + metadata is set to true indicating + that this is a static object manifest. + Normally when you perform a &GET; operation on the + manifest object, the response body contains the + concatenated content of the segment objects. To + download the manifest list, use the + ?multipart-manifest=get query parameter. + The resulting list is not formatted the same as 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 + objects are not affected. However, if you add the + ?multipart-manifest=delete query parameter, + the segment objects are deleted and if all are + successfully deleted, the manifest object is also + deleted. + To change the manifest, use a &PUT; operation with + the ?multipart-manifest=put + query parameter. This request creates a + new manifest object. You can + also update the object metadata in the usual + way. +
+
+
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..f868c47 100644 --- a/openstack-object-storage-dev/section_object-api-create-website.xml +++ b/openstack-object-storage-dev/section_object-api-create-website.xml @@ -1,56 +1,30 @@ - - - - - - -COPY'> -GET'> -HEAD'> -PUT'> -POST'> -DELETE'> - - - - - -'> - - - - - -'> -]>
- 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 - X-Web-Mode to TRUE on the - request. The staticweb filter should be added to - the pipeline in your /etc/swift/proxy-server.conf - file just after any auth middleware. Beneath the pipeline, the - staticweb middleware configuration must be - added. For example: - - Your publicly readable containers will be checked for two - headers, X-Container-Meta-Web-Index and - X-Container-Meta-Web-Error. (The latter + xml:id="static-website"> + Create static website + To discover whether your Object Storage system supports + this feature, see . Alternatively, check with your service provider. + You can use your Object Storage account to create a static + website. This mode is normally only active for anonymous + requests, which provide no authentication token. To use it + with authenticated requests, set the header + X-Web-Mode to TRUE + on the request. To determine whether the static website + feature is enabled, contact your service provider. + For example: + + Your publicly readable containers are checked for two + headers, X-Container-Meta-Web-Index and + X-Container-Meta-Web-Error. (The latter header is discussed below, under Set Error Pages for Static Website.) With - X-Container-Meta-Web-Index, you determine the - index file (or default page served, such as - index.html) displays your website. When + X-Container-Meta-Web-Index, you + determine the index file (or default page served, such as + index.html) displays your website. When someone initially enters your site, they don't have to specify the index file; index.html file displays automatically. If you create sub-directories for your site by creating @@ -60,39 +34,41 @@ format="SVG" scale="60"/> visits to the sub-directory return a 404 error. You also have the option of displaying a list of files in your pseudo-directory instead of a web page. You do this by - setting the X-Container-Meta-Web-Listings header - to TRUE. You may add style to your file listing - by setting X-Container-Meta-Web-Listings-CSS: to - a style sheet (for example, lists.css). + setting the X-Container-Meta-Web-Listings + header to TRUE. You may add style to your + file listing by setting + X-Container-Meta-Web-Listings-CSS: to a + style sheet (for example, + lists.css).
Static Web Middleware through swift Make Container Publicly Readable Make the container publicly readable. Once the container is publicly readable, you may access your - objects directly, but you will need to set the index - file to browse the main site URL and its + objects directly, but you must set the index file to + browse the main site URL and its sub-directories. - swift post -r '.r:*' container + $ swift post -r '.r:*' container Set Site Index File Set the index file. In this case, - index.html is the default file + index.html is the default file displayed when the site displays. - swift post -m 'web-index:index.html' container + $ swift post -m 'web-index:index.html' container Enable File Listing Turn on file listing. If you do not set the index file, list the objects in the container. Instructions on styling the list with the CSS follow. - swift post -m 'web-listings: true' container + $ swift post -m 'web-listings: true' container Enable CSS for File Listing Style the file listing. - +
@@ -100,24 +76,27 @@ 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 - page 401error.html. Similarly, 404 errors - will display 404error.html. You must have - both of these pages created in your container when you set - the X-Container-Meta-Web-Error metadata, or - your site will display generic error pages. - Set the X-Container-Meta-Web-Error metadata - once for your entire static website. + X-Container-Meta-Web-Error to + error.html, 401 errors will display + the page 401error.html. Similarly, 404 + errors will display 404error.html. You + must have both of these pages created in your container + when you set the + X-Container-Meta-Web-Error + metadata, or your site will display generic error + pages. + Set the X-Container-Meta-Web-Error + metadata once for your entire static website. Set Error Pages for Static Website Request - + - Any 2xx response indicates success. - + Any 2nn response indicates success. +
diff --git a/openstack-object-storage-dev/section_object-api-curl-commands.xml b/openstack-object-storage-dev/section_object-api-curl-commands.xml new file mode 100644 index 0000000..4381445 --- /dev/null +++ b/openstack-object-storage-dev/section_object-api-curl-commands.xml @@ -0,0 +1,211 @@ + + + + + + + + +GET'> +PUT'> +POST'> +DELETE'> + + + + + +'> + + + + + +'> +]> +
+ cURL commands + 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 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. + Before you can run these examples, you must set environment + variables. See . + This example cURL command shows account details and lists + containers in the account. + # curl -i $publicURL?format=json \ + -X GET -H "X-Auth-Token: $token" + HTTP/1.1 200 OK +Content-Length: 96 +X-Account-Object-Count: 1 +X-Timestamp: 1389453423.35964 +X-Account-Meta-Subject: Literature +X-Account-Bytes-Used: 14 +X-Account-Container-Count: 2 +Content-Type: application/json; charset=utf-8 +Accept-Ranges: bytes +X-Trans-Id: tx274a77a8975c4a66aeb24-0052d95365 +Date: Fri, 17 Jan 2014 15:59:33 GMT + + The response, in JSON format, is: + [ + { + "count":0, + "bytes":0, + "name":"janeausten" + }, + { + "count":1, + "bytes":14, + "name":"marktwain" + } +] + + 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. +
+ + + Includes the HTTP response headers 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. + +
+ Example of an XML response + To request an XML response, append the + format=xml query parameter to the + request. + This example cURL command shows account information and + list containers in the account, and asks for the response + in XML: + # curl -i $publicURL?format=xml \ + -X GET -H "X-Auth-Token: $token" + HTTP/1.1 200 OK +Content-Length: 262 +X-Account-Object-Count: 1 +X-Timestamp: 1389453423.35964 +X-Account-Meta-Subject: Literature +X-Account-Bytes-Used: 14 +X-Account-Container-Count: 2 +Content-Type: application/xml; charset=utf-8 +Accept-Ranges: bytes +X-Trans-Id: tx69f60bc9f7634a01988e6-0052d9544b +Date: Fri, 17 Jan 2014 16:03:23 GMT + <?xml version="1.0" encoding="UTF-8"?> +<account name="my_account"> + <container> + <name>janeausten</name> + <count>0</count> + <bytes>0</bytes> + </container> + <container> + <name>marktwain</name> + <count>1</count> + <bytes>14</bytes> + </container> +</account +
+
diff --git a/openstack-object-storage-dev/section_object-api-discoverability.xml b/openstack-object-storage-dev/section_object-api-discoverability.xml new file mode 100644 index 0000000..8c5190b --- /dev/null +++ b/openstack-object-storage-dev/section_object-api-discoverability.xml @@ -0,0 +1,66 @@ + +POST'> +GET'> +]> +
+ Discoverability + Your Object Storage system might not enable all features + that this document describes. These features are: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + To discover which features are enabled in your Object + Storage system, use the /info request. + However, your service provider might have disabled the + /info request, or you might be using an + older version that does not support the + /info request. + To use the /info request, send a &GET; + request using the /info path to the Object + Store endpoint as shown in this example: + # curl https://storage.clouddrive.com/info + This example shows a truncated response body: + { + "swift":{ + "version":"1.11.0" + }, + "staticweb":{ + + }, + "tempurl":{ + + } +} + This output shows that the Object Storage system has enabled + the static website and temporary URL features. +
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-env-vars.xml b/openstack-object-storage-dev/section_object-api-env-vars.xml new file mode 100644 index 0000000..21b8b0c --- /dev/null +++ b/openstack-object-storage-dev/section_object-api-env-vars.xml @@ -0,0 +1,38 @@ + +
+ Environment variables required to run examples + To run the cURL command examples for the Object Storage API + requests, set these environment variables: + + + publicURL. The public URL that is + the HTTP endpoint from where you can access Object + Storage. It includes the Object Storage API version + number and your account name. For example, + https://23.253.72.207/v1/my_account. + + + token. The authentication token + for Object Storage. + + + To obtain these values, run the swift stat + -v command. + As shown in this example, the public URL appears in the + StorageURL field, and the token appears + in the Auth Token field: + StorageURL: https://23.253.72.207/v1/my_account +Auth Token: {token} +Account: my_account +Containers: 2 +Objects: 3 +Bytes: 47 +Meta Book: MobyDick +X-Timestamp: 1389453423.35964 +X-Trans-Id: txee55498935404a2caad89-0052dd3b77 +Content-Type: text/plain; charset=utf-8 +Accept-Ranges: bytes +
diff --git a/openstack-object-storage-dev/section_object-api-expire-objects.xml b/openstack-object-storage-dev/section_object-api-expire-objects.xml new file mode 100644 index 0000000..8de26f6 --- /dev/null +++ b/openstack-object-storage-dev/section_object-api-expire-objects.xml @@ -0,0 +1,61 @@ + + +PUT'> +POST'> +]> +
+ Schedule objects for deletion + To discover whether your Object Storage system supports this + feature, see . Alternatively, + check with your service provider. + Scheduling an object for deletion is helpful for objects + that you do not want to permanently store, such as log files, + recurring full backups of a dataset, or documents or images + that become outdated at a specified future time. + To schedule an object for deletion, include one of these + headers with the &PUT; or &POST; request on the object: + + + X-Delete-After + An integer value. Specifies the number of seconds in + the future when you want to delete the object. + This header is converted to an + X-Delete-At header that is set + to the sum of the X-Delete-After + value plus the current time, in seconds. + + + X-Delete-At + A UNIX Epoch timestamp, in integer form. For + example, 1348691905 represents + Wed, 26 Sep 2012 20:38:25 GMT. + Specifies the time when you want the object to expire, + not be served, and be deleted completely from the + object store. + + + Use the &POST; method to assign expiration headers to + existing objects that you want expire. + + Delete object at specified time request: HTTP + In the example, the X-Delete-At header is + assigned a UNIX Epoch timestamp in integer form for Mon, + 11 Jun 2012 15:38:25 GMT. Use http://www.epochconverter.com/ for example + timestamps and a batch converter. + # curl -i $publicURL/marktwain/goodbye -X PUT -H "X-Auth-Token: $token" -H "X-Delete-At: 1390581073" -H "Content-Length: 14" -H "Content-Type: application/octet-stream" + + + Delete object after specified interval request: + HTTP + This example sets the X-Delete-After header + to a value in seconds that is equivalent to 10 days. After + this time, the object expires. + + +
diff --git a/openstack-object-storage-dev/section_object_api_formpost.xml b/openstack-object-storage-dev/section_object-api-formpost.xml similarity index 98% rename from openstack-object-storage-dev/section_object_api_formpost.xml rename to openstack-object-storage-dev/section_object-api-formpost.xml index 7301344..e38ef1f 100644 --- a/openstack-object-storage-dev/section_object_api_formpost.xml +++ b/openstack-object-storage-dev/section_object-api-formpost.xml @@ -13,6 +13,9 @@ xml:id="form-post"> Form POST middleware + To discover whether your Object Storage system supports + this feature, see . Alternatively, check with your service provider. You can upload objects directly to the Object Storage system from a browser by using the form &POST; middleware. This middleware uses account secret keys to generate a diff --git a/openstack-object-storage-dev/src/docbkx/object-api-language-bindings.xml b/openstack-object-storage-dev/section_object-api-language-bindings.xml similarity index 100% rename from openstack-object-storage-dev/src/docbkx/object-api-language-bindings.xml rename to openstack-object-storage-dev/section_object-api-language-bindings.xml diff --git a/openstack-object-storage-dev/section_object-api-large-lists.xml b/openstack-object-storage-dev/section_object-api-large-lists.xml new file mode 100644 index 0000000..3233f50 --- /dev/null +++ b/openstack-object-storage-dev/section_object-api-large-lists.xml @@ -0,0 +1,58 @@ + + + + + +]> +
+ 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 + parameter. 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 again. + + + limit + parameter. 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 + parameter. 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. + + + For examples of how to page through large lists, see . +
diff --git a/openstack-object-storage-dev/section_object-api-overview.xml b/openstack-object-storage-dev/section_object-api-overview.xml new file mode 100644 index 0000000..a535b15 --- /dev/null +++ b/openstack-object-storage-dev/section_object-api-overview.xml @@ -0,0 +1,257 @@ + + + + +PUT'> +GET'> +POST'> +]> +
+ Object Storage API overview + OpenStack Object Storage is an object-based storage system + that stores content and metadata as objects. You create, + modify, and get objects and metadata by using the Object + Storage API, which is implemented as a set of Representational + State Transfer (REST) web services. + For an introduction to OpenStack Object Storage, see Object Storage in the OpenStack Cloud + Administrator Guide. + You use the HTTPS (SSL) protocol to interact with Object + Storage, and you use standard HTTP calls to perform API + operations. You can also use language-specific APIs, which use + the RESTful API, that make it easier for you to integrate into + your applications. + To assert your right to access and change data in an + account, you identify yourself to Object Storage by using an + authentication token. To get a token, you present your + credentials to an authentication service. The authentication + service returns a token and the URL for the account. Depending + on which authentication service that you use, the URL for the + account appears in: + + + OpenStack Identity + Service. The URL is defined in the + service catalog. + + + Tempauth. The URL + is provided in the X-Storage-Url + response header. + + + In both cases, the URL is the full URL and includes the + account resource. For information about authentication, see + . + The Object Storage API supports the standard, non-serialized + response format, which is the default, and both JSON and XML + serialized response formats. See . + The Object Storage system organizes data in a hierarchy, as + follows: + + + Account. Represents + the top-level of the hierarchy. + Your service provider creates your account and you + own all resources in that account. The account defines + a namespace for containers. A container might have the + same name in two different accounts. + In the OpenStack environment, + account is synonymous with + a project or tenant. + + + Container. Defines + a namespace for objects. An object with the same name + in two different containers represents two different + objects. You can create any number of containers + within an account. + In addition to containing objects, you can also use + the container to control access to objects by using an + access control list (ACL). You cannot store an ACL + with individual objects. + In addition, you configure and control many other + features, such as object versioning, at the container + level. See . + You can bulk-delete up to 10,000 containers in a + single request. See . + + + Object. Stores data + content, such as documents, images, and so on. You can + also store custom metadata with an object. + With the Object Storage API, you can: + + + Store an unlimited number of objects. Each + object can be as large as 5 GB, which is the + default. You can configure the maximum object + size. + + + Upload and store objects of any size with + large object creation. See . + + + Use cross-origin resource sharing to manage + object security. See . + + + Compress files. See . + + + Override browser behavior for an object. See + . + + + Schedule objects for deletion. See . + + + Bulk-delete up to 10,000 objects in a single + request. See . + + + Auto-extract archive files. See . + + + Generate a URL that provides time-limited + &GET; access to an object. See . + + + Upload objects directly to the Object + Storage system from a browser by using form + &POST; middleware. See . + + + + + The account, container, and object hierarchy affects the way + you interact with the Object Storage API. + Specifically, the resource path reflects this structure and + has this format: + /v1/{account}/{container}/{object} + For example, for the flowers/rose.jpg + object in the images container in the + 12345678912345 account, the resource + path is: + /v1/12345678912345/images/flowers/rose.jpg + Notice that the object name contains the + / character. This slash does not + indicate that Object Storage has a sub-hierarchy called + flowers because containers do not store + objects in actual sub-folders. However, the inclusion of + / or a similar convention inside object + names enables you to create pseudo-hierarchical folders and + directories. See . + For example, if the endpoint for Object Storage is + objects.mycloud.com, the returned URL + is + https://objects.mycloud.com/v1/12345678912345. + To access a container, append the container name to the + resource path. + To access an object, append the container and the object + name to the path. + If you have a large number of containers or objects, you can + use query parameters to page through large lists of + containers or objects. Use the marker, + limit, and + end_marker query parameters to + control how many items are returned in a list and where the + list starts or ends. See . + Object Storage HTTP requests have the following default + constraints. Your service provider might use different default + values. + + + + 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 GB + + + + Length of container names + 256 bytes + Cannot contain the / + character. + + + Length of object names + 1024 bytes + By default, there are no character + restrictions. + + + + You must UTF-8-encode and then URL-encode container and + object names before you call the API binding. If you use an + API binding that performs the URL-encoding for you, do not + URL-encode the names before you call the API binding. + Otherwise, you double-encode these names. Check the length + restrictions against the URL-encoded string. + These sections describe the operations that you can perform + with the Object Storage API: + + + . Use to + perform account-level tasks. + Lists containers for a specified account. Creates, + updates, and deletes account metadata. Shows account + metadata. + + + . Use to + perform container-level tasks. + Lists objects in a specified container. Creates, + shows details for, and deletes containers. Creates, + updates, shows, and deletes container metadata. + + + . Use to + perform object-level tasks. + Creates, replaces, shows details for, and deletes + objects. Copies objects with another object with a new + or different name. Updates object metadata. + + +
diff --git a/openstack-object-storage-dev/section_object-api-pseudo-hier-folders.xml b/openstack-object-storage-dev/section_object-api-pseudo-hier-folders.xml new file mode 100644 index 0000000..e730ce0 --- /dev/null +++ b/openstack-object-storage-dev/section_object-api-pseudo-hier-folders.xml @@ -0,0 +1,94 @@ + + +GET'> +HEAD'> +PUT'> +POST'> +DELETE'> +]> +
+ 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 can use the + delimiter query parameter. this examples show + you how to use pseudo-hierarchical folders and + directories. + + In this 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 and delimiter + parameters 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 this 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 2nn (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/section_object-api-response-formats.xml b/openstack-object-storage-dev/section_object-api-response-formats.xml new file mode 100644 index 0000000..1f6de64 --- /dev/null +++ b/openstack-object-storage-dev/section_object-api-response-formats.xml @@ -0,0 +1,136 @@ + + +GET'> +]> +
+ Serialized response formats + By default, the Object Storage API uses a + text/plain response format. In + addition, both JSON and XML data serialization response + formats are supported. + + To run the cURL command examples, you must export environment + variables. + + To define the response format, use one of these + methods: + + + + Method + Description + + + + + format=format + query parameter + + Append this parameter to the URL for a &GET; + request, where + format is + json or + xml. + + + + Accept request + header + + Include this header in the &GET; request. + The valid header values are: + + + text/plain. Plain text + response format. The default. + + + application/json. JSON + data serialization response + format. + + + application/xml or + text/xml. XML data + serialization response format. + + + + + + + + JSON example with format query parameter + For example, this request uses the + format query parameter to ask + for a JSON response: + # curl -i $publicURL?format=json -X GET -H "X-Auth-Token: $token" + HTTP/1.1 200 OK +Content-Length: 96 +X-Account-Object-Count: 1 +X-Timestamp: 1389453423.35964 +X-Account-Meta-Subject: Literature +X-Account-Bytes-Used: 14 +X-Account-Container-Count: 2 +Content-Type: application/json; charset=utf-8 +Accept-Ranges: bytes +X-Trans-Id: tx274a77a8975c4a66aeb24-0052d95365 +Date: Fri, 17 Jan 2014 15:59:33 GMT + Object Storage lists container names with additional + information in JSON format: + [ + { + "count":0, + "bytes":0, + "name":"janeausten" + }, + { + "count":1, + "bytes":14, + "name":"marktwain" + } +] + + + XML example with Accept header + This request uses the Accept request + header to ask for an XML response: + # curl -i $publicURL -X GET -H "X-Auth-Token: $token" -H "Accept: application/xml; charset=utf-8" + HTTP/1.1 200 OK +Content-Length: 263 +X-Account-Object-Count: 3 +X-Account-Meta-Book: MobyDick +X-Timestamp: 1389453423.35964 +X-Account-Bytes-Used: 47 +X-Account-Container-Count: 2 +Content-Type: application/xml; charset=utf-8 +Accept-Ranges: bytes +X-Trans-Id: txf0b4c9727c3e491694019-0052e03420 +Date: Wed, 22 Jan 2014 21:12:00 GMT + Object Storage lists container names with additional + information in XML format: + <?xml version="1.0" encoding="UTF-8"?> +<account name="AUTH_73f0aa26640f4971864919d0eb0f0880"> + <container> + <name>janeausten</name> + <count>2</count> + <bytes>33</bytes> + </container> + <container> + <name>marktwain</name> + <count>1</count> + <bytes>14</bytes> + </container> +</account> + The remainder of the examples in this guide use + standard, non-serialized responses. However, all &GET; + requests that perform list operations accept the + format query parameter or + Accept request header. + +
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..bd4ef53 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 @@ -1,518 +1,20 @@ - - - - - - -COPY'> -GET'> -HEAD'> -PUT'> -POST'> -DELETE'> - - - - - -'> - - - - - -'> -]>
- Storage Container Services - You can perform the following operations for - containers: - - - - Verb - URI - Description - - - - - &GET; - /account/container - Lists objects. - - - &PUT; - /account/container - Creates a container. - - - &DELETE; - /account/container - Deletes a container. - - - &HEAD; - /account/container - Gets container 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 container. - 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. - - - - - All operations follow this format: - - Storage Container Services HTTP Request - METHOD /v1/<account>/<container> HTTP/1.1 - -
- List Objects - &GET; operations against a storage container name are - performed to retrieve a list of objects stored in the - container. Additionally, there are a number of optional - query parameters that can be used to refine the list - results. - A request with no query parameters will return the full - list of object names stored in the container, up to 10,000 - names. Optionally specifying the query parameters will - filter the full list and return a subset of - objects. - - Query Parameters - - limit - - For an integer value - n - , limits the number of - results to at most - n - values. - - - - marker - - Given a string value - x - , return object names greater - in value than the specified marker. - - - - end_marker - - Given a string value - x - , return object names less in - value than the specified marker. - - - - prefix - - For a string value - x - , causes the results to be - limited to object names beginning with the - substring - x - . - - - - format - - Specify either json or - xml to return the respective - serialized response. - - - - delimiter - - For a character - c - , return all the object names - nested in the container (without the need for - the directory marker objects). - - - - path - - For a string value - x - , return the object names - nested in the pseudo path. Equivalent to - setting delimiter to '/' and prefix to the - path with a '/' on the end. - - - - - List Objects HTTP Request - - - A list of objects is returned in the response body, one - object name per line. The response will have a 2xx HTTP status - code (between 200 and 299 inclusive). If the container does - not exist, or if an incorrect account is specified, then a - response with a 404 (Not Found) status code will be - returned. - - List Objects HTTP Response - - -
- Serialized List Output - If a format=xml or - format=json argument is appended to - the storage account URL, the service will serve - extended object information serialized in the chosen - format. Other than the ?format=xml|json - parameter, it will return the same status/errors - codes. The sample responses below are formatted for - readability. - - Get Objects Details HTTP and JSON - Request - - - - Get Objects Details HTTP and JSON Response - - - - - Objects Details Request: XML - - - - Objects Details Request: XML - - - -
-
- Controlling a Large List of Objects - The system returns a maximum of 10,000 object names - per request. To retrieve subsequent object names, - another request must be made with the 'marker' - parameter. The marker indicates where the last list - left off and the system returns object 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, a 'limit' - parameter may be given. - If the number of object names returned equals the - limit given (or 10,000 if no limit is given), it can - be assumed there are more object names to be listed. - If the container name list is exactly divisible by the - limit, the last request has no content. - - List Large Number of Objects - For an example, let's use a listing of five - object names: - gala -grannysmith -honeycrisp -jonagold -reddelicious - We'll use a limit of two to show how things - work: - - 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 we have two items returned; there might be - more: - - Now we received less than the limit number of - object names, indicating that we have the complete - list. - By using end_marker we can limit - the result set to object names less than the given - value. - - -
-
- 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 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 - &PUT; operations against a storage container are used to - create that container. - Containers are storage compartments for your data. The - URL encoded name must be less than 256 bytes and cannot - contain a forward slash '/' character. - Containers can be assigned custom metadata by including - additional HTTP headers on the &PUT; request. The custom - metadata is assigned to a container via HTTP headers - identified with the X-Container-Meta- prefix. - - Create Container HTTP Request - - - No content is returned. A status code of 201 (Created) - indicates that the container was created as requested. - Container &PUT; requests are idempotent and a code of 202 - (Accepted) is returned when the container already existed. - If you request a &PUT; to a container with an - X-Container-Meta- prefix in the header, - your &GET;/&HEAD; request responses carry the metadata - prefix from the container in subsequent requests. - - Create Container HTTP Response - - - Using custom container metadata, you can create information in the header to - effectively tag a container with metadata. The container metadata restrictions are the - same as object metadata: you can have 4096 bytes maximum overall metadata, 90 distinct - metadata items at the most. Each may have a 128 character name length with a maximum of - 256 bytes in the value. Any valid UTF-8 encoded string value is allowed for metadata. In - addition for custom metadata, we recommend that you - URL-encode the header value. However, for non-custom metadata (such as - X-Versions-Location), you must UTF-8 encode and then - URL-encode values that contain a container or object name. - - Container Create Container with Metadata HTTP - Request - - - No content is returned. A status code of 201 (Created) - indicates that the container was created as requested. - Container &PUT; requests are idempotent and a code of 202 - (Accepted) is returned if the container existed prior to - the request. If you request a &PUT; to a container with an - X-Container-Meta- prefix in the header, - your &GET;/&HEAD; request responses carry the metadata - prefix from the container in subsequent requests. - - Create Container with Metadata HTTP - Response - - -
-
- Delete Container - &DELETE; operations against a storage container - permanently remove it. The container must be empty before - it can be deleted. - A &HEAD; request against the container can be used to - determine if it contains any objects. - - Delete Container HTTP Request - - - No content is returned. A status code of 2xx (between - 200 and 299, inclusive) indicates success, 404 (Not Found) is - returned if the requested container was not found, and a 409 - (Conflict) if the container is not empty. No response body is - generated. - - Delete Container HTTP Response - - -
-
- Get Container Metadata - &HEAD; operations against a storage container are used - to determine the number of objects, and the total bytes of - all objects stored in the container. 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 Container Metadata HTTP Request - - - The HTTP status code will be 2xx (between 200 and 299, - inclusive) if the container exists, and 404 (Not Found) if it - does not. The object count and utilization are returned in the - X-Container-Object-Count and - X-Container-Bytes-Used headers - respectively. - - Get Container Metadata HTTP Response - - -
-
- Create or Update Container Metadata - You may create any custom or arbitrary metadata headers - as you find useful. They must, however, take the format - X-Container-Meta-. - To create or update the arbitrary container metadata, - use the &POST; query. Subsequent requests of the same - key/value pair overwrites the previous value. - - Update Container Metadata HTTP Request - - - No response body is returned. A status code of 2xx - (between 200 and 299, inclusive) indicates success; status 404 - (Not Found) is returned when the requested container does not - exist. - - Update Container Metadata HTTP Response - - - To confirm your metadata changes, perform a &HEAD; - request on the container. Do not send the metadata in your - &HEAD; request. - - View Container Metadata HTTP Request - - - - View Container Metadata HTTP Response - - - -
-
- Delete Container Metadata - To delete a metadata header send an empty value for that - particular header, such as - X-Container-Meta-Book:. - If the tool you're using to communicate with Object - Storage doesn't support sending empty headers (older - versions of curl) send the header - "X-Remove-Container-Meta-name: - arbitrary value". For - example, send a header like - X-Remove-Container-Meta-Book: x. The - value (x in this example) is - ignored. - - Delete Container Metadata HTTP Request - - No response body is returned. A status code of 2xx - (between 200 and 299, inclusive) indicates success. - -
+ Storage container services + Lists objects, creates and delete containers, and gets, + creates, updates, or deletes container metadata. + + + + + + + + + +
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 4127445..307e7f8 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 @@ -3,7 +3,6 @@ - COPY'> GET'> @@ -16,1044 +15,30 @@ 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 + stored in the system. Through the REST interface, you can include metadata for an object by adding custom HTTP headers - to the request and the data payload as the request body. - Objects cannot exceed 5 GB and must have names that do not + to the request and the data payload as the request + body. + Objects cannot exceed 5 GB and must have names that do not exceed 1024 bytes after URL encoding. However, you can segment a large object into 5 GB segments and upload the segments. Then, you can download the segments as a single concatenated object. You can use HTTP requests to work with the segments and manifests directly. - - - - Verb - URI - Description - - - - - &GET; - /account/container/object - Gets object details. - - - &PUT; - /account/container/object - Creates or updates object. - - - &PUT; - /account/container/object - Chunked transfer encoding. - - - &DELETE; - /account/container/object - Deletes a specified object. - - - &HEAD; - /account/container/object - Gets object metadata. - - - &POST; - /account/container/object - Updates object 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 object. 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. - - - -
- Get Object Details - Perform &GET; operations against an object to get object - data. - You can perform conditional &GET; requests by using the - following HTTP headers in the request: - - - If-Match - - - If-None-Match - - - If-Modified-Since - - - If-Unmodified-Since - - - These headers are documented in http://www.ietf.org/rfc/rfc2616.txt. - You can use the HTTP Range header to fetch - portions of data by using one or more range - specifications. To specify many ranges, separate the range - specifications with a comma. - The types of range specifications are: - - - Byte range - specification. Use - FIRST_BYTE_OFFSET to specify the start of the data - range, and LAST_BYTE_OFFSET to specify the end. - You can omit the LAST_BYTE_OFFSET and if you do, - the value defaults to the offset of the last byte - of data. - - - Suffix byte range - specification. Use LENGTH bytes to - specify the length of the data range. - - - The following forms of the header specify the following - ranges of data: - - - - - - Header - Range of object data - - - - - - Range: bytes=-5 - The last five bytes. - - - - Range: - bytes=10-14 - The five bytes of data after a 10-byte - offset. - - - Range: - bytes=10-14,-5 - A multi-part response that contains the five bytes of data after - a 10-byte offset and the last five - bytes. - The Content-Type of the - response is then - multipart/byteranges. - - - - - Range: - bytes=4-6 - Bytes 4 to 6 inclusive. - - - - Range: - bytes=2-2 - Byte 2, which is the third byte of the data. - - - - - Range: bytes=6- - Byte 6 and after. - - - - - Range: - bytes=1-3,2-5 - A multi-part response that contains - bytes 1 to 3 inclusive, and bytes 2 to 5 - inclusive. - The Content-Type of the - response is then - multipart/byteranges. - - - - - - Get Object Details HTTP Request - - - The object data is returned in the response body. Object - metadata is returned as HTTP headers. A status of - 2xx (between 200 and 299, - inclusive) indicates success; status 404 (Not Found) is - returned if no such object exists. - - Get Object Details HTTP Response - - - These examples include an object that contains 10 bytes - of data: 0123456789. - - Get Object Details HTTP Request Using Range - - - - Get Object Details HTTP Response When Using - Range - - - - Get Object Details HTTP Request Using Multiple - Ranges - - - - Get Object Details HTTP Response When Using - Multiple Ranges - - -
-
- Create or Update Object - &PUT; operations are used to write, or overwrite, an - object's content and metadata. - You can ensure end-to-end data integrity by including an - MD5 checksum of your object's data in the ETag header. You - are not required to include the ETag header, but it is - recommended to ensure that the storage system successfully - stored your object's content. - You can cause an object to expire after a certain date - by using the X-Delete-At or - X-Delete-After headers during an object - &PUT; operation. When Object Storage detects one of these - headers, the system automatically stops serving that - object at the specified time and shortly after the - expiration date, it removes the object from the storage - system. - The HTTP response will include the MD5 checksum of the - data written to the storage system. If you do not send the - ETag in the request, you should compare the value returned - with your content's MD5 locally to perform the end-to-end - data validation on the client side. For manifest objects, - the ETag is the MD5 checksum of the concatenated string of - ETags for each of the segments in the manifest. Refer to - Create Large - Objects for more information. - Objects can be assigned custom metadata by including - additional HTTP headers on the &PUT; request. - The object can be created with custom metadata via HTTP - headers identified with the X-Object-Meta- - prefix, or arbitrary headers set with the - allowed_headers option in the - object-server configuration. - - Create or Update Object HTTP Request - - [ ... ] - - No response body is returned. A status code of 201 - (Created) indicates a successful write; status 411 (Length - Required) denotes a missing Content-Length or - Content-Type header in the request. If - the MD5 checksum of the data written to the storage system - does NOT match the (optionally) supplied ETag value, a 422 - (Unprocessable Entity) response is returned. - - Create or Update Object HTTP Response - - -
- Chunked Transfer Encoding - Users can upload data without needing to know in - advance the amount of data to be uploaded. Users can - do this by specifying an HTTP header of - Transfer-Encoding: chunked and not - using a Content-Length header. A good use - of this feature would be doing a DB dump, piping the - output through gzip, then piping the data directly - into OpenStack Object Storage without having to buffer - the data to disk to compute the file size. If users - attempt to upload more than 5GB with this method, the - server will close the TCP/IP connection after 5GB and - purge the customer data from the system. Users must - take responsibility for ensuring the data they - transfer will be less than 5GB or for splitting it - into 5GB chunks, each in its own storage object. If - you have files that are larger than 5GB see . - - Upload Unspecified Quantity of Content HTTP - Request - - - - Upload Unspecified Quantity of Content HTTP - Response - - -
-
-
- 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: - - - Divide your content into pieces and upload each - piece into its own object. These objects are known - as segment objects. - - - Create a manifest object. A manifest object - "points to" the segment objects. - - - 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 - 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. - The Content-Length is the total size of all segment - objects and the ETag is calculated by taking the ETag - value of each segment, concatenating them together and - then returning the MD5 checksum of the result. - - If you use the © operation using a manifest - object as the source, the new object is a "normal" - object (not segmented). If the total size of the - source segment objects exceeds 5 GB, the © - operation fails. However, as explained later, you can - make a duplicate of the manifest object. This new - object can be larger than 5 GB. - - The manifest object type are: - - - Static large objects. The manifest object - content is an ordered list of the names of the - segment objects in json format. - - - Dynamic large objects. The manifest object has - no content. However, it has - X-Object-Manifest metadata. The - value of this is - <container>/<prefix>, where - <container> is the name of the - container where the segment objects are stored and - <prefix> is a string that all - the segment objects have in common. - - - While both types of manifest objects have similar - behavior, there are differences as explained in the - following table. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Comparison of Static and Dynamic Large - Objects
FeatureStatic Large ObjectDynamic Large Object
End-to-end integrityAssured. The list of segments includes the MD5 - checksum (ETag) of each segment. You cannot - upload the manifest object if the ETag in the - list differs from the segment object already - uploaded. If a segment is somehow lost, an - attempt to download the manifest object will - result in an error.Not guaranteed. The eventual consistency model - means that although you may have uploaded a - segment object, it may not appear in the - container listing until later. If you download - the manifest before it appears in the - container, it will not form part of the - content returned in response to a &GET; - request.
Upload orderThe segment objects must be uploaded before - the manifest object.You can upload manifest and segment objects in - any order. You are recommended to upload the - manifest object after the segments in case a - premature download of the manifest occurs. - However, this is not enforced.
Removal or addition of segment objectsYou cannot add or remove segment objects from - the manifest. However, you can create a - completely new manifest object of the same - name with a different manifest list.You can upload new segment objects or remove - existing segments --- the names must simply - match the <prefix> supplied in - X-Object-Manifest.
Segment object size and numberSegment objects must be at least 1MB in size - (by default). The final segment object can be - any size. At most 1000 segments are supported - (by default).Segment objects can be of any size.
Segment object container nameThe manifest list includes the container name - of each object, i.e., segment objects may be - in different containers.All segment objects must be in the same - container
Manifest Object MetadataThe object has - X-Static-Large-Object set to - true. You do not set this - metadata directly. Instead the system sets it - when you &PUT; a static manifest object.The X-Object-Manifest value is - the <container>/<prefix> - indicating where the segment objects are - located. You supply this request header in the - &PUT; operation
Making a copy of the manifest objectTo make a copy of the manifest object, include - the ?multipart-manifest=get query - string with the © operation. The new - object contains the same manifest as the - original. The segment objects are not copied. - Instead, both the original and new manifest - objects share the same set of segment - objects.The © operation does not create a - manifest object. To duplicate a manifest - object, use the &GET; operation to read the - value of X-Object-Manifest and - use this value in the - X-Object-Manifest request - header in a &PUT; operation. This creates a - new manifest object that shares the same set - of segment objects as the original manifest - object.
-
- 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 - manifest object telling OpenStack Object Storage how - to find the segments of the large object. The segments - remain individually addressable, but retrieving the - manifest object streams all the segments concatenated. - There is no limit to the number of segments that can - be a part of a single large object. - To ensure the download works correctly, you must - upload all the object segments to the same container - and ensure that each object name is prefixed in such a - way that it sorts in the order in which it should be - concatenated. You also create and upload a manifest - file. The manifest file is a zero-byte file with the - extra X-Object-Manifest: - <container>/<prefix> header, where - <container> is the container the object segments - are in and <prefix> is the common prefix for all - the segments. The container and common prefix must be - UTF-8 encoded and URL-encoded in the X-Object-Manifest - header. - It is best to upload all the segments first and then - create or update the manifest. With this method, the - full object will not be available for downloading - until the upload is complete. Also, you can upload a - new set of segments to a second location and then - update the manifest to point to this new location. - During the upload of the new segments, the original - manifest will still be available to download the first - set of segments. - - Upload Segment of Large Object HTTP - Request - - - - Upload Segment of Large Object HTTP - Response - s - - No response body is returned. A status code of 2xx - (between 200 and 299, inclusive) indicates a - successful write; status 411 (Length Required) denotes - a missing Content-Length or - Content-Type header in the request. - If the MD5 checksum of the data written to the storage - system does NOT match the (optionally) supplied ETag - value, a 422 (Unprocessable Entity) response is - returned. - 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 HTTP - Response - w - - Next, upload the manifest you created that indicates - the container the object segments reside within. Note - that uploading additional segments after the manifest - is created will cause the concatenated object to be - that much larger but you do not need to recreate the - manifest file for subsequent additional - segments. - - Upload Manifest HTTP Request - - - - Upload Manifest HTTP Response - - - The response's Content-Type for a &GET; or &HEAD; on - the manifest will be the same as the Content-Type set - during the PUT request that created the manifest. You - can easily change the Content-Type by reissuing the - &PUT; request. -
-
- 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 - response header returned by the&PUT; - operation. Alternatively, you can calculate - the MD5 checksum of the segment prior to - uploading and include this in the - 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 - this is a manifest object by including the - ?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: - - - path - this is the container - and object name in the following format: - <container-name>/<object-name> - - - etag - this is the MD5 checksum - of the content of the segment object. This - must match the ETag of that - object. - - - size_bytes - this is the size - of the segment object. This must match the - Content-Length of that - object - - - - 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 - conform to a specific pattern, in contrast to - dynamic large objects. - - - 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 - Content-Type request header and - custom object metadata. - When the &PUT; operation sees the - ?multipart-manifest=put query string, - it reads the request body and verifies that each - segment object exists and that the sizes and ETags - match. If there is a mismatch, the &PUT;operation will - fail. - If everything matches, the manifest object is - created. The X-Static-Large-Object - metadata is set to true indicating that - this is a static object manifest. - Normally when you perform a &GET; operation on the - manifest object, the response body contains the - concatenated content of the segment objects. To - download the manifest list, use the query string - ?multipart-manifest=get. The - resulting list will not be identically formatted as - 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 - objects are not affected. However, if you add the - query parameter - ?multipart-manifest=delete, the - segment objects are deleted and if all are - successfully deleted, the manifest object is also - deleted. - To change the manifest, use a &PUT; operation with - the ?multipart-manifest=put query string. - This will create a new manifest - object. You may also update the object metadata in the - usual way. -
-
-
- 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 - those assigned by Object Storage API requests. These - headers are supported with the Object Storage API. You can - read more about the definition of the Access-Control- - response headers and Origin response header at www.w3.org/TR/access-control/. - - - - - - - - - - - - - - - - - - - - - - - - -
Supported Headers
MetadataUse
X-Container-Meta-Access-Control-Allow-OriginOrigins to be allowed to make Cross Origin Requests, space separated.
X-Container-Meta-Access-Control-Max-AgeMax age for the Origin to hold the preflight results.
X-Container-Meta-Access-Control-Expose-HeadersHeaders exposed to the user agent (e.g. browser) in the the actual request response. Space separated.
- - CORS metadata is held on the container only. The values given apply to the container itself and all objects within it. - - 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 - repository are indeed from the correct - origination: - - - You can find more details in the Swift Documentation. -
-
- Enabling File Compression with the Content-Encoding - Header - The Content-Encoding header allows 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 - In the example, the content-encoding header is - assigned with an attachment type that indicates how - the file should be downloaded: - - -
-
- Enabling 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 - In the example, the content-encoding header is - assigned with an attachment type that indicates how - the file should be downloaded. - - -
-
- Expiring 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 - &POST; on the object, it is scheduled for deletion. This - feature is helpful for objects you do not want to - permanently store, such as log files, recurring full - backups of a dataset, or documents or images you know will - 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. - 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 - server that receives the request converts this header into - an X-Delete-At header and calculates the - deletion time using its current time plus the value given - in seconds. - For existing objects that you want to assign expiration - headers to, use the &POST; operation. - - Delete Object at HTTP Request - 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 http://www.epochconverter.com/ for example - timestamps and a batch converter. - - - - 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. - - - -
- -
- - 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 - can be used on any type of content. It is strongly - recommended that you put non-current objects in a - container apart from where the current versions exist. - Once you enable Object Versioning on a container (such as - a "current version" container), &PUT;s to existing objects - in that container copy the prior object to a separate - "non-current version" container. Each of the non-current - versions of an object has a time stamp appended to it, so - you know when it was created. - To enable object versioning, your cloud provider has to - set allow_versions to TRUE in - their container config. Then, create a container where - your non-current versions will be written. Next, set the - metadata X-Versions-Location header on the - container that holds the current versions of your objects. - Set the metadata header to point to the new non-current - version container you created. The name of the container - must be UTF-8 encoded and then URL-encoded before putting - into the X-Versions-Location header. This is - where your non-current versions will be stored. Once this - is done, each object in your current-version container - will have Object Versioning enabled; changes to the - objects automatically create non-current versions in the - separate container. - Nothing is written to the non-current version container - when you initially &PUT; an object into the - current-version container. Only when you make edits to the - objects via &PUT; will you create non-current versions. - These non-current versions are labeled according to the - schema below. - - Naming Schema: Non-current versions - are assigned the name - <length><object_name>/<timestamp>, where - length is the 3-character zero-padded hexadecimal - character length of the <object_name> and - <timestamp> is when the it was initially created as - a current version. - Any return status in the 2xx range, such as 202 - (Accepted), denotes success. Status codes in the 4xx or - 5xx range denote failure. You should retry your request if - you receive an error. Please note, however, that if you - have specified a container that does not exist as your - non-current version container, a status of 412 - (Precondition Failed) returns when you edit the versioned - object. If you receive this error, check that the - container exists. - A &GET; to a versioned object returns the current - version of the object without having to do any request - redirects or metadata lookups. - A &POST; to a versioned object only updates the object's - metadata; it does not create a new version of the object. - In other words, new versions are only created when the - content of the object changes. - A &DELETE; to a versioned object removes the current - version of the object and replaces it with the next-most - current version, moving it from the non-current container - to the current. This next-most current version carries - with it any metadata last set on it. If want to completely - remove an object and you have five total versions of it, - you must &DELETE; it five times. - - A large-object manifest file cannot be versioned, - but it may point to versioned segments. - - To turn off Object Versioning on your current version - container, remove its X-Versions-Location - metadata by sending an empty key value. - - 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 - X-Versions-Location header. In this - example, this container is named "current". You can - also add the X-Versions-Location header - to an existing container. In this example, the name of - the container is “versions”; the location for the - current version is the container "current". - Create a container named versions. - $ curl -i -XPUT -H "X-Auth-Token: <token>" http://<storage_url>/versions - Create a container named current with the - X-Versions-Location header that - references "versions". - $ curl -i -XPUT -H "X-Auth-Token: <token>" \ - -H "X-Versions-Location: versions" http://<storage_url>/current - Create an object (the first version): - $ curl -i -XPUT --data-binary 1 -H "X-Auth-Token: <token>" \ - http://<storage_url>/current/myobject - Now create a new version of that object: - $ curl -i -XPUT --data-binary 2 -H "X-Auth-Token: <token>" \ - http://<storage_url>/current/myobject - See a listing of the older versions of the - object: - $ curl -i -H "X-Auth-Token: <token>" \ - http://<storage_url>/versions?prefix=008myobject/ - Now delete the current version of the object and see - that the older version is gone: - $ curl -i -XDELETE -H "X-Auth-Token: <token>" \ - http://<storage_url>/current/myobject - $ curl -i -H "X-Auth-Token: <token>" \ - http://<storage_url>/versions?prefix=008myobject/ - -
-
- Copy Object - Suppose you upload a file with the wrong object name or - content type, or you needed to move some objects to - another container. Without a server-side copy feature, you - would need to repeat uploading the same content and then - delete the existing object. With server-side object copy, - you can save the step of re-uploading the content and thus - also save the associated bandwidth charges, if any were to - apply. - There are two ways to copy an existing object to another - object in OpenStack Object Storage. One way is to do a - &PUT; to the new object (the target) location, but add the - “X-Copy-From” header to designate the - source of the data. The header value should be the - container and object name of the source object in the form - of “/container/object”. The container and object name must - be UTF-8 encoded and then URL-encoded. Also, the - X-Copy-From &PUT; requests require a - Content-Length header, even if it is zero (0). - - Object Copy Method 1 - - - The second way to do an object copy is similar. Do a - © to the existing object, and include the - “Destination” header to specify the target of the copy. - The header value is the container and new object name in - the form of “/container/object”. - - Object Copy Method 2 - - - With both of these methods, the destination container - must exist before attempting the copy. - If the source object is a manifest object, i.e., an - object with X-Object-Manifest or - X-Static-Large-Object:true metadata, the - copy operation concatenates the segment objects when - making the content for the destination object. You cannot - copy an object larger than 5GB (by default). Refer to - Large Object - Creation for more information about large - objects. - However, for a Static Large Object manifest, it is possible - to copy the manifest so that the destination becomes a - manifest object. Use the - ?multipart-manifest=get query string to - indicate that you want a copy of the manifest object. The - new object will contain the same manifest as the original. - The segment objects are not copied. Instead, both the - original and new manifest objects share the same set of - segment objects. - If you wanted to move the object rather than copy it, - you need to send a &DELETE; request to the old object. A - move is simply a © + &DELETE;. All metadata is - preserved during the object copy. Note that you can set - metadata on the request to copy the object (either the - &PUT; or the ©) and the metadata will overwrite any - conflicting keys on the target (new) object. One - interesting use case is to copy an object to itself and - set the content type to a new value. This is the only way - to change the content type of an existing object. -
-
- Delete Object - &DELETE; operations on an object are used to permanently - remove an object from the storage system (metadata and - data). - Deleting an object is processed immediately at the time - of the request. Any subsequent &GET;, &HEAD;, &POST;, or - &DELETE; operations will return a 404 (Not Found) - error. - For static large - object manifests, you can add the query - parameter ?multipart-manifest=delete. The - segment objects are deleted and if all are successfully - deleted, the manifest object is also deleted. - Objects with the X-Delete-At or - X-Delete-After header assigned are - deleted within one day of the expiration time and the - object is not served immediately after the expiration - time. Refer to Expiring Objects for more details. - - Object Delete HTTP Request - - - No response body is returned. A status code of 2xx ( - between 200 and 299, inclusive) indicates success; status - code 404 (Not Found) is returned when the object does not - exist. - - Object Delete HTTP Response - - -
-
- Get Object Metadata - &HEAD; operations on an object are used to retrieve - object metadata and other standard HTTP headers. - The only required header to be sent in the request is - the authorization token. - - Get Object Metadata HTTP Request - - - No response body is returned. Metadata is returned as - HTTP headers. A status code of 2xx (between 200 and 299, - inclusive) indicates success; status 404 (Not Found) is - returned when the object does not exist. - - Get Object Metadata HTTP Response - - -
-
- Update Object Metadata - &POST; operations against an object name are used to set - and overwrite arbitrary key/value metadata or to assign - headers not already assigned such as - X-Delete-At or - X-Delete-After for expiring objects. You - cannot use the &POST; operation to change any of the - object's other headers such as Content-Type, - ETag, etc. It is not used to upload - storage objects (see &PUT;). Also refer to copying an object when - you need to update metadata or other headers such as - Content-Type or CORS headers. - Key names must be prefixed with - X-Object-Meta-. A &POST; request will - delete all existing metadata added with a previous - &PUT;/&POST;. - - Update Object Metadata HTTP Request - - - No response body is returned. A status code of 2xx - (between 200 and 299, inclusive) indicates success; status - 404 (Not Found) is returned if the requested object does - not exist. - - Update Object Metadata HTTP Response - - -
+ + + + + + + + + + + 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_object_api_tempurl.xml b/openstack-object-storage-dev/section_object-api-tempurl.xml similarity index 97% rename from openstack-object-storage-dev/section_object_api_tempurl.xml rename to openstack-object-storage-dev/section_object-api-tempurl.xml index 32c4e6d..3eb2124 100644 --- a/openstack-object-storage-dev/section_object_api_tempurl.xml +++ b/openstack-object-storage-dev/section_object-api-tempurl.xml @@ -14,10 +14,12 @@ xmlns:m="http://www.w3.org/1998/Math/MathML" xmlns:html="http://www.w3.org/1999/xhtml" xmlns:db="http://docbook.org/ns/docbook" version="5.0" - xml:id="object-storage-tempurl"> + xml:id="tempurl"> Temporary URL middleware - A temporary URL gives users temporary access to objects. For + To discover whether your Object Storage system supports + this feature, see . Alternatively, check with your service provider.A temporary URL gives users temporary access to objects. For example, a website might want to provide a link to download a large object in Object Storage, but the Object Storage account has no public access. The website can generate a URL that diff --git a/openstack-object-storage-dev/section_object-api-versioning.xml b/openstack-object-storage-dev/section_object-api-versioning.xml new file mode 100644 index 0000000..056e139 --- /dev/null +++ b/openstack-object-storage-dev/section_object-api-versioning.xml @@ -0,0 +1,184 @@ + + + + + + +COPY'> +GET'> +HEAD'> +PUT'> +POST'> +DELETE'> +]> +
+ Object versioning + You can store multiple versions of your content so that you + can recover from unintended overwrites. Object versioning is + an easy way to implement version control, which you can use + with any type of content. + + You cannot version a large-object manifest file, but the + large-object manifest file can point to versioned + segments. + + It is strongly recommended that you put non-current objects + in a different container than the container where current + object versions reside. + + To enable and use object versioning + + To enable object versioning, ask your cloud provider + to set the option to + TRUE in the container + configuration file. + + + Create an archive container to + store older versions of objects. + Create the archive + container: + # curl -i $publicURL/archive -X PUT -H "Content-Length: 0" -H "X-Auth-Token: $token" + HTTP/1.1 201 Created +Content-Length: 0 +Content-Type: text/html; charset=UTF-8 +X-Trans-Id: tx46f8c29050834d88b8d7e-0052e1859d +Date: Thu, 23 Jan 2014 21:11:57 GMT + + + Create a current container to + store current versions of objects. + Include the X-Versions-Location + header. This header defines the container that holds + the non-current versions of your objects. You must + UTF-8-encode and then URL-encode the container name + before you include it in the + X-Versions-Location header. This + header enables object versioning for all objects in + the current container. Changes to + objects in the current container + automatically create non-current versions in the + archive container. + Create the current + container: + # curl -i $publicURL/current -X PUT -H "Content-Length: 0" -H "X-Auth-Token: $token" -H "X-Versions-Location: archive" + HTTP/1.1 201 Created +Content-Length: 0 +Content-Type: text/html; charset=UTF-8 +X-Trans-Id: txb91810fb717347d09eec8-0052e18997 +Date: Thu, 23 Jan 2014 21:28:55 GMT + + + Create the first version of an object in the + current container: + # curl -i $publicURL/current/my_object --data-binary 1 -X PUT -H "Content-Length: 0" -H "X-Auth-Token: $token" + HTTP/1.1 201 Created +Last-Modified: Thu, 23 Jan 2014 21:31:22 GMT +Content-Length: 0 +Etag: d41d8cd98f00b204e9800998ecf8427e +Content-Type: text/html; charset=UTF-8 +X-Trans-Id: tx5992d536a4bd4fec973aa-0052e18a2a +Date: Thu, 23 Jan 2014 21:31:22 GMT + Nothing is written to the non-current version + container when you initially &PUT; an object in the + current container. However, + subsequent &PUT; requests that edit an object trigger + the creation of a version of that object in the + archive container. + These non-current versions are named as + follows: + <length><object_name><timestamp> + Where length is the 3-character, zero-padded + hexadecimal character length of the object, + <object_name> is the object name, and + <timestamp> is the time when the object was + initially created as a current version. + + + Create a second version of the object in the + current container: + # curl -i $publicURL/current/my_object --data-binary 2 -X PUT -H "Content-Length: 0" -H "X-Auth-Token: $token" + HTTP/1.1 201 Created +Last-Modified: Thu, 23 Jan 2014 21:41:32 GMT +Content-Length: 0 +Etag: d41d8cd98f00b204e9800998ecf8427e +Content-Type: text/html; charset=UTF-8 +X-Trans-Id: tx468287ce4fc94eada96ec-0052e18c8c +Date: Thu, 23 Jan 2014 21:41:32 GMT + + + Issue a &GET; request to a versioned object to get + the current version of the object. You do not have to + do any request redirects or metadata lookups. + List older versions of the object in the + archive container: + # curl -i $publicURL/archive?prefix=009my_object -X GET -H "X-Auth-Token: $token" + HTTP/1.1 200 OK +Content-Length: 30 +X-Container-Object-Count: 1 +Accept-Ranges: bytes +X-Timestamp: 1390513280.79684 +X-Container-Bytes-Used: 0 +Content-Type: text/plain; charset=utf-8 +X-Trans-Id: tx9a441884997542d3a5868-0052e18d8e +Date: Thu, 23 Jan 2014 21:45:50 GMT + +009my_object/1390512682.92052 + + A &POST; request to a versioned object updates + only the metadata for the object and does not + create a new version of the object. New versions + are created only when the content of the object + changes. + + + + Issue a &DELETE; request to a versioned object to + remove the current version of the object and replace + it with the next-most current version in the + non-current container. + # curl -i $publicURL/current/my_object -X DELETE -H "X-Auth-Token: $token" + HTTP/1.1 204 No Content +Content-Length: 0 +Content-Type: text/html; charset=UTF-8 +X-Trans-Id: tx006d944e02494e229b8ee-0052e18edd +Date: Thu, 23 Jan 2014 21:51:25 GMT + List objects in the archive + container to show that the archived object was moved + back to the current + container: + # curl -i $publicURL/archive?prefix=009my_object -X GET -H "X-Auth-Token: $token" + HTTP/1.1 204 No Content +Content-Length: 0 +X-Container-Object-Count: 0 +Accept-Ranges: bytes +X-Timestamp: 1390513280.79684 +X-Container-Bytes-Used: 0 +Content-Type: text/html; charset=UTF-8 +X-Trans-Id: tx044f2a05f56f4997af737-0052e18eed +Date: Thu, 23 Jan 2014 21:51:41 GMT + This next-most current version carries with it any + metadata last set on it. If want to completely remove + an object and you have five versions of it, you must + &DELETE; it five times. + + + To disable object versioning for the + current container, remove its + X-Versions-Location metadata + header by sending an empty key value. + # curl -i $publicURL/current -X PUT -H "Content-Length: 0" -H "X-Auth-Token: $token" -H "X-Versions-Location: " + HTTP/1.1 202 Accepted +Content-Length: 76 +Content-Type: text/html; charset=UTF-8 +X-Trans-Id: txe2476de217134549996d0-0052e19038 +Date: Thu, 23 Jan 2014 21:57:12 GMT + +<html><h1>Accepted</h1><p>The request is accepted for processing.</p></html> + + +