OpenStack Object Storage Developer Guide/Swift官方API文档

lishenghan

　　关于开源代码的学习，主要就只接触过XMPP服务端实现Openfire和现在的Swift了。想想这段时间对swift学习的停滞感，越来越觉得“如果想要学习一个东西的原理，首先要会使用它”，这会在一定程度上增加对功能处理流程的理解，并在源码阅读时产生共鸣。
　　对于swift API的学习，由于之前一直没有找到比较系统的资料，官方文档主页上也没有相关的链接，所以都是对照着swift-python-client的curl命令自己进行整理，这几天突然发现swift官方文档主页上增加了Swift’s API docs链接！内容非常的全，以前真没见到过哎，可能藏的太深，哈哈哈，PDF请点击这里下载。
　　在文档的1.2小节document change history，中可以看到本文档是《Rackspace Cloud Files Developer Guide》的分支。整体阅读了一遍，发现很多细节内容是自己以前所不知的，比如分段返回信息、超过5GB的大文件上传等，为了给后续自己开发实验室的API做准备，所以决定试着翻译一下，也可以作为小组内工作共享。
　　文档中的内容主要分为4部分：



1. Overview
2. General API Information
3. API Operations for Storage Services
4. Troubleshooting and Examples
　　第1部分主要是对swift进行了简单的介绍，指明了本篇文档的目标读者、给出文档更改记录、其他资源链接；第4部分其实主要是介绍如何使用curl与swift进行交互的，以绕过代码层面的交互，并返回请求/相应的详细信息。其实看完前三个部分，对着命令行敲敲curl命令就可以理解了，很简单。我这个人还是很懒的，所以第1和第4部分就不打算翻啦=D
　　现在，就让我们愉快的开始吧！
　　=============================================================================
　　2. API基本信息


　　2.1. 认证
2.2. API操作概述
　　API操作参考摘要

Accounts存储


Verb
URI
描述


GET
/account
获取当前account下的containers列表


HEAD
account
获取account元数据信息
　　
　　
　　
　　

Container存储


Verb
URI
描述


GET
/account/container
获取当前container下的objects列表


PUT
/account/container
创建container


DELETE
/account/container
删除container


HEAD
/account/container
获取container元数据信息
　　
　　
　　
　　
　　

Object存储


Verb
URI
描述


GET
/account/container/object
获取object


PUT
/account/container/object
创建/更新object


PUT
/account/container/object
分块传输编码


DELETE
/account/container/object
删除object（原文档这里有误）


HEAD
/account/container/object
获取object元数据信息


POST
/account/container/object
更新object元数据信息
　　
　　
　　
　　
　　
　　
　　
　　2.1. 认证（Authentication）
　　客户端认证由ReST接口的GET方法提供，并使用 v1.0 作为路径。此外，有两个头信息必须提供：X-Auth-User 和 X-Auth-Key，它们的值分别为用户名和API访问Key。
　　每一个访问OpenStack对象存储系统的ReST请求都必须在HTTP头中包含一个特定的头信息：X-Auth-Token，这个header的值即为用户的访问认证token。客户端需要维护好这个token，同时也需要维护好其对应的云端服务器的API URI，这两个值都是在客户端第一次使用用户名和API访问Key进行认证服务的时候返回的。
　　请求
　　如果要进行认证，你必须提供你的用户名和API访问Key，并用这两个值设置HTTP请求头的x-headers：

• 使用你的OpenStack对象存储（Swfit）用户名作为API访问的用户名。将用户名存储在请求头的 X-Auth-User 中。
  
• 从你安装时所选择的认证服务中获取你的API访问Key。关于认证，你可以有几个选择，包括tempauth（swift中自带的）、swauth（这是一种将swift的认证服务作为WSGI中间件的方式，它使用swift本身作为后端存储，swauth可以通过Github进行下载）、OpenStack认证服务（KeyStone），或者你也可以使用自己的认证系统。将API访问Key存储在请求头的 X-Auth-Key 中。
  

　　　　例2.1. 认证请求



GET /v1.0 HTTP/1.1
Host: auth.api.yourcloud.com
X-Auth-User: jdoe
X-Auth-Key: a86850deb2742ec3cb41518e26aa2d89
　　响应
　　当认证成功时，一个状态码为204（没有Content）且包含头信息 X-Storage-Url 和 X-Auth-Token 的HTTP响应会被返回。任何一个状态码为2xx的响应都是一个好的响应。比如，一个202响应意味着请求已经被接受了。当然，一个额外的x-headers也有可能被返回。这些额外的头信息与其他的Rackspace服务相关也可以被忽略。当认证失败时，会返回一个状态码为401（未授权）的响应。所有子路径为container/object的OpenStack对象存储操作都应该使用 X-Storage-Url 中指定的URI作为访问基路径，且必须包含 X-Auth-Token 头。
　　　　例2.2. 认证响应



HTTP/1.1 204 No Content
Date: Mon, 12 Nov 2010 15:32:21 GMT
Server: Apache
X-Storage-Url: https://storage.swiftdrive.com/v1/CF_xer7_34
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
Content-Length: 0
Content-Type: text/plain; charset=UTF-8
　　X-Storage-Url 需要在后续的连接和所有对象存储请求中作为基URI解析和使用。在例2.2中，用户后续连接OpenStack对象存储进行container/object请求时，大部分情况下都需要使用storage.swiftdrive.com作为主机头、/v1/CF_xer7_34作为请求版本和账户。需要注意的是，在很多种认证配置中，认证token的有效期只有24个小时。
　　
　　2.2. API操作概述
　　OpenStack对象存储的API被实现成一套ReSTful（Representational State Transfer） web services的集合，所有的认证和container/object操作都可以通过标准的HTTP调用实现。可以查看维基百科获取更多关于ReST的信息。
　　以下内容为ReST API HTTP请求中的一些限制：

• 每个请求的HTTP headers数目最多为90;
  
• 所有HTTP headers的长度最大为4096 bytes;
  
• 每个HTTP请求行（HTTP request line）的最大长度为8192 bytes;
  
• 每个HTTP请求的最大长度为5 GB;
  
• container名称的最大长度为256 bytes;
  
• object名称的最大长度为1024 bytes
  

　　Container和object的名字在与ReST接口进行交互前必须被进行适当的URL编码，此外，container和object的名字也必须是UTF-8编码的。应该在进行URL编码后字符串上进行长度约束的检测。
　　每一个面向OpenStack对象存储系统的ReST请求都需要包含一个指定的认证token的HTTP头—— X-Auth-Token。客户端在第一次使用用户名和API访问Key进行认证时获取这个token，同时也获取OpenStack对象存储的URLs。
　　使用 X-Storage-Url 识别的ReST服务用语管理存储在系统中的数据。例如创建container和上传object的操作。
　　在下一节中，我们将介绍每个HTTP方法调用与服务的对应关系。比如，一个针对 X-Storage-Url 的PUT请求有可能是用于创建一个container或上传一个对象的。
　　特定语言的APIs将程序员与系统实现细节隔离开。程序员只需要简单的使用适当的ReST API就可以创建一个container、标记其为公共的，并处理调用将其分配到适当的后端服务。
　　注意：



所有认证请求和针对OpenStack对象存储的操作都通过HTTP（HTTPS）的SSL执行，并使用TCP 443端口。
　　
　　哎，翻的好烂，自己都受不了了T^T