“OpenStack Object Storage API v1”解析

OpenStack Object Storage又名swift。

OpenStack Object Storage是一种冗余的，可扩展的，动态的存储服务提供者，其核心思想是提供一种安全的，自动调整大小和基于网络存取方式来存储数据。

OpenStack Object Storage允许用户存储与检索文件和内容通过一种简单的Web Service interface（ReST：Representational State Transfer）。如今，已有多种语言实现了ReSTful的API，所以对开发人员来说将这些整合到应用变得容易多了。

更多的关于OpenStack Object Storage信息：http://docs.openstack.org/developer/swift/

本文建立在你已经安装了OpenStack Object Storage服务

认证

以Linux命令行工具 curl 为例，获取令牌与存储url

curl -v -H 'X-Storage-User: test:tester' -H 'X-Storage-Pass: testing' http://172.26.xxx.xxx:xxxx/auth/v1.0

返回内容包含以下http header：

x-Storage-Url:http://172.26.xxx.xxx:xxxx/v1/Auth_test

x-Storage-Token:AUTH_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

在swift上对容器或者对象的操作都基于X-Storage-URL指定的url，并且也都需要包含X-Storage-Token header

所有基于认证或者对swift操作的请求都是通过在TCP端口443上使用SSL实现的

账户服务

<METHOD> /v1/<account> HTTP/1.1

列出用户容器

curl -k -X GET -H 'X-Auth-Token:AUTH_xxxxxxxxxxxxxxxxxxxxxxxxxxxx'http://172.26.xxx.xxx:xxxx/auth/v1/Auth_test

可以使用查询参数

如limit=3只输出前三个

curl -k -X GET -H 'X-Auth-Token:AUTH_xxxxxxxxxxxxxxxxxxxxxxxxxxxx'http://172.26.xxx.xxx:xxxx/auth/v1/Auth_test？limit=3

还可以是marker，返回容器名称大于该marker的容器

end_marker，返回容器名称小于该end_marker的容器

format，指定结果以json或者xml返回

列出账户元数据

使用head方法查询账户元数据信息

curl -v -X HEAD -H 'X-Auth-Token:AUTH_XXXXXXXXXXXXXXXXXXXXXX' http://172.26.xxx.xxx:xxxx/v1/AUTH_test?format=xml

返回以下响应信息

X-Account-Object-Count: 137

X-Account-Bytes-Used: 1070538

X-Account-Container-Count: 9

Accept-Ranges: bytes

创建或更新账户元数据

添加的header必须按照这个格式来写：X-Account-Meta-*

 curl -v -X POST -H 'X-Auth-Token:AUTH_xxxxxxxxxxxxxxxxxx' -H 'X-Account-Meta-Book:swift' http://172.26.xxx.xxx:xxxx/v1/AUTH_test?

然后，查看账户元数据，发现该header已经添加

X-Account-Object-Count: 137

X-Account-Meta-Book: swift
X-Account-Bytes-Used: 1070538
X-Account-Container-Count: 9
Accept-Ranges: bytes

删除账户元数据

须按照以下格式删除，X-Remove-Account-Meta-Book：x，其中值部分的具体取值可以忽略

curl -v -X POST -H 'X-Auth-Token:AUTH_xxxxxxxxxxxxx' -H 'X-Remove-Account-Meta-Book:x' http://172.26.xxx.xxx:xxxx/v1/AUTH_test?format=xml

然后查看账户元数据，发现header已经删除

容器服务

可以使用以下方法操作容器

GET	/account/container	列出对象
PUT	/account/container	创建一个容器
DELETE	/account/container	删除一个容器
HEAD	/account/container	查询容器元数据

所有操作按照以下格式

METHOD /v1/<account>/<container> HTTP/1.1

列出容器下的对象

curl -v -X GET -H 'X-Auth-Token:AUTH_tkada7xxxxxxxx' http://172.26.xxx.xxx:xxxx/v1/AUTH_test/test

可以通过设置查询参数prefix来设置前缀匹配，如

curl  -X GET -H 'X-Auth-Token:AUTH_tkada7cf96780947xxxx' http://172.26.xxx.xxx:xxxx/v1/AUTH_test/test?prefix=2385

查询AUTH_test账户，test容器下，已2385开头的对象

伪分层文件夹与目录

不能在Swift上建立目录，但是我们通过在一个容器，给对象名称中间添加'/'来模拟该层次结构。

例如，存储url为http://172.26.xxx.xxx:xxxx/v1/AUTH_test，容器名称为test，现在可以建立一个伪文件夹photos，那么image me.jpg的url是

http://172.26.xxx.xxx:xxxx/v1/AUTH_test/test/photos/me.jpg，好像图片存放在test容器下的photos伪文件夹下

GET /v1/AUTH_test/test，获得的是test容器下的所有对象

GET /v1/AUTH_test/test?delimiter=/,获得的是test容器下包含的伪文件夹

GET /v1/AUTH_test/test?prefix=2385/&delimiter=/,获得是test容器下，2385/开头的,已'/'作为分隔符的对象

GET /v1/AUTH_test/test?prefix=2385/animais/dogs/&delimiter=/,获得的是2385文件夹下的animais文件下的dogs文件夹下的文件对象

创建容器

PUT /<api version>/<account>/<container> HTTP/1.1

容器是存储数据的部件，容器的名称中不能包含'/'，也就是说容器里面不存在子容器的概念

url -v -X PUT -H 'X-Auth-Token:AUTH_tkada7cf967809471xxxxxx' http://172.26.xxx.xxx:xxxx/v1/AUTH_test/learnCreateContainer

可以按照 X-Container-Meta-xxx的格式给容器添加标签，例如

 curl -v -X PUT -H 'X-Auth-Token:AUTH_tk6fad162b657944ef9221ddxxxxx' -H 'X-Container-Meta-InspectedBy:lidashuai' http://172.26.xxx.xxx:8081/v1/AUTH_test/learnCreateContainer1

删除容器

DELETE /<api version>/<account>/<container> HTTP/1.1

删除一个容器前，必须确保容器为空，才能被删除

curl -v -X DELETE -H 'X-Auth-Token:AUTH_tk6fad162b657944ef9223a61ddxxxxx'  http://172.26.xxx.xxx:xxxx/v1/AUTH_test/learnCreateContaine

获取容器元数据

HEAD /<api version>/<account>/<container> HTTP/1.1

该请求会返回Container-Object-Count返回容器中对象的个数，X-Container-Bytes-Used会返回容器的字节数大小

创建或者更新容器元数据

可以根据需要创建各种元数据header，但是必须按照X-Container-Meta-xxx的格式来命名

POST /<api version>/<account>/<container>/ HTTP/1.1

对于相同的key，之后的value会覆盖先去的value值

查询容器元数据可以按照下列格式

HEAD /<api version>/<account>/<container>/ HTTP/1.1

删除容器元数据

与创建和更新容器元数据相似，按照X-Remove-Container-Meta-xxx来指定要删除的容器元数据的名称

存储对象服务

对象要求不能大于5G，如果大于5G的话，需要分段已确保每段不能大于5G

GET	/account/container/object	获取对象数据
PUT	/account/container/object	创建或者更新对象
PUT	/account/container/object	分块传输编码
DELETE	/account/container/object	删除对象
HEAD	/account/container/object	查看对象元数据
POST	/account/container/object	更新对象元数据

获取对象数据

通过使用HTTP Range header可以获取一部分数据，但是目前swift只能支持Range的部分功能

Range:bytes=-5,对象的最后5个字节

Range:bytes=10-15,对象的第10到15个字节

Range:bytes=32-，第32个字节之后的所有字节

GET /<api version>/<account>/<container>/<object> HTTP/1.1

curl  -X GET -H 'X-Auth-Token:AUTH_tk6fad162b6xxxxxxx'  -H 'Range: bytes=10-20' http://172.26.xxx.xxx:xxxx/v1/AUTH_test/test/961/E4D320B7-F335-xxxxxxx

响应体中包含对象数据，响应头包含对象元数据

创建或者更新对象

PUT操作用来写或者重写一个对象的内容和元数据

建议使用ETag header，用来存放对象的MD5值，该值可以用来检测数据传输是否成功

PUT操作还可以指定一个对象失效日期，通过使用X-Delete-At or X-Delete-After headers，系统会在指定的时间停止该对象的服务，并删除该对象

可以按照以下形式添加对象元数据：X-Object-Meta-xxx

PUT /<api version>/<account>/<container>/<object> HTTP/1.1

如果上传到swift上的数据的MD5检测和与ETag的值不同，则返回422（未被处理的实体）

curl -v -X PUT -T ./1.txt -H 'Content-Type: text/html' -H 'X-Auth-Token:AUTH_tk6faxxxxx'   http://172.26.xxx.xxx:xxxx/v1/AUTH_xxxx/learnCreateContainer/1.txt

需要指定Content-Type或者Content-length在header中，否则会返回411错误

使用Content-Encoding header压缩文件

通过使用Content-Encoding header，可以在不丢失文件的相关元类型时压缩，如视频文件

下面的例子用来指定，文件如何被下载

PUT /<api version>/<account>/<container>/<object> HTTP/1.1
Host: storage.clouddrive.com
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
Content-Type: video/mp4
Content-Encoding: gzip

通过X-Delete-After和X-Delete-At header设置对象失效

这个特性用于非持久存储，如log文件等

X-Delete-At header需要一个Unix时间戳，指定一个时间使对象失效，对该对象的服务停止，并删除该对象

X-Delete-After用来指定多少秒后使该对象失效

PUT /<api version>/<account>/<container>/<object> HTTP/1.1
Host: storage.clouddrive.com
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
Content-Type: image/jpeg
X-Delete-At: 1339429105

对象版本

允许存储一个对象的多个版本，防止被无意思的重写而导致覆盖问题

对象复制

如何将对象从一个容器复制到另一个容器呢？如果没有服务端的操作，你需要重复上传相同的对象，并删除原先的对象。通过使用服务端的操作，可以省去重复上传的操作

有两种方法用来拷贝一个已存在的对象

其一：PUT到一个新对象位置，通过使用X-Copy-From header来指定数据源，其值应该按照/container/object的形式指定，同时需要指定Content-Length header，即使长度为0

PUT /<api version>/<account>/<destcontainer>/<destobject> HTTP/1.1
Host: <storage URL>
X-Auth-Token: <some-auth-token>
X-Copy-From: /<sourcecontainer>/<sourceobject>
Content-Length: 0