注意
本文档适用于 Ceph 的开发版本。
容器操作
容器是用于存储数据对象的机制。一个账户可以有多个容器，但容器名称必须唯一。此 API 允许客户端创建容器、设置访问控制和元数据、检索容器内容以及删除容器。由于此 API 发出的请求与特定用户账户中的信息相关，因此此 API 中的所有请求都必须经过身份验证，除非容器的访问控制被故意设置为公共可访问（即允许匿名请求）。
注意
Amazon S3 API 使用术语“bucket”（存储桶）来描述数据容器。当您听到有人在 Swift API 中提及“bucket”时，“bucket”一词可以被理解为等同于“container”（容器）。
对象存储的一个特点是它不支持分层路径或目录。相反，它支持一个包含一个或多个容器的级别，其中每个容器可以包含对象。RADOS Gateway 的 Swift 兼容 API 支持“伪分层容器”的概念，这是一种通过使用对象命名来模拟容器（或目录）层次结构的方法，而无需在存储系统中实际实现它。您可以使用伪分层名称命名对象（例如 photos/buildings/empire-state.jpg），但容器名称不能包含正斜杠（/）字符。
创建容器
要创建新容器，请发出 PUT 请求，其中包含 API 版本、账户和新容器的名称。容器名称必须唯一，不能包含正斜杠（/）字符，并且应小于 256 字节。您可以在请求中包含访问控制标头和元数据标头。该操作是幂等的；也就是说，如果您发出创建已存在容器的请求，它将返回 HTTP 202 返回码，但不会创建另一个容器。
语法
PUT /{api version}/{account}/{container} HTTP/1.1
Host: {fqdn}
X-Auth-Token: {auth-token}
X-Container-Read: {comma-separated-uids}
X-Container-Write: {comma-separated-uids}
X-Container-Meta-{key}: {value}
标头
X-Container-Read
- 描述:
对容器具有读取权限的用户 ID。
- 类型:
逗号分隔的用户 ID 字符串值。
- 必需:
否
X-Container-Write
- 描述:
对容器具有写入权限的用户 ID。
- 类型:
逗号分隔的用户 ID 字符串值。
- 必需:
否
X-Container-Meta-{key}
- 描述:
用户定义的元数据键，取任意字符串值。
- 类型:
String
- 必需:
否
HTTP响应
如果已存在同名容器，且用户是容器所有者，则操作将成功。否则操作将失败。
409
- 描述:
该容器已存在于其他用户所有权下。
- 状态码:
BucketAlreadyExists
列出容器中的对象
要列出容器中的对象，请发出 GET 请求，其中包含 API 版本、账户和容器名称。您可以指定查询参数来过滤完整列表，或者省略参数以返回存储在容器中的前 10,000 个对象名称列表。
Syntax
GET /{api version}/{container} HTTP/1.1
Host: {fqdn}
X-Auth-Token: {auth-token}
参数
format
- 描述:
定义结果的格式。
- 类型:
String
- Valid Values:
json|xml- 必需:
否
prefix
- 描述:
将结果集限制为以指定前缀开头的对象。
- 类型:
String
- 必需:
否
marker
- 描述:
返回大于标记值的列表结果。
- 类型:
String
- 必需:
否
limit
- 描述:
将结果数限制为指定值。
- 类型:
整数
- 有效范围:
0 - 10,000
- 必需:
否
delimiter
- 描述:
前缀与对象名称其余部分之间的分隔符。
- 类型:
String
- 必需:
否
path
- 描述:
对象的伪分层路径。
- 类型:
String
- 必需:
否
allow_unordered
- 描述:
允许返回无序结果以减少计算开销。不能与
delimiter一起使用。- 类型:
Boolean
- 必需:
否
- 非标准扩展:
是
Response Entities
container
- 描述:
容器。
- 类型:
Container
object
- 描述:
容器内的对象。
- 类型:
Container
name
- 描述:
容器内对象的名称。
- 类型:
String
hash
- 描述:
对象内容的哈希码。
- 类型:
String
last_modified
- 描述:
对象内容最后修改的时间。
- 类型:
日期
content_type
- 描述:
对象内的内容类型。
- 类型:
String
更新容器的 ACL
当用户创建容器时，默认情况下用户对容器具有读写权限。要允许其他用户读取容器内容或写入容器，您必须明确启用该用户。您也可以在 X-Container-Read 或 X-Container-Write 设置中指定 *，这会有效地允许所有用户读取或写入容器。设置 * 会使容器公开。这意味着它允许匿名用户读取或写入容器。
注意
如果您计划为 Swift API 公开公共读取 ACL 功能，强烈建议在端点定义中包含 Swift 账户名称，以最接近地模仿原生 OpenStack Swift 的行为。为此，请在 ceph.conf 配置文件中设置 rgw swift account in url = true，并将 Keystone 端点更新为 URL 后缀 /v1/AUTH_%(tenant_id)s（而不是仅 /v1）。
语法
POST /{api version}/{account}/{container} HTTP/1.1
Host: {fqdn}
X-Auth-Token: {auth-token}
X-Container-Read: *
X-Container-Write: {uid1}, {uid2}, {uid3}
请求头
X-Container-Read
- 描述:
对容器具有读取权限的用户 ID。
- 类型:
逗号分隔的用户 ID 字符串值。
- 必需:
否
X-Container-Write
- 描述:
对容器具有写入权限的用户 ID。
- 类型:
逗号分隔的用户 ID 字符串值。
- 必需:
否
添加/更新容器元数据
要向容器添加元数据，请发出 POST 请求，其中包含 API 版本、账户和容器名称。您必须对容器具有写入权限才能添加或更新元数据。
语法
POST /{api version}/{account}/{container} HTTP/1.1
Host: {fqdn}
X-Auth-Token: {auth-token}
X-Container-Meta-Color: red
X-Container-Meta-Taste: salty
请求标头
X-Container-Meta-{key}
- 描述:
用户定义的元数据键，取任意字符串值。
- 类型:
String
- 必需:
否
为容器启用对象版本控制
要为容器启用对象版本控制，请发出 POST 请求，其中包含 API 版本、账户和容器名称。您必须对容器具有写入权限才能添加或更新元数据。
注意
radosgw 默认情况下未启用对象版本控制支持；您必须在 ceph.conf 中设置 rgw swift versioning enabled = true 来启用此功能。
Syntax
POST /{api version}/{account}/{container} HTTP/1.1
Host: {fqdn}
X-Auth-Token: {auth-token}
X-Versions-Location: {archive-container}
请求标头
X-Versions-Location
- 描述:
容器（“归档容器”）的名称，该容器将用于存储发出
POST请求的容器（“当前容器”）中的对象版本。在引用归档容器时，它可能不需要存在，但是一旦在当前容器上设置了X-Versions-Location，并且因此启用了对象版本控制，那么在当前容器中更新或删除任何其他对象之前，归档容器必须存在。注意
X-Versions-Location是 radosgw 解释的唯一与版本控制相关的标头。原生 OpenStack Swift 支持的X-History-Location目前不受 radosgw 支持。- 类型:
String
- 必需:
否（如果此标头传入空值，则禁用当前容器上的对象版本控制，但归档容器继续存在。）
删除容器
要删除容器，请发出 DELETE 请求，其中包含 API 版本、账户和容器名称。容器必须为空。如果您想检查容器是否为空，请对容器执行 HEAD 请求。成功删除容器后，您将能够重用该容器名称。
语法
DELETE /{api version}/{account}/{container} HTTP/1.1
Host: {fqdn}
X-Auth-Token: {auth-token}
HTTP 响应
204
- 描述:
容器已移除。
- 状态码:
NoContent