4.4. Swift 容器操作

4.4.1. Swift 容器操作

容器是用于存储数据对象的机制。帐户可以有许多容器，但容器名称必须是唯一的。此 API 允许客户端创建容器，设置访问控制和元数据，检索容器的内容，以及删除容器。由于此 API 对特定用户帐户中的信息发出与请求相关的请求，因此此 API 中的所有请求都必须进行身份验证，除非容器访问控制被有意公开访问，即允许匿名请求。

注意

Amazon S3 API 使用术语"bucket"来描述数据容器。当您听到在 Swift API 中提到术语 'bucket' 时，这个术语 'bucket' 可能被认为与 "container" 这一术语相当。

对象存储的一个方面是它不支持分层路径或目录。相反，它支持由一个或多个容器组成的一个级别，每个容器可能具有对象。RADOS 网关的 Swift API 支持 'pseudo-hierarchical 容器' 的概念，这是一种使用对象命名来模拟容器或目录层次结构，而无需实际在存储系统中实施。您可以使用伪层次结构名称来命名对象，例如 photos/buildings/empire-state.jpg，但容器名称不能包含正斜杠(/)字符。

重要

将大型对象上传到版本的 Swift 容器时，在 python-swiftclient 程序中使用 --leave-segments 选项。不要使用 --leave-segments 覆盖清单文件。因此，现有对象会被覆盖，这会导致数据丢失。

4.4.2. Swift 更新容器的访问控制列表(ACL)

当用户创建容器时，用户默认对容器具有读写权限。要允许其他用户读取容器的内容或写入容器，您必须特别启用该用户。您也可以在 X-Container-Read 或 X-Container-Write 设置中指定 *，这样可以有效地让所有用户从或写入容器。设置 * 使容器变为公共容器。这是它允许匿名用户从容器读取或写入到容器。

语法

POST /API_VERSION/ACCOUNT/TENANT:CONTAINER HTTP/1.1
Host: FULLY_QUALIFIED_DOMAIN_NAME
X-Auth-Token: AUTH_TOKEN
X-Container-Read: *
X-Container-Write: UID1, UID2, UID3

请求 Headers

x-Container-Read

描述: 具有容器读取权限的用户 ID。
Type: 用户 ID 的以逗号分隔的字符串值。
必需: 否

X-Container-Write

描述: 具有容器写入权限的用户 ID。
Type: 用户 ID 的以逗号分隔的字符串值。
必需: 否

4.4.3. Swift 列出容器

指定 API 版本并且帐户返回特定用户帐户的容器列表的 GET 请求。由于请求返回特定用户的容器，因此请求需要身份验证令牌。无法匿名发出请求。

语法

GET /API_VERSION/ACCOUNT HTTP/1.1
Host: FULLY_QUALIFIED_DOMAIN_NAME
X-Auth-Token: AUTH_TOKEN

请求参数

limit

描述: 将结果数量限制为指定的值。
Type: 整数
有效值: 不适用
必需: 是

格式

描述: 将结果数量限制为指定的值。
Type: 整数
有效值: json 或 xml
必需: 否

marker

描述: 返回大于标记值的结果列表。
Type: 字符串
有效值: 不适用
必需: 否

响应包含容器列表，或使用 HTTP 204 响应代码返回。

响应实体

account

描述: 帐户信息列表。
Type: Container

container

描述: 容器列表。
Type: Container

名称

描述: 容器的名称。
Type: 字符串

bytes

描述: 容器的大小。
Type: 整数

4.4.4. Swift 列出容器的对象

要列出容器内的对象，请使用 API 版本、帐户和容器名称来创建一个 GET 请求。您可以指定查询参数来过滤完整列表，或用参数返回存储在容器中的前 10,000 项名称的列表。

语法

GET /API_VERSION/TENANT:CONTAINER HTTP/1.1
Host: FULLY_QUALIFIED_DOMAIN_NAME
X-Auth-Token: AUTH_TOKEN

请求参数

格式

描述: 将结果数量限制为指定的值。
Type: 整数
有效值: json 或 xml
必需: 否

prefix

描述: 将结果设置为以指定前缀开头的对象。
Type: 字符串
有效值: 不适用
必需: 否

marker

描述: 返回大于标记值的结果列表。
Type: 字符串
有效值: 不适用
必需: 否

limit

描述: 将结果数量限制为指定的值。
Type: 整数
有效值: 0 - 10,000
必需: 否

delimiter

描述: 前缀与其他对象名称之间的分隔符。
Type: 字符串
有效值: 不适用
必需: 否

path

描述: 对象的伪层次结构路径。
Type: 字符串
有效值: 不适用
必需: 否

响应实体

container

描述: 容器。
Type: Container

object

描述: 容器内的对象。
Type: Container

名称

描述: 容器中对象的名称。
Type: 字符串

hash

描述: 对象内容的散列代码。
Type: 字符串

last_modified

描述: 最后一次修改对象内容的时间。
Type: Date

content_type

描述: 对象中的内容类型。
Type: 字符串

4.4.5. Swift 创建容器

若要创建新容器，请为 PUT 请求提供 API 版本、帐户和新容器的名称。容器名称必须是唯一的，不得包含正斜杠(/)字符，且应小于 256 字节。您可以在请求中包含访问控制标头和元数据标头。您还可以包含指定一组 PG 的密钥的存储策略。例如，执行 radosgw-admin zone get 以查看 placement_pools 下的可用键的列表。存储策略允许您为容器指定一组特殊的池，如基于 SSD 的存储。操作是幂等的。如果您请求创建已存在的容器，它会返回 HTTP 202 返回代码，但不会创建另一个容器。

语法

PUT /API_VERSION/ACCOUNT/TENANT:CONTAINER HTTP/1.1
Host: FULLY_QUALIFIED_DOMAIN_NAME
X-Auth-Token: AUTH_TOKEN
X-Container-Read: COMMA_SEPARATED_UIDS
X-Container-Write: COMMA_SEPARATED_UIDS
X-Container-Meta-KEY:VALUE
X-Storage-Policy: PLACEMENT_POOLS_KEY

Headers

x-Container-Read

描述: 具有容器读取权限的用户 ID。
Type: 用户 ID 的以逗号分隔的字符串值。
必填: 否

X-Container-Write

描述: 具有容器写入权限的用户 ID。
Type: 用户 ID 的以逗号分隔的字符串值。
必填: 否

X-Container-Meta-KEY

描述: 用户定义的元数据键，它采用任意字符串值。
Type: 字符串
必填: 否

x-Storage-Policy

描述: 在 Ceph 对象网关的 placement_pools 下标识存储策略的密钥。为可用的密钥执行 radosgw-admin zone get。
Type: 字符串
必填: 否

如果容器已存在具有相同名称的容器，并且用户是容器所有者，则操作将成功。否则，操作将失败。

HTTP 响应

409

状态代码: BucketAlreadyExists
描述: 容器已存在于其他用户的所有权下。

4.4.6. Swift 删除容器

要删除容器，请使用 API 版本、帐户和容器名称进行 DELETE 请求。容器必须为空。如果您想检查容器是否为空，请对容器执行 HEAD 请求。成功移除容器后，您将能够重复利用容器名称。

语法

DELETE /API_VERSION/ACCOUNT/TENANT:CONTAINER HTTP/1.1
Host: FULLY_QUALIFIED_DOMAIN_NAME
X-Auth-Token: AUTH_TOKEN

HTTP 响应

204

状态代码: NoContent
描述: 容器已被删除。

4.4.7. Swift 添加或更新容器元数据

要向容器添加元数据，请使用 API 版本、帐户和容器名称发出 POST 请求。容器必须具有写入权限才能添加或更新元数据。

语法

POST /API_VERSION/ACCOUNT/TENANT:CONTAINER HTTP/1.1
Host: FULLY_QUALIFIED_DOMAIN_NAME
X-Auth-Token: AUTH_TOKEN
X-Container-Meta-Color: red
X-Container-Meta-Taste: salty