注意

本文档适用于 Ceph 开发版本。

容器操作

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

Note

亚马逊 S3 API 使用术语“存储桶”来描述数据容器。当你在 Swift API 中听到有人提到“存储桶”时，“存储桶”一词可能被理解为与“容器”一词等效。

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

创建容器

要创建一个新的容器，请使用 API 版本、账户和新建容器的名称发出请求。容器名称必须唯一，不能包含正向斜杠（/）字符，并且应小于 256 字节。您可以在请求中包含访问控制标头和元数据标头。该操作是幂等的；也就是说，如果您向已存在的容器发出创建容器的请求，它将返回 HTTP 202 响应代码，但不会创建另一个容器。PUT request with the API version, account, and the name of the new container. The container name must be unique, must not contain a forward-slash (/) character, and should be less than 256 bytes. You may include access control headers and metadata headers in the request. The operation is idempotent; that is, if you make a request to create a container that already exists, it will return with a HTTP 202 return code, but will not create another container.

语法

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}

描述:: 一个用户定义的元数据键，它接受任意字符串值。
类型:: 字符串
必需:: 否

HTTP响应

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

409

描述:: 容器已被其他用户拥有。
状态代码:: BucketAlreadyExists

列出容器的对象

要列出容器中的对象，请使用 API 版本、账户和容器名称发出请求。您可以指定查询参数来过滤完整列表，或者省略参数以返回容器中存储的前 10,000 个对象名称的列表。GET request with the API version, account, and the name of the container. You can specify query parameters to filter the full list, or leave out the parameters to return a list of the first 10,000 object names stored in the container.

语法

GET /{api version}/{container} HTTP/1.1
     Host: {fqdn}
     X-Auth-Token: {auth-token}

参数

format

描述:: 定义结果的格式。
类型:: 字符串
有效值:: json | xml
必需:: 否

prefix

描述:: 将结果集限制为以指定前缀开头的对象。
类型:: 字符串
必需:: 否

marker

描述:: 返回大于标记值的列表。
类型:: 字符串
必需:: 否

limit

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

delimiter

描述:: 前缀和对象名其余部分之间的分隔符。
类型:: 字符串
必需:: 否

path

描述:: 对象的伪分层路径。
类型:: 字符串
必需:: 否

allow_unordered

描述:: 允许结果无序返回以减少计算开销。不能与delimiter.
类型:: 布尔值
必需:: 否
非标准扩展:: 是

响应实体

container

描述:: 容器。
类型:: 容器

object

描述:: 容器中的一个对象。
类型:: 容器

name

描述:: 容器中的一个对象名称。
类型:: 字符串

hash

描述:: 对象内容的哈希码。
类型:: 字符串

last_modified

描述:: 对象内容最后一次修改的时间。
类型:: 日期

content_type

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

更新容器的 ACL

当用户创建容器时，用户默认具有对容器的读取和写入权限。要允许其他用户读取容器的内容或向容器写入，您必须明确启用用户。*。Cephadm 还支持使用X-Container-Read或X-Container-Write设置，这实际上使所有用户都能够从容器读取或向容器写入。设置*使容器公开。也就是说，它允许匿名用户从容器读取或向容器写入。

Note

如果您计划为 Swift API 暴露公共读取 ACL 功能，强烈建议在端点定义中包含 Swift 账户名称，以便最接近地模拟原生 OpenStack Swift 的行为。为此，请设置ceph.conf configuration option rgw swift account in url = true, and update your Keystone endpoint to the URL suffix /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 的逗号分隔字符串值。
必需:: 否

添加/更新容器元数据

要向容器添加元数据，请使用 API 版本、账户和容器名称发出请求。您必须具有对容器的写入权限才能添加或更新元数据。POST request with the API version, account, and container name. You must have write permissions on the container to add or update metadata.

语法

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}

描述:: 一个用户定义的元数据键，它接受任意字符串值。
类型:: 字符串
必需:: 否

为容器启用对象版本控制

要为容器启用对象版本控制，请使用 API 版本、账户和容器名称发出请求。您必须具有对容器的写入权限才能添加或更新元数据。POST request with the API version, account, and container name. You must have write permissions on the container to add or update metadata.

Note

radosgw 默认不启用对象版本控制；您必须设置rgw swift versioning enabled = true in ceph.conf来启用此功能。

语法

POST /{api version}/{account}/{container} HTTP/1.1
Host: {fqdn}
     X-Auth-Token: {auth-token}
     X-Versions-Location: {archive-container}

请求头

X-Versions-Location

描述:: 一个容器名称（“归档容器”），它将用于存储在当前容器中（“当前容器”）的对象的版本。归档容器在引用时不必存在，但在当前容器上设置POST request is made on (the “current container”). The archive container need not exist at the time it is being referenced, but once X-Versions-Location is set on the current container, and object versioning is thus enabled, the archive container must exist before any further objects are updated or deleted in the current container.

Note

X-Versions-Location是 radosgw 解释的唯一与版本控制相关的标头。X-History-Location，由原生 OpenStack Swift 支持，目前 radosgw 不支持。
类型:: 字符串
必需:: 否（如果此标头与空值一起传递，当前容器的对象版本控制将被禁用，但归档容器仍然存在。）

删除容器

要删除容器，请使用 API 版本、账户和容器名称发出请求。容器必须为空。如果您想检查容器是否为空，请对容器执行DELETE请求。成功删除容器后，您将能够重用容器名称。HEAD request against the container. Once you have successfully removed the container, you will be able to reuse the container name.

语法

DELETE /{api version}/{account}/{container} HTTP/1.1
Host: {fqdn}
X-Auth-Token: {auth-token}

HTTP响应

204

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

由 Ceph 基金会带给您

Ceph 文档是一个社区资源，由非盈利的 Ceph 基金会资助和托管Ceph Foundation. 如果您想支持这一点和我们的其他工作，请考虑加入现在加入.