支持控制台（Console）开发人员开始试用联系人

3.4. S3 存储桶操作

作为开发人员，您可以通过 Ceph 对象网关对 Amazon S3 应用程序编程接口(API)执行存储桶操作。

下表列出了存储桶的 Amazon S3 功能操作，以及功能的支持状态。

表 3.2. bucket 操作
功能Status备注

List Buckets

支持

 

创建 Bucket

支持

不同的一组可实施 ACL。

Put Bucket Website

支持

 

Get Bucket Website

支持

 

Delete Bucket Website

支持

 

bucket Lifecycle

部分支持

支持 Expiration, NoncurrentVersionExpiration 和 AbortIncompleteMultipartUpload。

Put Bucket Lifecycle

部分支持

支持 Expiration, NoncurrentVersionExpiration 和 AbortIncompleteMultipartUpload。

Delete Bucket Lifecycle

支持

 

Get Bucket Objects

支持

 

bucket 位置

支持

 

Get Bucket Version

支持

 

Put Bucket Version

支持

 

删除 Bucket

支持

 

获取 Bucket ACL

支持

不同的可处理 ACL 集

放置 Bucket ACL

支持

不同的可处理 ACL 集

get Bucket cors

支持

 

put Bucket cors

支持

 

Delete Bucket cors

支持

 

列出 Bucket Object Versions

支持

 

head Bucket

支持

 

List Bucket Multipart Uploads

支持

 

bucket Policies

部分支持

 

Get a Bucket Request Payment

支持

 

Put a Bucket Request Payment

支持

 

多租户 Bucket 操作

支持

 

get PublicAccessBlock

支持

 

放置 PublicAccessBlock

支持

 

Delete PublicAccessBlock

支持

 

3.4.1. 先决条件

  • 一个正在运行的 Red Hat Ceph Storage 集群。
  • RESTful 客户端。

3.4.2. S3 创建存储桶通知

在 bucket 级别上创建 bucket 通知。通知配置具有 Red Hat Ceph Storage 对象网关 S3 事件，即 ObjectCreated 和 ObjectRemoved。这些需要发布，以及发送 bucket 通知的目的地。bucket 通知是 S3 操作。

要为 s3:objectCreate 和 s3:objectRemove 事件创建存储桶通知，可使用 PUT：

示例

client.put_bucket_notification_configuration(
   Bucket=bucket_name,
   NotificationConfiguration={
       'TopicConfigurations': [
           {
               'Id': notification_name,
               'TopicArn': topic_arn,
               'Events': ['s3:ObjectCreated:*', 's3:ObjectRemoved:*']
           }]})

重要

红帽支持 ObjectCreate 事件，如 put, post, multipartUpload, 和 copy。红帽还支持 ObjectRemove 事件，如 object_delete 和 s3_multi_object_delete。

请求实体

NotificationConfiguration
描述
TopicConfiguration 实体列表。
Type
Container
必需
是
TopicConfiguration
描述
事件主题的 Id, Topic 和 list。
Type
Container
必需
是
id
描述
通知的名称。
Type
字符串
必需
是
Topic
描述

Topic Amazon Resource Name(ARN)

注意

必须事先创建主题。

Type
字符串
必需
是
事件
描述
支持的事件列表。可以使用多个事件实体。如果省略，则处理所有事件。
Type
字符串
必需
否
Filter
描述
S3Key、S3Metadata 和 S3Tags 实体。
Type
Container
必需
否
S3Key
描述
FilterRule 实体列表，用于根据对象密钥进行过滤。列表中最多可以有 3 个实体，例如，Name 为 prefix, suffix, 或 regex。列表中的所有过滤规则必须与过滤器匹配。
类型
Container
必需
否
S3Metadata
描述
FilterRule 实体列表，用于根据对象元数据进行过滤。列表中的所有过滤规则必须与对象中定义的元数据匹配。但是，如果对象具有过滤器中没有列出的其他元数据条目，则对象仍然匹配。
Type
Container
必需
否
S3Tags
描述
FilterRule 实体列表，用于根据对象标签进行过滤。列表中的所有过滤规则必须与对象中定义的标签匹配。但是，如果对象没有列在过滤器中，则对象仍然匹配。
Type
Container
必需
否
S3Key.FilterRule
描述
Name 和 Value 实体。name 是 : 前缀、后缀 或 regex。Value 将保留用于匹配该密钥的密钥前缀、键后缀或正则表达式。
Type
Container
必需
是
S3Metadata.FilterRule
描述
Name 和 Value 实体。name 是 x-amz-meta-xxx 等 metadata 属性的名称。该值是此属性的预期值。
Type
Container
必需
是
S3Tags.FilterRule
描述
Name 和 Value 实体。name 是 tag 键，值为 tag 值。
Type
Container
必需
是

HTTP 响应

400
状态代码
MalformedXML
描述
XML 没有良好的格式。
400
状态代码
InvalidArgument
描述
缺少 Id 或 missing 或 invalid topic ARN 或无效事件。
404
状态代码
NoSuchBucket
描述
bucket 不存在。
404
状态代码
NoSuchKey
描述
主题不存在。

3.4.3. S3 获取存储桶通知

获取特定的通知，或列出存储桶中配置的所有通知。

语法

Get /BUCKET?notification=NOTIFICATION_ID HTTP/1.1
Host: cname.domain.com
Date: date
Authorization: AWS ACCESS_KEY:HASH_OF_HEADER_AND_SECRET

示例

Get /testbucket?notification=testnotificationID HTTP/1.1
Host: cname.domain.com
Date: date
Authorization: AWS ACCESS_KEY:HASH_OF_HEADER_AND_SECRET

响应示例

<NotificationConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <TopicConfiguration>
        <Id></Id>
        <Topic></Topic>
        <Event></Event>
        <Filter>
            <S3Key>
                <FilterRule>
                    <Name></Name>
                    <Value></Value>
                </FilterRule>
                 </S3Key>
             <S3Metadata>
                 <FilterRule>
                     <Name></Name>
                     <Value></Value>
                 </FilterRule>
             </S3Metadata>
             <S3Tags>
                 <FilterRule>
                     <Name></Name>
                     <Value></Value>
                 </FilterRule>
             </S3Tags>
         </Filter>
    </TopicConfiguration>
</NotificationConfiguration>

注意

notification 子资源返回存储桶通知配置或空 notification Configuration 元素。调用者必须是存储桶所有者。

请求实体

notification-id
描述
通知的名称。如果未提供 ID，则会列出所有通知。
Type
字符串
NotificationConfiguration
描述
TopicConfiguration 实体列表。
Type
Container
必需
是
TopicConfiguration
描述
事件主题的 Id, Topic 和 list。
Type
Container
必需
是
id
描述
通知的名称。
Type
字符串
必需
是
Topic
描述

Topic Amazon Resource Name(ARN)

注意

必须事先创建主题。

Type
字符串
必需
是
事件
描述
处理的事件。可能存在多个事件实体。
Type
字符串
必需
是
Filter
描述
指定配置的过滤器。
Type
Container
必需
否

HTTP 响应

404
状态代码
NoSuchBucket
描述
bucket 不存在。
404
状态代码
NoSuchKey
描述
如果提供了通知，则不会存在。

3.4.4. S3 删除存储桶通知

从存储桶中删除特定或所有通知。

注意

通知删除是对 S3 通知 API 的扩展。当存储桶被删除时，存储桶上所有定义的通知都会被删除。删除一个未知的示例 double delete 的通知不会被视为错误。

要删除特定或所有通知，请使用 DELETE：

语法

DELETE /BUCKET?notification=NOTIFICATION_ID HTTP/1.1

示例

DELETE /testbucket?notification=testnotificationID HTTP/1.1

请求实体

notification-id
描述
通知的名称。如果没有提供通知 ID，则存储桶上的所有通知都会被删除。
Type
字符串

HTTP 响应

404
状态代码
NoSuchBucket
描述
bucket 不存在。

3.4.5. 访问存储桶主机名

访问存储桶时有两种不同的模式。第一种方法和首选的方法将 bucket 标识为 URI 中的顶级目录。

示例

GET /mybucket HTTP/1.1
Host: cname.domain.com

第二种方法通过虚拟 bucket 主机名标识 bucket。

示例

GET / HTTP/1.1
Host: mybucket.cname.domain.com

提示

红帽首选第一种方法，因为第二种方法需要昂贵的域认证和 DNS 通配符。

3.4.6. S3 列表存储桶

GET / 返回由发出请求的用户创建的 bucket 列表。GET / 仅返回由经过身份验证的用户创建的存储桶。您不能发出匿名请求。

语法

GET / HTTP/1.1
Host: cname.domain.com

Authorization: AWS ACCESS_KEY:HASH_OF_HEADER_AND_SECRET

响应实体

Buckets
描述
用于存储桶列表的容器。
Type
Container
Bucket
描述
用于存储桶信息的容器。
Type
Container
名称
描述
bucket 名称.
Type
字符串
CreationDate
描述
创建存储桶时的 UTC 时间。
Type
Date
ListAllMyBucketsResult
描述
用于结果的容器。
Type
Container
所有者
描述
bucket 所有者的 ID 和 DisplayName 的容器。
Type
Container
ID
描述
bucket 所有者的 ID。
Type
字符串
DisplayName
描述
bucket 所有者的显示名称。
Type
字符串

3.4.7. S3 返回存储桶对象列表

返回存储桶对象列表。

语法

GET /BUCKET?max-keys=25 HTTP/1.1
Host: cname.domain.com

参数

prefix
描述
仅返回包含指定前缀的对象。
Type
字符串
delimiter
描述
前缀与其他对象名称之间的分隔符。
Type
字符串
marker
描述
返回的对象列表的开头索引。
Type
字符串
max-keys
描述
要返回的最大密钥数。默认值为 1000。
Type
整数

HTTP 响应

200
状态代码
确定
描述
检索的 bucket。

GET /BUCKET 返回存储桶的容器，并带有以下字段：

bucket 响应实体

ListBucketResult
描述
容器，用于对象列表。
Type
实体
名称
描述
其内容要返回的存储桶的名称。
Type
字符串
prefix
描述
对象密钥的前缀。
Type
字符串
Marker
描述
返回的对象列表的开头索引。
Type
字符串
MaxKeys
描述
返回的最大键数。
Type
整数
Delimiter
描述
如果设置，具有相同前缀的对象将显示在 CommonPrefixes 列表中。
Type
字符串
IsTruncated
描述
如果为 true，则仅返回存储桶内容的子集。
Type
布尔值
CommonPrefixes
描述
如果多个对象包含相同的前缀，它们将显示在此列表中。
Type
Container

ListBucketResult 包含对象，其中每个对象都在一个 Contents 容器中。

对象响应实体

内容
描述
对象的容器。
Type
Object
键
描述
对象的密钥。
Type
字符串
LastModified
描述
对象的最后修改的日期和时间。
Type
Date
ETag
描述
对象的 MD-5 哈希。etag 是一个实体标签。
Type
字符串
大小
描述
对象的大小。
Type
整数
StorageClass
描述
应始终返回 STANDARD。
Type
字符串

3.4.8. S3 创建新存储桶

创建新存储桶。要创建存储桶，必须有用户 ID 和有效的 AWS 访问密钥 ID 才能验证请求。您不能以匿名用户身份创建存储桶。

约束

通常，存储桶名称应该遵循域名约束。

  • bucket 名称必须是唯一的。
  • bucket 名称不能格式化为 IP 地址。
  • bucket 名称长度可在 3 到 63 个字符之间。
  • bucket 名称不得包含大写字符或下划线。
  • bucket 名称必须以小写或数字开头。
  • bucket 名称可以包含短划线(-)。
  • bucket 名称必须是由一个或多个标签组成的系列。相邻标签由单个句点(.)分隔。bucket 名称可以包含小写字母、数字和连字符。每个标签必须以小写字母或数字开头和结尾。
注意

如果 rgw_relaxed_s3_bucket_names 设为 true，则上述限制会被放松。bucket 名称仍必须是唯一的，不能以 IP 地址进行格式化，并包含长度最多 255 个字符的字母、数字、句点、横线和下划线。

语法

PUT /BUCKET HTTP/1.1
Host: cname.domain.com
x-amz-acl: public-read-write

Authorization: AWS ACCESS_KEY:HASH_OF_HEADER_AND_SECRET

参数

x-amz-acl
描述
可签署 ACL.
有效值
私有,public-read,public-read-write,authenticated-read
必需
否

HTTP 响应

如果存储桶名称是唯一的、约束和未使用，则操作会成功。如果具有相同名称的存储桶已经存在，并且该用户是 bucket 所有者，则操作将成功。如果存储桶名称已经在使用中，则操作将失败。

409
状态代码
BucketAlreadyExists
描述
bucket 已存在于不同用户的所有权下。

3.4.9. S3 放置存储桶网站

put bucket 网站 API 设置网站子资源中指定的 网站 配置。要将存储桶配置为网站，可在存储桶中添加 website 子资源。

注意

Put 操作需要 S3:PutBucketWebsite 权限。默认情况下，只有存储桶所有者可以配置附加到存储桶的网站。

语法

PUT /BUCKET?website-configuration=HTTP/1.1

示例

PUT /testbucket?website-configuration=HTTP/1.1

其它资源

  • 有关此 API 调用的更多信息，请参阅 S3 API。

3.4.10. S3 获取存储桶网站

get bucket 网站 API 检索网站子资源中指定的 网站 配置。

注意

Get 操作需要 S3:GetBucketWebsite 权限。默认情况下，只有存储桶所有者可以读取存储桶网站配置。

语法

GET /BUCKET?website-configuration=HTTP/1.1

示例

GET /testbucket?website-configuration=HTTP/1.1

其它资源

  • 有关此 API 调用的更多信息，请参阅 S3 API。

3.4.11. S3 删除存储桶网站

删除存储桶网站 API 会删除存储桶的网站配置。

语法

DELETE /BUCKET?website-configuration=HTTP/1.1

示例

DELETE /testbucket?website-configuration=HTTP/1.1

其它资源

  • 有关此 API 调用的更多信息，请参阅 S3 API。

3.4.12. S3 删除存储桶

删除存储桶。您可以在成功删除存储桶后重复使用存储桶名称。

语法

DELETE /BUCKET HTTP/1.1
Host: cname.domain.com

Authorization: AWS ACCESS_KEY:HASH_OF_HEADER_AND_SECRET

HTTP 响应

204
状态代码
无内容
描述
已删除存储桶。

3.4.13. S3 存储桶生命周期

您可以使用存储桶生命周期配置来管理对象，以便在其生命周期内有效存储它们。Ceph 对象网关中的 S3 API 支持 AWS 存储桶生命周期操作的子集：

  • Expiration: 定义存储桶内对象的寿命。它取对象应处于活动状态或过期日期的天数，指向 Ceph 对象网关将删除对象。如果存储桶没有启用版本控制，Ceph 对象网关将永久删除对象。如果 bucket 启用版本控制，Ceph 对象网关为当前版本创建删除标记，然后删除当前版本。
  • NoncurrentVersionExpiration ：这定义了存储桶中非当前对象版本的寿命。要使用此功能，存储桶必须启用版本控制。它取非当前对象应保持的天数，指向 Ceph 对象网关会删除非当前对象。
  • AbortIncompleteMultipartUpload ：这定义了未完成的多部分上传在中止前的天数。

生命周期配置包含使用 <Rule> 元素的一个或多个规则。

示例

<LifecycleConfiguration>
    <Rule>
      <Prefix/>
      <Status>Enabled</Status>
      <Expiration>
        <Days>10</Days>
      </Expiration>
    </Rule>
</LifecycleConfiguration>

根据您在生命周期规则中指定的 < Filter > 元素，生命周期规则可应用到存储桶中的所有对象或子集。您可以通过几种方法指定过滤器：

  • 密钥前缀
  • 对象标签
  • 密钥前缀和一个或多个对象标签

密钥前缀

您可以根据密钥名称前缀，将生命周期规则应用到对象的子集。例如，指定 <keypre/> 将应用到以 keypre/ 开头的对象： 

<LifecycleConfiguration>
    <Rule>
        <Status>Enabled</Status>
        <Filter>
           <Prefix>keypre/</Prefix>
        </Filter>
    </Rule>
</LifecycleConfiguration>

您还可以将不同的生命周期规则应用到具有不同密钥前缀的对象： 

<LifecycleConfiguration>
    <Rule>
        <Status>Enabled</Status>
        <Filter>
           <Prefix>keypre/</Prefix>
        </Filter>
    </Rule>
    <Rule>
        <Status>Enabled</Status>
        <Filter>
           <Prefix>mypre/</Prefix>
        </Filter>
    </Rule>
</LifecycleConfiguration>

对象标签

您可以使用 <Key> 和 <Value> 元素将生命周期规则应用到带有特定标签的对象： 

<LifecycleConfiguration>
    <Rule>
        <Status>Enabled</Status>
        <Filter>
           <Tag>
              <Key>key</Key>
              <Value>value</Value>
           </Tag>
        </Filter>
    </Rule>
</LifecycleConfiguration>

前缀和一个或多个标签

在生命周期规则中，您可以根据密钥前缀和一个或多个标签指定过滤器。它们必须包括在 <And> 项中。过滤器只能有一个前缀，以及零个或多个标签： 

<LifecycleConfiguration>
    <Rule>
        <Status>Enabled</Status>
        <Filter>
          <And>
             <Prefix>key-prefix</Prefix>
             <Tag>
                <Key>key1</Key>
                <Value>value1</Value>
             </Tag>
             <Tag>
                <Key>key2</Key>
                <Value>value2</Value>
             </Tag>
              ...
          </And>
        </Filter>
    </Rule>
</LifecycleConfiguration>

其它资源

3.4.14. S3 GET 存储桶生命周期

要获取存储桶生命周期，请使用 GET 并指定目标存储桶。

语法

GET /BUCKET?lifecycle HTTP/1.1
Host: cname.domain.com

Authorization: AWS ACCESS_KEY:HASH_OF_HEADER_AND_SECRET

请求 Headers

有关常见请求标头的更多信息，请参阅附录 B 中的 S3 通用请求标头。

响应

响应中包含存储桶生命周期及其元素。

3.4.15. S3 创建或替换存储桶生命周期

要创建或替换存储桶生命周期，请使用 PUT，并指定目标存储桶和生命周期配置。Ceph 对象网关仅支持 S3 生命周期功能的子集。

语法

PUT /BUCKET?lifecycle HTTP/1.1
Host: cname.domain.com

Authorization: AWS ACCESS_KEY:HASH_OF_HEADER_AND_SECRET
<LifecycleConfiguration>
  <Rule>
    <Expiration>
      <Days>10</Days>
    </Expiration>
  </Rule>
    ...
  <Rule>
  </Rule>
</LifecycleConfiguration>

请求 Headers

content-md5
描述
消息的 base64 编码 MD-5 哈希
有效值
字符串没有默认值或限制。
必需
否

其它资源

  • 有关 Amazon S3 通用请求标头 的更多信息，请参阅 Red Hat Ceph Storage Developer Guide 附录 B 中的 S3 常见请求标头部分。
  • 有关 Amazon S3 存储桶生命周期的更多信息，请参阅 Red Hat Ceph Storage Developer Guide 中的 S3 存储桶生命周期 部分。

3.4.16. S3 删除存储桶生命周期

要删除存储桶生命周期，请使用 DELETE 并指定目标存储桶。

语法

DELETE /BUCKET?lifecycle HTTP/1.1
Host: cname.domain.com

Authorization: AWS ACCESS_KEY:HASH_OF_HEADER_AND_SECRET

请求 Headers

请求不包含任何特殊元素。

响应

响应返回常见的响应状态。

其它资源

  • 有关 Amazon S3 通用请求标头 的更多信息，请参阅 Red Hat Ceph Storage Developer Guide 附录 B 中的 S3 常见请求标头部分。
  • 有关 Amazon S3 通用响应状态代码 的更多信息，请参阅 Red Hat Ceph Storage Developer Guide 附录 C 中的 S3 常见响应状态代码部分。

3.4.17. S3 get bucket 位置

检索 bucket 的 zone group。用户需要是存储桶所有者才能调用它。通过在 PUT 请求期间提供 LocationConstraint，可以将 bucket 限制到 zone group。

将位置 子资源添加到存储桶资源，如下所示。

语法

GET /BUCKET?location HTTP/1.1
Host: cname.domain.com

Authorization: AWS ACCESS_KEY:HASH_OF_HEADER_AND_SECRET

响应实体

LocationConstraint
描述
bucket 所在的 zone 组，即 default zone group 的空字符串。
类型
字符串

3.4.18. S3 获取存储桶版本

检索 bucket 的版本控制状态。用户需要是存储桶所有者才能调用它。

将 版本 子资源添加到存储桶资源，如下所示。

语法

GET /BUCKET?versioning HTTP/1.1
Host: cname.domain.com

Authorization: AWS ACCESS_KEY:HASH_OF_HEADER_AND_SECRET

3.4.19. S3 设置存储桶版本

此子资源设置现有存储桶的 versioning 状态。用户需要是存储桶所有者来设置版本控制状态。如果存储桶上没有设置 versioning 状态，则没有版本状态。执行 GET 版本请求不会返回 versioning 状态值。

设置存储桶版本状态：

启用 ：为存储桶中的对象启用版本控制。添加到存储桶的所有对象都会获得一个唯一的版本 ID。已暂停 ：禁用存储桶中对象的版本控制。添加到存储桶的所有对象都会接收版本 ID null。

语法

PUT /BUCKET?versioning HTTP/1.1

示例

PUT /testbucket?versioning HTTP/1.1

bucket 请求实体

VersioningConfiguration
描述
用于请求的容器。
Type
Container
Status
描述
设置存储桶的版本控制状态。有效值： Suspended/Enabled
Type
字符串

3.4.20. S3 获取存储桶访问控制列表

检索 bucket 访问控制列表。用户需要是存储桶所有者，或被授予存储桶的 READ_ACP 权限。

将 acl 子资源添加到存储桶请求，如下所示。

语法

GET /BUCKET?acl HTTP/1.1
Host: cname.domain.com

Authorization: AWS ACCESS_KEY:HASH_OF_HEADER_AND_SECRET

响应实体

AccessControlPolicy
描述
用于响应的容器。
Type
Container
AccessControlList
描述
ACL 信息的容器。
Type
Container
所有者
描述
bucket 所有者的 ID 和 DisplayName 的容器。
Type
Container
ID
描述
bucket 所有者的 ID。
Type
字符串
DisplayName
描述
bucket 所有者的显示名称。
Type
字符串
Grant
描述
适用于 Grantee 和 Permission 的容器。
Type
Container
Grantee
描述
允许权限的用户的 DisplayName 和 ID 的容器。
Type
Container
权限
描述
提供给 Grantee 存储桶的权限。
Type
字符串

3.4.21. S3 放置存储桶访问控制列表

设置到现有存储桶的访问控制。用户需要是存储桶所有者，或被授予存储桶的 WRITE_ACP 权限。

将 acl 子资源添加到存储桶请求，如下所示。

语法

PUT /BUCKET?acl HTTP/1.1

请求实体

S3 列表多部分上传

AccessControlList
描述
ACL 信息的容器。
Type
Container
所有者
描述
bucket 所有者的 ID 和 DisplayName 的容器。
Type
Container
ID
描述
bucket 所有者的 ID。
Type
字符串
DisplayName
描述
bucket 所有者的显示名称。
Type
字符串
Grant
描述
适用于 Grantee 和 Permission 的容器。
Type
Container
Grantee
描述
允许权限的用户的 DisplayName 和 ID 的容器。
Type
Container
权限
描述
提供给 Grantee 存储桶的权限。
Type
字符串

3.4.22. S3 get bucket cors

检索为存储桶设置的 cors 配置信息。用户需要是存储桶所有者，或被授予存储桶的 READ_ACP 权限。

将 cors 子资源添加到存储桶请求，如下所示。

语法

GET /BUCKET?cors HTTP/1.1
Host: cname.domain.com

Authorization: AWS ACCESS_KEY:HASH_OF_HEADER_AND_SECRET

3.4.23. S3 put bucket cors

为存储桶设置 cors 配置。用户需要是存储桶所有者，或被授予存储桶的 READ_ACP 权限。

将 cors 子资源添加到存储桶请求，如下所示。

语法

PUT /BUCKET?cors HTTP/1.1
Host: cname.domain.com

Authorization: AWS ACCESS_KEY:HASH_OF_HEADER_AND_SECRET

3.4.24. S3 删除存储桶 cors

删除为存储桶设置的 cors 配置信息。用户需要是存储桶所有者，或被授予存储桶的 READ_ACP 权限。

将 cors 子资源添加到存储桶请求，如下所示。

语法

DELETE /BUCKET?cors HTTP/1.1
Host: cname.domain.com

Authorization: AWS ACCESS_KEY:HASH_OF_HEADER_AND_SECRET

3.4.25. S3 列表存储桶对象版本

返回存储桶中所有对象版本的元数据列表。需要指向存储桶的 READ 访问权限。

将 version 子资源添加到存储桶请求，如下所示。

语法

GET /BUCKET?versions HTTP/1.1
Host: cname.domain.com

Authorization: AWS ACCESS_KEY:HASH_OF_HEADER_AND_SECRET

您可以为 GET /BUCKET?version 指定参数，但不需要它们。

参数

prefix
描述
返回的 in-progress 上传，其密钥包含指定前缀。
Type
字符串
delimiter
描述
前缀与其他对象名称之间的分隔符。
Type
字符串
key-marker
描述
上传列表的开头标记。
Type
字符串
max-keys
描述
最大的 in-progress 上传数。默认值为 1000。
Type
整数
version-id-marker
描述
指定用于开始列表的对象版本。
Type
字符串

响应实体

KeyMarker
描述
通过 key-marker 请求参数指定的密钥标记（如果有）。
Type
字符串
NextKeyMarker
描述
如果 IsTruncated 为 true，则后续请求中使用的密钥标记。
类型
字符串
NextUploadIdMarker
描述
如果 IsTruncated 为 true，则上传 ID 标记用于后续请求。
类型
字符串
IsTruncated
描述
如果为 true，则仅返回存储桶上传内容的子集。
Type
布尔值
大小
描述
上传部分的大小。
Type
整数
DisplayName
描述
所有者的显示名称。
Type
字符串
ID
描述
所有者的 ID。
Type
字符串
所有者
描述
用于拥有对象的用户的 ID 和 DisplayName 的容器。
Type
Container
StorageClass
描述
用于存储生成的对象的方法。STANDARD 或 REDUCED_REDUNDANCY
Type
字符串
版本
描述
版本信息的容器。
Type
Container
versionId
描述
对象的版本 ID。
Type
字符串
versionIdMarker
描述
已截断响应中密钥的最后一个版本。
Type
字符串

3.4.26. S3 头存储桶

在存储桶上调用 HEAD，以确定它是否存在以及调用者是否有访问权限。如果存储桶存在并且调用者具有权限，则返回 200 OK ；如果存储桶不存在，则返回 404 Not Found。如果存储桶存在，但调用者没有访问权限，则返回 403 Forbidden。

语法

HEAD /BUCKET HTTP/1.1
Host: cname.domain.com
Date: date
Authorization: AWS ACCESS_KEY:HASH_OF_HEADER_AND_SECRET

3.4.27. S3 列表多部分上传

GET /?uploads 返回当前 in-progress 多部件上传的列表，即，应用程序会启动多部分上传，但该服务还没有完成所有上传。

语法

GET /BUCKET?uploads HTTP/1.1

您可以为 GET /BUCKET?uploads 指定参数，但参数都不是必需的。

参数

prefix
描述
返回的 in-progress 上传，其密钥包含指定前缀。
Type
字符串
delimiter
描述
前缀与其他对象名称之间的分隔符。
Type
字符串
key-marker
描述
上传列表的开头标记。
类型
字符串
max-keys
描述
最大的 in-progress 上传数。默认值为 1000。
Type
整数
max-uploads
描述
多部分上传的最大数量。范围为 1-1000。默认值为 1000。
类型
整数
version-id-marker
描述
如果没有指定 key-marker，则忽略。指定第一个上传的 ID 以字典顺序（位于 ）或遵循 ID 的顺序来列出。
Type
字符串

响应实体

ListMultipartUploadsResult
描述
用于结果的容器。
Type
Container
ListMultipartUploadsResult.Prefix
描述
prefix 请求参数中指定的前缀（若有）。
Type
字符串
Bucket
描述
将接收存储桶内容的存储桶。
Type
字符串
KeyMarker
描述
通过 key-marker 请求参数指定的密钥标记（如果有）。
Type
字符串
UploadIdMarker
描述
upload-id-marker 请求参数中指定的标记（若有）。
Type
字符串
NextKeyMarker
描述
如果 IsTruncated 为 true，则后续请求中使用的密钥标记。
Type
字符串
NextUploadIdMarker
描述
如果 IsTruncated 为 true，则上传 ID 标记用于后续请求。
Type
字符串
MaxUploads
描述
max-uploads 请求参数指定的最大上传。
Type
整数
Delimiter
描述
如果设置，具有相同前缀的对象将显示在 CommonPrefixes 列表中。
Type
字符串
IsTruncated
描述
如果为 true，则仅返回存储桶上传内容的子集。
Type
布尔值
上传
描述
Key、UploadId、InitiatorOwner、StorageClass 和 Initiated 元素的容器。
Type
Container
键
描述
在多部分上传完成后，对象的键。
Type
字符串
UploadId
描述
标识多部分上传的 ID。
Type
字符串
initiator
描述
包含开始上传的用户的 ID 和 DisplayName。
Type
Container
DisplayName
描述
启动器的显示名称。
Type
字符串
ID
描述
启动器的 ID。
Type
字符串
所有者
描述
拥有上传对象的用户的 ID 和 DisplayName 的容器。
Type
Container
StorageClass
描述
用于存储生成的对象的方法。STANDARD 或 REDUCED_REDUNDANCY
Type
字符串
启动
描述
用户开始上传的日期和时间。
Type
Date
CommonPrefixes
描述
如果多个对象包含相同的前缀，它们将显示在此列表中。
Type
Container
CommonPrefixes.Prefix
描述
前缀 请求参数的前缀后键的子字符串。
Type
字符串

3.4.28. S3 存储桶策略

Ceph 对象网关支持应用到 bucket 的 Amazon S3 策略语言的子集。

创建和删除

Ceph 对象网关通过标准 S3 操作来管理 S3 Bucket 策略，而不使用 radosgw-admin CLI 工具。

管理员可以使用 s3cmd 命令来设置或删除策略。

示例

$ cat > examplepol
{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": {"AWS": ["arn:aws:iam::usfolks:user/fred"]},
    "Action": "s3:PutObjectAcl",
    "Resource": [
      "arn:aws:s3:::happybucket/*"
    ]
  }]
}

$ s3cmd setpolicy examplepol s3://happybucket
$ s3cmd delpolicy s3://happybucket

限制

Ceph 对象网关仅支持以下 S3 操作：

  • s3:AbortMultipartUpload
  • s3:CreateBucket
  • s3:DeleteBucketPolicy
  • s3:DeleteBucket
  • s3:DeleteBucketWebsite
  • s3:DeleteObject
  • s3:DeleteObjectVersion
  • s3:GetBucketAcl
  • s3:GetBucketCORS
  • s3:GetBucketLocation
  • s3:GetBucketPolicy
  • s3:GetBucketRequestPayment
  • s3:GetBucketVersioning
  • s3:GetBucketWebsite
  • s3:GetLifecycleConfiguration
  • s3:GetObjectAcl
  • s3:GetObject
  • s3:GetObjectTorrent
  • s3:GetObjectVersionAcl
  • s3:GetObjectVersion
  • s3:GetObjectVersionTorrent
  • s3:ListAllMyBuckets
  • s3:ListBucketMultiPartUploads
  • s3:ListBucket
  • s3:ListBucketVersions
  • s3:ListMultipartUploadParts
  • s3:PutBucketAcl
  • s3:PutBucketCORS
  • s3:PutBucketPolicy
  • s3:PutBucketRequestPayment
  • s3:PutBucketVersioning
  • s3:PutBucketWebsite
  • s3:PutLifecycleConfiguration
  • s3:PutObjectAcl
  • s3:PutObject
  • s3:PutObjectVersionAcl
注意

Ceph 对象网关不支持在用户、组或角色上设置策略。

Ceph 对象网关使用 RGW 的"租户"标识符来代替 Amazon twelve-bit 帐户 ID。希望使用 Amazon Web Service(AWS)S3 和 Ceph 对象网关 S3 之间的策略，必须在创建用户时将 Amazon 帐户 ID 用作租户 ID。

使用 AWS S3 时，所有租户共享一个命名空间。与之相反，Ceph 对象网关为每个租户提供自己的 bucket 命名空间。目前，Ceph 对象网关客户端试图访问属于另一个租户 MUST 地址的 bucket，作为 S3 请求中的 tenant:bucket。

在 AWS 中，存储桶策略可以授予其他帐户的访问权限，然后该帐户所有者可以向具有用户权限的单独用户授予访问权限。由于 Ceph 对象网关尚不支持用户、角色和组权限，因此帐户所有者需要直接向个别用户授予访问权限。

重要

授予 bucket 的完整帐户访问权限，授予该帐户中所有用户的访问权限。

bucket 策略 不支持 字符串插值。

Ceph 对象网关支持以下条件键：

  • aws:CurrentTime
  • aws:EpochTime
  • aws:PrincipalType
  • aws:Referer
  • aws:SecureTransport
  • aws:SourceIp
  • aws:UserAgent
  • aws:username

Ceph 对象网关仅支持以下条件键进行 ListBucket 操作：

  • s3:prefix
  • s3:delimiter
  • s3:max-keys

对 Swift 的影响

Ceph 对象网关提供在 Swift API 下设置 bucket 策略的功能。但是，使用 S3 API 管理 Swift 以及 S3 操作设置的存储桶策略。

Ceph 对象网关将 Swift 凭据与策略中指定的主体匹配。

3.4.29. S3 获取存储桶上的请求支付配置

使用 requestPayment 子资源返回存储桶的请求支付配置。用户需要是存储桶所有者，或被授予存储桶的 READ_ACP 权限。

将 requestPayment 子资源添加到存储桶请求，如下所示。

语法

GET /BUCKET?requestPayment HTTP/1.1
Host: cname.domain.com

Authorization: AWS ACCESS_KEY:HASH_OF_HEADER_AND_SECRET

3.4.30. S3 在存储桶上设置请求支付配置

使用 requestPayment 子资源来设置存储桶的请求支付配置。默认情况下，存储桶所有者需要从存储桶下载。此配置参数可让 bucket 所有者指定请求者将被请求及从存储桶下载的数据。

将 requestPayment 子资源添加到存储桶请求，如下所示。

语法

PUT /BUCKET?requestPayment HTTP/1.1
Host: cname.domain.com

请求实体

Payer
描述
指定下载和请求费用的支付费用。
Type
Enum
RequestPaymentConfiguration
描述
用于 Payer 的容器.
Type
Container

3.4.31. 多租户存储桶操作

当客户端应用访问 bucket 时，它始终与特定用户的凭据一同运行。在 Red Hat Ceph Storage 集群中，每个用户都属于一个租户。因此，如果没有明确指定租户，每个 bucket 操作在其上下文中都有一个隐式租户。因此，多租户与之前的版本完全兼容，只要引用的存储桶并引用用户属于同一租户。

已根据所使用的协议和身份验证系统，使用扩展来指定明确的租户会有所不同。

在以下示例中，冒号分隔租户和 bucket。因此，一个示例 URL 是： 

https://rgw.domain.com/tenant:bucket

相反，一个简单的 Python 示例将租户和存储桶方法本身分开：

示例

from boto.s3.connection import S3Connection, OrdinaryCallingFormat
  c = S3Connection(
    aws_access_key_id="TESTER",
    aws_secret_access_key="test123",
    host="rgw.domain.com",
    calling_format = OrdinaryCallingFormat()
  )
  bucket = c.get_bucket("tenant:bucket")

注意

无法利用多租户使用 S3-style 子域，因为主机名不能包含冒号或任何已在存储桶名称中无效的其他分隔符。使用句点会创建模糊的语法。因此，bucket-in-URL-path 格式必须与多租户一起使用。

其它资源

  • 如需了解更多信息，请参阅 Red Hat Ceph Storage Object Gateway 指南中的多租户部分（位于用户管理下）

3.4.32. S3 块公共访问

您可以使用 S3 Block Public Access 功能设置访问点、存储桶和帐户，以帮助您管理对 Amazon S3 资源的公共访问。

使用此功能、存储桶策略、访问点策略和对象权限可以被覆盖，以允许公共访问。默认情况下，新的 bucket、接入点和对象不允许公共访问。

Ceph 对象网关中的 S3 API 支持 AWS 公共访问设置的子集：

  • BlockPublicPolicy ：定义允许用户管理访问点和存储桶策略的设置。此设置不允许用户公开共享存储桶或其包含的对象。通过启用此设置，现有的访问点和存储桶策略不会受到影响。将这个选项设置为 TRUE 会导致 S3:

    • 拒绝 PUT Bucket 策略的调用。
    • 拒绝对所有 bucket 的相同访问点点的 PUT 访问点的调用。
重要

在帐户 级别应用此设置，以便用户无法更改特定存储桶的块公共访问设置。

注意

TRUE 设置仅在指定的策略允许公共访问时才有效。

  • RestrictPublicBuckets ：定义设置来限制对存储桶的访问或使用公共策略的接入点。限制适用于存储桶所有者帐户和访问点所有者帐户内的 AWS 服务主体和授权用户。这会阻止跨帐户访问访问访问点或 bucket，但指定的情况除外，同时仍然允许帐户中的用户管理访问点或存储桶。启用此设置不会影响现有的访问点或存储桶策略。它仅定义 Amazon S3 会阻止公共和跨帐户访问，以及从任何公共访问点或 bucket 策略派生的跨帐户访问，包括特定帐户的非公共委托。
注意

Red Hat Ceph Storage 目前不支持访问控制列表(ACL)。

除非另有定义，否则假定存储桶策略为 public。要阻止公共访问，存储桶策略必须只授予以下一个或多个值的访问权限：

注意

固定值不包含通配符(*)或 AWS Identity and Access Management Policy Variable。

  • AWS 主体、用户、角色或服务主体
  • 使用 aws:SourceIp的无类别域间路由(CIDRs)集
  • aws:SourceArn
  • aws:SourceVpc
  • aws:SourceVpce
  • aws:SourceOwner
  • aws:SourceAccount
  • s3:x-amz-server-side-encryption-aws-kms-key-id
  • aws:userid，在模式 AROLEID:*之外

  • s3:DataAccessPointArn

    注意

    在存储桶策略中使用时，这个值可以包含访问点名称的通配符，而无需渲染策略 public，只要帐户 ID 已修复。

  • s3:DataAccessPointPointAccount

以下示例策略被视为 public。

示例

{
		"Principal": "*",
		"Resource": "*",
		"Action": "s3:PutObject",
		"Effect": "Allow",
		"Condition": { "StringLike": {"aws:SourceVpc": "vpc-*"}}
	}

要使策略非公共，请包含具有固定值的任何条件键。

示例

{
		"Principal": "*",
		"Resource": "*",
		"Action": "s3:PutObject",
		"Effect": "Allow",
		"Condition": {"StringEquals": {"aws:SourceVpc": "vpc-91237329"}}
	}

其它资源

3.4.33. S3 GET PublicAccessBlock

要获得配置的 S3 Block Public Access 功能，请使用 GET 并指定目标 AWS 帐户。

语法

GET /v20180820/configuration/publicAccessBlock HTTP/1.1
Host: cname.domain.com
x-amz-account-id: _ACCOUNTID_

请求 Headers

有关常见请求标头的更多信息，请参阅附录 B 中的 S3 通用请求标头。

响应

响应是 HTTP 200 响应，以 XML 格式返回。

3.4.34. S3 PUT PublicAccessBlock

使用它来为 S3 存储桶创建或修改 PublicAccessBlock 配置。

要使用此操作，您必须有 s3:PutBucketPublicAccessBlock 权限。

重要

如果 PublicAccessBlock 配置在存储桶和帐户之间不同，Amazon S3 将使用存储桶级别和帐户级别设置的最严格的组合。

语法

PUT /?publicAccessBlock HTTP/1.1
Host: Bucket.s3.amazonaws.com
Content-MD5: ContentMD5
x-amz-sdk-checksum-algorithm: ChecksumAlgorithm
x-amz-expected-bucket-owner: ExpectedBucketOwner
<?xml version="1.0" encoding="UTF-8"?>
<PublicAccessBlockConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
   <BlockPublicAcls>boolean</BlockPublicAcls>
   <IgnorePublicAcls>boolean</IgnorePublicAcls>
   <BlockPublicPolicy>boolean</BlockPublicPolicy>
   <RestrictPublicBuckets>boolean</RestrictPublicBuckets>
</PublicAccessBlockConfiguration>

请求 Headers

有关常见请求标头的更多信息，请参阅附录 B 中的 S3 通用请求标头。

响应

响应是一个 HTTP 200 响应，它会返回一个空的 HTTP 正文。

3.4.35. S3 删除 PublicAccessBlock

使用它来删除 S3 存储桶的 PublicAccessBlock 配置。

语法

DELETE /v20180820/configuration/publicAccessBlock HTTP/1.1
Host: s3-control.amazonaws.com
x-amz-account-id: AccountId

请求 Headers

有关常见请求标头的更多信息，请参阅附录 B 中的 S3 通用请求标头。

响应

响应是一个 HTTP 200 响应，它会返回一个空的 HTTP 正文。

Red Hat logoGithubRedditYoutubeTwitter

学习

尝试、购买和销售

社区

关于红帽文档

通过我们的产品和服务，以及可以信赖的内容，帮助红帽用户创新并实现他们的目标。

让开源更具包容性

红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。欲了解更多详情，请参阅红帽博客.

關於紅帽

我们提供强化的解决方案，使企业能够更轻松地跨平台和环境（从核心数据中心到网络边缘）工作。

© 2024 Red Hat, Inc.