]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | ====================== |
2 | Container Operations | |
3 | ====================== | |
4 | ||
5 | A container is a mechanism for storing data objects. An account may | |
6 | have many containers, but container names must be unique. This API enables a | |
7 | client to create a container, set access controls and metadata, | |
8 | retrieve a container's contents, and delete a container. Since this API | |
9 | makes requests related to information in a particular user's account, all | |
10 | requests in this API must be authenticated unless a container's access control | |
11 | is deliberately made publicly accessible (i.e., allows anonymous requests). | |
12 | ||
13 | .. note:: The Amazon S3 API uses the term 'bucket' to describe a data container. | |
14 | When you hear someone refer to a 'bucket' within the Swift API, the term | |
15 | 'bucket' may be construed as the equivalent of the term 'container.' | |
16 | ||
17 | One facet of object storage is that it does not support hierarchical paths | |
18 | or directories. Instead, it supports one level consisting of one or more | |
19 | containers, where each container may have objects. The RADOS Gateway's | |
20 | Swift-compatible API supports the notion of 'pseudo-hierarchical containers,' | |
21 | which is a means of using object naming to emulate a container (or directory) | |
22 | hierarchy without actually implementing one in the storage system. You may | |
23 | name objects with pseudo-hierarchical names | |
24 | (e.g., photos/buildings/empire-state.jpg), but container names cannot | |
25 | contain a forward slash (``/``) character. | |
26 | ||
27 | ||
28 | Create a Container | |
29 | ================== | |
30 | ||
31 | To create a new container, make a ``PUT`` request with the API version, account, | |
32 | and the name of the new container. The container name must be unique, must not | |
33 | contain a forward-slash (/) character, and should be less than 256 bytes. You | |
34 | may include access control headers and metadata headers in the request. The | |
35 | operation is idempotent; that is, if you make a request to create a container | |
36 | that already exists, it will return with a HTTP 202 return code, but will not | |
37 | create another container. | |
38 | ||
39 | ||
40 | Syntax | |
41 | ~~~~~~ | |
42 | ||
43 | :: | |
44 | ||
45 | PUT /{api version}/{account}/{container} HTTP/1.1 | |
46 | Host: {fqdn} | |
47 | X-Auth-Token: {auth-token} | |
48 | X-Container-Read: {comma-separated-uids} | |
49 | X-Container-Write: {comma-separated-uids} | |
50 | X-Container-Meta-{key}: {value} | |
51 | ||
52 | ||
53 | Headers | |
54 | ~~~~~~~ | |
55 | ||
56 | ``X-Container-Read`` | |
57 | ||
58 | :Description: The user IDs with read permissions for the container. | |
59 | :Type: Comma-separated string values of user IDs. | |
60 | :Required: No | |
61 | ||
62 | ``X-Container-Write`` | |
63 | ||
64 | :Description: The user IDs with write permissions for the container. | |
65 | :Type: Comma-separated string values of user IDs. | |
66 | :Required: No | |
67 | ||
68 | ``X-Container-Meta-{key}`` | |
69 | ||
70 | :Description: A user-defined meta data key that takes an arbitrary string value. | |
71 | :Type: String | |
72 | :Required: No | |
73 | ||
74 | ||
75 | HTTP Response | |
76 | ~~~~~~~~~~~~~ | |
77 | ||
78 | If a container with the same name already exists, and the user is the | |
79 | container owner then the operation will succeed. Otherwise the operation | |
80 | will fail. | |
81 | ||
82 | ``409`` | |
83 | ||
84 | :Description: The container already exists under a different user's ownership. | |
85 | :Status Code: ``BucketAlreadyExists`` | |
86 | ||
87 | ||
88 | ||
89 | ||
90 | List a Container's Objects | |
91 | ========================== | |
92 | ||
93 | To list the objects within a container, make a ``GET`` request with the with the | |
94 | API version, account, and the name of the container. You can specify query | |
95 | parameters to filter the full list, or leave out the parameters to return a list | |
96 | of the first 10,000 object names stored in the container. | |
97 | ||
98 | ||
99 | Syntax | |
100 | ~~~~~~ | |
101 | ||
102 | :: | |
103 | ||
104 | GET /{api version}/{container} HTTP/1.1 | |
105 | Host: {fqdn} | |
106 | X-Auth-Token: {auth-token} | |
107 | ||
108 | ||
109 | Parameters | |
110 | ~~~~~~~~~~ | |
111 | ||
112 | ``format`` | |
113 | ||
114 | :Description: Defines the format of the result. | |
115 | :Type: String | |
116 | :Valid Values: ``json`` | ``xml`` | |
117 | :Required: No | |
118 | ||
119 | ``prefix`` | |
120 | ||
121 | :Description: Limits the result set to objects beginning with the specified prefix. | |
122 | :Type: String | |
123 | :Required: No | |
124 | ||
125 | ``marker`` | |
126 | ||
127 | :Description: Returns a list of results greater than the marker value. | |
128 | :Type: String | |
129 | :Required: No | |
130 | ||
131 | ``limit`` | |
132 | ||
133 | :Description: Limits the number of results to the specified value. | |
134 | :Type: Integer | |
135 | :Valid Range: 0 - 10,000 | |
136 | :Required: No | |
137 | ||
138 | ``delimiter`` | |
139 | ||
140 | :Description: The delimiter between the prefix and the rest of the object name. | |
141 | :Type: String | |
142 | :Required: No | |
143 | ||
144 | ``path`` | |
145 | ||
146 | :Description: The pseudo-hierarchical path of the objects. | |
147 | :Type: String | |
148 | :Required: No | |
149 | ||
1adf2230 AA |
150 | ``allow_unordered`` |
151 | ||
152 | :Description: Allows the results to be returned unordered to reduce computation overhead. Cannot be used with ``delimiter``. | |
153 | :Type: Boolean | |
154 | :Required: No | |
155 | :Non-Standard Extension: Yes | |
156 | ||
7c673cae FG |
157 | |
158 | Response Entities | |
159 | ~~~~~~~~~~~~~~~~~ | |
160 | ||
161 | ``container`` | |
162 | ||
163 | :Description: The container. | |
164 | :Type: Container | |
165 | ||
166 | ``object`` | |
167 | ||
168 | :Description: An object within the container. | |
169 | :Type: Container | |
170 | ||
171 | ``name`` | |
172 | ||
173 | :Description: The name of an object within the container. | |
174 | :Type: String | |
175 | ||
176 | ``hash`` | |
177 | ||
178 | :Description: A hash code of the object's contents. | |
179 | :Type: String | |
180 | ||
181 | ``last_modified`` | |
182 | ||
183 | :Description: The last time the object's contents were modified. | |
184 | :Type: Date | |
185 | ||
186 | ``content_type`` | |
187 | ||
188 | :Description: The type of content within the object. | |
189 | :Type: String | |
190 | ||
191 | ||
192 | ||
193 | Update a Container's ACLs | |
194 | ========================= | |
195 | ||
196 | When a user creates a container, the user has read and write access to the | |
197 | container by default. To allow other users to read a container's contents or | |
198 | write to a container, you must specifically enable the user. | |
199 | You may also specify ``*`` in the ``X-Container-Read`` or ``X-Container-Write`` | |
200 | settings, which effectively enables all users to either read from or write | |
201 | to the container. Setting ``*`` makes the container public. That is it | |
202 | enables anonymous users to either read from or write to the container. | |
203 | ||
204 | ||
205 | Syntax | |
206 | ~~~~~~ | |
207 | ||
208 | :: | |
209 | ||
210 | POST /{api version}/{account}/{container} HTTP/1.1 | |
211 | Host: {fqdn} | |
212 | X-Auth-Token: {auth-token} | |
213 | X-Container-Read: * | |
214 | X-Container-Write: {uid1}, {uid2}, {uid3} | |
215 | ||
216 | Request Headers | |
217 | ~~~~~~~~~~~~~~~ | |
218 | ||
219 | ``X-Container-Read`` | |
220 | ||
221 | :Description: The user IDs with read permissions for the container. | |
222 | :Type: Comma-separated string values of user IDs. | |
223 | :Required: No | |
224 | ||
225 | ``X-Container-Write`` | |
226 | ||
227 | :Description: The user IDs with write permissions for the container. | |
228 | :Type: Comma-separated string values of user IDs. | |
229 | :Required: No | |
230 | ||
231 | ||
232 | Add/Update Container Metadata | |
233 | ============================= | |
234 | ||
235 | To add metadata to a container, make a ``POST`` request with the API version, | |
236 | account, and container name. You must have write permissions on the | |
237 | container to add or update metadata. | |
238 | ||
239 | Syntax | |
240 | ~~~~~~ | |
241 | ||
242 | :: | |
243 | ||
244 | POST /{api version}/{account}/{container} HTTP/1.1 | |
245 | Host: {fqdn} | |
246 | X-Auth-Token: {auth-token} | |
247 | X-Container-Meta-Color: red | |
248 | X-Container-Meta-Taste: salty | |
249 | ||
250 | Request Headers | |
251 | ~~~~~~~~~~~~~~~ | |
252 | ||
253 | ``X-Container-Meta-{key}`` | |
254 | ||
255 | :Description: A user-defined meta data key that takes an arbitrary string value. | |
256 | :Type: String | |
257 | :Required: No | |
258 | ||
259 | ||
260 | ||
261 | Delete a Container | |
262 | ================== | |
263 | ||
264 | To delete a container, make a ``DELETE`` request with the API version, account, | |
265 | and the name of the container. The container must be empty. If you'd like to check | |
266 | if the container is empty, execute a ``HEAD`` request against the container. Once | |
c07f9fc5 | 267 | you have successfully removed the container, you will be able to reuse the container name. |
7c673cae FG |
268 | |
269 | Syntax | |
270 | ~~~~~~ | |
271 | ||
272 | :: | |
273 | ||
274 | DELETE /{api version}/{account}/{container} HTTP/1.1 | |
275 | Host: {fqdn} | |
276 | X-Auth-Token: {auth-token} | |
277 | ||
278 | ||
279 | HTTP Response | |
280 | ~~~~~~~~~~~~~ | |
281 | ||
282 | ``204`` | |
283 | ||
284 | :Description: The container was removed. | |
285 | :Status Code: ``NoContent`` | |
286 |