OpenStack Object Storage Developer Guide/Swift官方API文档 -- 翻译 （二）
在上一篇中，翻译介绍了Swift官方文档的第2部分API基本信息，本篇来完成最主要的存储服务的API操作部分。那么，现在就让我们开始吧=D
3. 存储服务的API操作（API Operations for Storage Services）
3.1. Account存储服务（Storage Account Services）
3.1.1. 获取容器列表（List Containers）
3.1.2. 获取账号元数据（Retrieve Account Metadata）
3.1.3. 创建/更新账号元数据（Create/Update Account Metadata)
3.1.4. 删除账号元数据（Delete Account Metadata）
3.2. Container存储服务（Storage Container Services）
3.2.1. 获取对象列表（List Objects）
3.2.2. 创建容器（Create Container）
3.2.3. 删除容器（Delete Container）
3.2.4. 获取容器元数据（Retrieve Container Metadata）
3.2.5. 创建/更新容器元数据（Create/Update Container Metadata）
3.2.6. 删除容器元数据（Delete Container Metadata）
3.3. 创建静态站点（Create Static Website）
3.3.1. 通过Swift实现的静态网页中间件（Static Web Middleware via swift）
3.3.2. 为静态站点设置出错页（Set Error Pages for Static Website）
3.4. Object存储服务（Storage Object Services）
3.4.1. 获取对象（Retrieve Object）
3.4.2. 创建/更新对象（Create/Update Object）
3.4.3. 为请求分配CORS头（Assigning CORS Headers to Requests）
3.4.4. 通过Content-Encoding头启用文件压缩（Enabling File Compression with the Content-Encoding Header）
3.4.5. 通过Content-Disposition都启用浏览器旁路（Enabling Browser Bypass with the Content-Disposition Header）
3.4.6. 通过X-Delete-After和X-Delete-At头使对象过期（Expiring Objects with the X-Delete-After and X-Delete-At Headers）
3.4.7. 对象版本管理（Object Versioning）
3.4.8. 复制对象（Copy Object）
3.4.9. 删除对象（Delete Object）
3.4.10. 获取对象元数据（Retrieve Object Metadata）
3.4.11. 更新对象元数据（Update Object Metadata）
本章描述了与OpenStack对象存储中的存储组件进行交互的ReST API。所有的请求都通过在认证阶段成功获取的 X-Storage-Url 直接发送到主机。
以下内容为使用存储服务需要满足的几点要求：
- Container的名称不能超过256字节，并且不能包含字符'/'；
- Object的名称不能超过1024字节，并且不能包含保留字符；
- Object和Container的名称必须是URL编码和UTF编码的。
以下小节描述了存储系统中可能被执行的动作，3.1节重点描述存储系统中account层面的动作；3.2节重点描述存储系统中container层面的动作；3.4节（原文这里有误）重点描述了存储系统中object层面的动作。
3.1. Account存储服务（Storage Account Services）
以下操作在URL的account层面执行。例如，以下请求的URL将会以一个OpenStack对象存储的账户字符串结束：
例3.1. Account存储的HTTP请求：基本结构
METHOD /v1/<account> HTTP/1.1
3.1.1. 获取容器列表
对一个账号的 X-Storage-Url 执行 GET 操作将会获取这个账号下container列表，并以名称排序。名字的顺序由二进制比较决定，一个简单的内建排序方法是用SQLite的memcmp()函数实现，且与编码无关。以下列表内容描述了这个请求支持的可选参数。
| limit | 整数n，指明返回结果只包含n个值 |
| marker | 字符串x，返回名称比这个特定的字符串x大的container列表 |
| end_marker | 字符串x，返回名称比这个特定字符串小的container列表 |
| format | 设定响应的数据格式为json或xml |
当前，在account层面不支持根据前缀（prefix）查询。
例3.2. 获取container列表的请求
GET /<api version>/<account> HTTP/1.1 Host: storage.swiftdrive.com X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
container列表包含在响应消息体（response body）中，每行一个container名称。当查询账户中一个container都没有时，将会返回一个没有内容、状态码为204的响应消息。
例3.3. 获取container列表的响应
HTTP/1.1 200 Ok
Date: Thu, 07 Jun 2010 18:57:07 GMT
Server: Apache
Content-Type: text/plain; charset=UTF-8
Content-Length: 32
images
movies
documents
backups
3.1.1.1. 序列化列表输出
如果在存储账号URL后添加一个 format=xml 或 format=json 参数对，则服务端会将container列表以指定的格式进行序列化再返回。以下的例子就是根据相应的格式进行返回的。
例3.4. container详情请求：JSON
GET /<api version>/<account>?format=json HTTP/1.1 Host: storage.swiftdrive.com Content-Length: 0 X-Storage-Token: 182f9c0af0e828cfe3281767d29d19f4
例3.5. container详情响应：JSON
HTTP/1.1 200 OK
Date: Tue, 25 Nov 2008 19:39:13 GMT
Server: Apache
Content-Type: application/json; charset=utf-8
[
{"name":"test_container_1", "count":2, "bytes":78},
{"name":"test_container_2", "count":1, "bytes":17}
]
例3.6. container详情请求：XML
GET /<api version>/<account>?format=xml HTTP/1.1 Host: storage.swiftdrive.com Content-Length: 0 X-Storage-Token: 182f9c0af0e828cfe3281767d29d19f4
例3.7. container详情响应：XML
HTTP/1.1 200 OK
Date: Tue, 25 Nov 2008 19:39:13 GMT
Server: Apache
Content-Type: application/xml; charset=utf-8
<?xml version="1.0" encoding="UTF-8"?> <account name="MichaelBarton"> <container> <name>test_container_1</name> <count>2</count> <bytes>78</bytes> </container> <container> <name>test_container_2</name> <count>1</count> <bytes>17</bytes> </container> </account>
3.1.1.2. Container大列表的控制
OpenStack对象存储系统每个请求最多可以返回10,000个容器的名字。为了获取container名称列表的子序列，另一个请求必须使用 marker 参数。这个参数表明了列表从哪里结束，系统将会返回所有名称大于这个marker的container名称，同时，最多也只能有10,000个。注意，marker的值通过HTTP请求发送时应当是URL-encoded的。
如果我们不需要10,000个那么多的container，我们可以使用 limit 参数。
如果返回的container名称列表的长度刚好等于limit的值（或当没有使用limit时，等于10,000），则表明可能还有满足条件的container名称没有返回。
例3.8. 列出很长的container列表
例如，我们使用一个长度为5的容器名称列表。
apples
bananas
kiwis
oranges
pears
我们将使用limit值为2来表明这是如何工作的：
GET /<api version>/<account>?limit=2 Host: storage.swiftdrive.com X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
apples
bananas
由于我们收到两个容器名称（与limit的值相同），因此我们猜测还有更多的container名称需要被列出。因此，我们使用marker参数创建另一个请求，marker的值为上一次请求返回的container列表中的最后一个：
GET /<api version>/<account>?limit=2&marker=bananas Host: storage.swiftdrive.com X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
kiwis
oranges
由于又收到了长度为2的container列表，同理，我们继续请求：
GET /<api version>/<account>?limit=2&marker=oranges Host: storage.swiftdrive.com X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
pears
这次，我们只收到了长度为1的container列表，小于请求的limit值，因此表明没有更多的container名称需要被列出了，即已经到达了列表的结尾。
通过使用 end_marker 参数，我们可以限制返回的结果中的container名称小于给定的值。
GET /<api version><account>?end_marker=oranges Host: storage.swiftdrive.com X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
apples
bananas
kiwis
3.1.2. 获取账号元数据
在一个账号上使用HEAD操作可以获取这个账号下的container数量以及总存储字节。这个信息通过两个自定义的头信息返回：X-Account-Container-Count 和 X-Account-Bytes-Used。由于swift是为存储海量数据而设计的，因此在使用integer类型存储账号总使用字节时应当格外小心，如果你的平台支持的话，可以将其转换为64位的无符号整型。
例3.9. 获取账号元数据的请求
HEAD /<api version>/<account> HTTP/1.1 Host: storage.swiftdrive.com X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
如果请求成功，将会返回状态码为204（没有内容）的响应。如果请求的是一个无效的账号或访问key错误的话，将会返回状态码为401（未授权）的响应。
例3.10. 获取账号元数据的响应
HTTP/1.1 204 No Content
Date: Thu, 07 Jun 2010 18:57:07 GMT
Server: Apache
X-Account-Container-Count: 3
X-Account-Bytes-Used: 323479
3.1.3. 创建/更新账号元数据
你可以在account级别的URI上使用自定义的元数据头信息，这些头必须以 X-Account-Meta-* 的格式定义。
如果你想创建或更新一个账号的元数据头信息，则需要使用POST查询。后续请求中的相同可以的key/value对将会覆盖之前的值。
例3.11. 更新账号元数据的请求
POST /<api version>/<account> HTTP/1.1 Host: storage.clouddrive.com X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb X-Account-Meta-Book: MobyDick X-Account-Meta-Subject: Whaling
这个请求将不会有包含消息体的响应返回，一个状态码为204的无内容响应表明更新成功。
例3.12. 更新账号元数据的响应
HTTP/1.1 204 No Content
Content-Length: 0
Content-Type: text/html; charset=UTF-8
Date: Sat, 09 Jun 2012 19:16:29 GMT
为了确认你的元数据确实已经被更改了，则需要对account执行一个HEAD请求。注意，请不要在你的HEAD请求中包含任何元数据信息。
例3.13. 查看Account元数据的请求
HEAD /<api version>/<account> HTTP/1.1 Host: storage.clouddrive.com X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
例3.14. 查看Account元数据的响应
HTTP/1.1 204 No Content
X-Account-Meta-Book: MobyDick
X-Account-Meta-Subject: Whaling
X-Account-Object-Count: 5
X-Timestamp: 1323466696.21566
X-Account-Container-Count: 5
X-Account-Bytes-Used: 46988
Accept-Ranges: bytes
Content-Length: 0
Date: Sat, 09 Jun 2012 19:16:59 GMT
3.1.4. 删除账号元数据
为了删除账号的一个元数据，我们需要使用那个特定的头信息发送一个值为空的POST请求，例如X-Account-Meta-Book: 。
如果你所使用的与swift进行交互的工具不支持发送包含headers值为空的请求（例如较老版本的curl），则你可以发送头为“X-Remove-Account-Meta-name: 任意值”的请求，例如：X-Remove-Account-Meta-Book: x。这个值将会被忽略。
例3.15. 删除Account元数据的请求
POST /<api version>/<account> HTTP/1.1 Host: storage.clouddrive.com X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb X-Remove-Account-Meta-Book: x
这个请求将不会有包含消息体的响应返回，一个状态码为204的无内容响应表明删除成功。
暂时到这里吧，好累T^T，后续完成后再把3.2.节合并到后面（已合并完毕），这样一篇一小节^_^
