]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | =================== |
2 | Object Operations | |
3 | =================== | |
4 | ||
5 | An object is a container for storing data and metadata. A container may | |
6 | have many objects, but the object names must be unique. This API enables a | |
7 | client to create an object, set access controls and metadata, retrieve an | |
8 | object's data and metadata, and delete an object. Since this API makes requests | |
9 | related to information in a particular user's account, all requests in this API | |
10 | must be authenticated unless the container or object's access control is | |
11 | deliberately made publicly accessible (i.e., allows anonymous requests). | |
12 | ||
13 | ||
14 | Create/Update an Object | |
15 | ======================= | |
16 | ||
17 | To create a new object, make a ``PUT`` request with the API version, account, | |
18 | container name and the name of the new object. You must have write permission | |
19 | on the container to create or update an object. The object name must be | |
20 | unique within the container. The ``PUT`` request is not idempotent, so if you | |
21 | do not use a unique name, the request will update the object. However, you may | |
22 | use pseudo-hierarchical syntax in your object name to distinguish it from | |
23 | another object of the same name if it is under a different pseudo-hierarchical | |
24 | directory. You may include access control headers and metadata headers in the | |
25 | request. | |
26 | ||
27 | ||
28 | Syntax | |
29 | ~~~~~~ | |
30 | ||
31 | :: | |
32 | ||
33 | PUT /{api version}/{account}/{container}/{object} HTTP/1.1 | |
34 | Host: {fqdn} | |
35 | X-Auth-Token: {auth-token} | |
36 | ||
37 | ||
38 | Request Headers | |
39 | ~~~~~~~~~~~~~~~ | |
40 | ||
41 | ``ETag`` | |
42 | ||
43 | :Description: An MD5 hash of the object's contents. Recommended. | |
44 | :Type: String | |
45 | :Required: No | |
46 | ||
47 | ||
48 | ``Content-Type`` | |
49 | ||
50 | :Description: The type of content the object contains. | |
51 | :Type: String | |
52 | :Required: No | |
53 | ||
54 | ||
55 | ``Transfer-Encoding`` | |
56 | ||
57 | :Description: Indicates whether the object is part of a larger aggregate object. | |
58 | :Type: String | |
59 | :Valid Values: ``chunked`` | |
60 | :Required: No | |
61 | ||
62 | ||
63 | Copy an Object | |
64 | ============== | |
65 | ||
66 | Copying an object allows you to make a server-side copy of an object, so that | |
67 | you don't have to download it and upload it under another container/name. | |
68 | To copy the contents of one object to another object, you may make either a | |
69 | ``PUT`` request or a ``COPY`` request with the API version, account, and the | |
70 | container name. For a ``PUT`` request, use the destination container and object | |
71 | name in the request, and the source container and object in the request header. | |
72 | For a ``Copy`` request, use the source container and object in the request, and | |
73 | the destination container and object in the request header. You must have write | |
74 | permission on the container to copy an object. The destination object name must be | |
75 | unique within the container. The request is not idempotent, so if you do not use | |
76 | a unique name, the request will update the destination object. However, you may | |
77 | use pseudo-hierarchical syntax in your object name to distinguish the destination | |
78 | object from the source object of the same name if it is under a different | |
79 | pseudo-hierarchical directory. You may include access control headers and metadata | |
80 | headers in the request. | |
81 | ||
82 | Syntax | |
83 | ~~~~~~ | |
84 | ||
85 | :: | |
86 | ||
87 | PUT /{api version}/{account}/{dest-container}/{dest-object} HTTP/1.1 | |
88 | X-Copy-From: {source-container}/{source-object} | |
89 | Host: {fqdn} | |
90 | X-Auth-Token: {auth-token} | |
91 | ||
92 | ||
93 | or alternatively: | |
94 | ||
95 | :: | |
96 | ||
97 | COPY /{api version}/{account}/{source-container}/{source-object} HTTP/1.1 | |
98 | Destination: {dest-container}/{dest-object} | |
99 | ||
100 | Request Headers | |
101 | ~~~~~~~~~~~~~~~ | |
102 | ||
103 | ``X-Copy-From`` | |
104 | ||
105 | :Description: Used with a ``PUT`` request to define the source container/object path. | |
106 | :Type: String | |
107 | :Required: Yes, if using ``PUT`` | |
108 | ||
109 | ||
110 | ``Destination`` | |
111 | ||
112 | :Description: Used with a ``COPY`` request to define the destination container/object path. | |
113 | :Type: String | |
114 | :Required: Yes, if using ``COPY`` | |
115 | ||
116 | ||
117 | ``If-Modified-Since`` | |
118 | ||
119 | :Description: Only copies if modified since the date/time of the source object's ``last_modified`` attribute. | |
120 | :Type: Date | |
121 | :Required: No | |
122 | ||
123 | ||
124 | ``If-Unmodified-Since`` | |
125 | ||
126 | :Description: Only copies if not modified since the date/time of the source object's ``last_modified`` attribute. | |
127 | :Type: Date | |
128 | :Required: No | |
129 | ||
130 | ``Copy-If-Match`` | |
131 | ||
132 | :Description: Copies only if the ETag in the request matches the source object's ETag. | |
133 | :Type: ETag. | |
134 | :Required: No | |
135 | ||
136 | ||
137 | ``Copy-If-None-Match`` | |
138 | ||
139 | :Description: Copies only if the ETag in the request does not match the source object's ETag. | |
140 | :Type: ETag. | |
141 | :Required: No | |
142 | ||
143 | ||
144 | Delete an Object | |
145 | ================ | |
146 | ||
147 | To delete an object, make a ``DELETE`` request with the API version, account, | |
148 | container and object name. You must have write permissions on the container to delete | |
c07f9fc5 | 149 | an object within it. Once you have successfully deleted the object, you will be able to |
7c673cae FG |
150 | reuse the object name. |
151 | ||
152 | Syntax | |
153 | ~~~~~~ | |
154 | ||
155 | :: | |
156 | ||
157 | DELETE /{api version}/{account}/{container}/{object} HTTP/1.1 | |
158 | Host: {fqdn} | |
159 | X-Auth-Token: {auth-token} | |
160 | ||
161 | ||
162 | Get an Object | |
163 | ============= | |
164 | ||
165 | To retrieve an object, make a ``GET`` request with the API version, account, | |
166 | container and object name. You must have read permissions on the container to | |
167 | retrieve an object within it. | |
168 | ||
169 | Syntax | |
170 | ~~~~~~ | |
171 | ||
172 | :: | |
173 | ||
174 | GET /{api version}/{account}/{container}/{object} HTTP/1.1 | |
175 | Host: {fqdn} | |
176 | X-Auth-Token: {auth-token} | |
177 | ||
178 | ||
179 | ||
180 | Request Headers | |
181 | ~~~~~~~~~~~~~~~ | |
182 | ||
183 | ``range`` | |
184 | ||
185 | :Description: To retrieve a subset of an object's contents, you may specify a byte range. | |
186 | :Type: Date | |
187 | :Required: No | |
188 | ||
189 | ||
190 | ``If-Modified-Since`` | |
191 | ||
192 | :Description: Only copies if modified since the date/time of the source object's ``last_modified`` attribute. | |
193 | :Type: Date | |
194 | :Required: No | |
195 | ||
196 | ||
197 | ``If-Unmodified-Since`` | |
198 | ||
199 | :Description: Only copies if not modified since the date/time of the source object's ``last_modified`` attribute. | |
200 | :Type: Date | |
201 | :Required: No | |
202 | ||
203 | ``Copy-If-Match`` | |
204 | ||
205 | :Description: Copies only if the ETag in the request matches the source object's ETag. | |
206 | :Type: ETag. | |
207 | :Required: No | |
208 | ||
209 | ||
210 | ``Copy-If-None-Match`` | |
211 | ||
212 | :Description: Copies only if the ETag in the request does not match the source object's ETag. | |
213 | :Type: ETag. | |
214 | :Required: No | |
215 | ||
216 | ||
217 | ||
218 | Response Headers | |
219 | ~~~~~~~~~~~~~~~~ | |
220 | ||
221 | ``Content-Range`` | |
222 | ||
223 | :Description: The range of the subset of object contents. Returned only if the range header field was specified in the request | |
224 | ||
225 | ||
226 | Get Object Metadata | |
227 | =================== | |
228 | ||
229 | To retrieve an object's metadata, make a ``HEAD`` request with the API version, | |
230 | account, container and object name. You must have read permissions on the | |
231 | container to retrieve metadata from an object within the container. This request | |
232 | returns the same header information as the request for the object itself, but | |
233 | it does not return the object's data. | |
234 | ||
235 | Syntax | |
236 | ~~~~~~ | |
237 | ||
238 | :: | |
239 | ||
240 | HEAD /{api version}/{account}/{container}/{object} HTTP/1.1 | |
241 | Host: {fqdn} | |
242 | X-Auth-Token: {auth-token} | |
243 | ||
244 | ||
245 | ||
246 | Add/Update Object Metadata | |
247 | ========================== | |
248 | ||
249 | To add metadata to an object, make a ``POST`` request with the API version, | |
250 | account, container and object name. You must have write permissions on the | |
251 | parent container to add or update metadata. | |
252 | ||
253 | ||
254 | Syntax | |
255 | ~~~~~~ | |
256 | ||
257 | :: | |
258 | ||
259 | POST /{api version}/{account}/{container}/{object} HTTP/1.1 | |
260 | Host: {fqdn} | |
261 | X-Auth-Token: {auth-token} | |
262 | ||
263 | Request Headers | |
264 | ~~~~~~~~~~~~~~~ | |
265 | ||
266 | ``X-Object-Meta-{key}`` | |
267 | ||
268 | :Description: A user-defined meta data key that takes an arbitrary string value. | |
269 | :Type: String | |
270 | :Required: No | |
271 |