注意

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

报告文档错误

存储桶操作

PUT Bucket

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

约束条件

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

存储桶名称必须唯一。
存储桶名称不能格式化为 IP 地址。
存储桶名称长度为 3 到 63 个字符。
存储桶名称不能包含大写字符或下划线。
存储桶名称必须以小写字母或数字开头。
存储桶名称必须是一个或多个标签序列。相邻标签用一个句点（.）分隔。存储桶名称可以包含小写字母、数字和连字符。每个标签必须以小写字母或数字开头和结尾。

注意

如果选项“rgw_relaxed_s3_bucket_names”设置为 true，则上述约束会放宽，但存储桶名称仍必须唯一，不能格式化为 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。	`private`, `public-read`, `public-read-write`, `authenticated-read`	否
`x-amz-bucket-object-lock-enabled`	在存储桶上启用对象锁定。	`true`, `false`	否
`x-amz-object-ownership`	设置所有权控制。	`BucketOwnerEnforced`, `BucketOwnerPreferred`, `ObjectWriter`	否

请求实体

名称	类型	描述
`CreateBucketConfiguration`	Container	存储桶配置的容器。
`LocationConstraint`	String	一个zonegroup api名称，带有可选的S3存储桶放置。

HTTP响应

如果存储桶名称在约束范围内且未使用，则操作将成功。如果已存在同名存储桶且用户是存储桶所有者，则操作将成功，除非非默认选项rgw_bucket_eexist_override为true。如果存储桶名称已被使用，则操作将失败。

HTTP状态	状态码	描述
`409`	BucketAlreadyExists	存储桶已存在于不同用户的所有权下。

DELETE Bucket

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

Syntax

DELETE /{bucket} HTTP/1.1
Host: cname.domain.com

Authorization: AWS {access-key}:{hash-of-header-and-secret}

HTTP 响应

HTTP状态	状态码	描述
`204`	无内容	存储桶已移除。

GET Bucket

返回存储桶对象列表。

语法

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

参数

名称	类型	描述
`prefix`	String	仅返回包含指定前缀的对象。
`delimiter`	String	前缀和对象名称其余部分之间的分隔符。
`marker`	String	返回对象列表的起始索引。
`max-keys`	整数	要返回的最大键数。默认值为 1000。
`allow-unordered`	Boolean	非标准扩展。允许无序返回结果。不能与分隔符一起使用。

HTTP 响应

HTTP状态	状态码	描述
`200`	OK	存储桶已检索。

存储桶响应实体

GET /{bucket}返回一个存储桶容器，其中包含以下字段。

名称	类型	描述
`ListBucketResult`	实体	对象列表的容器。
`名称`	String	将返回其内容的存储桶名称。
`Prefix`	String	对象键的前缀。
`Marker`	String	返回对象列表的起始索引。
`MaxKeys`	整数	返回的最大键数。
`Delimiter`	String	如果设置，具有相同前缀的对象将出现在`CommonPrefixes`列表中。
`IsTruncated`	Boolean	如果`true`，则仅返回存储桶内容的一个子集。
`CommonPrefixes`	Container	如果多个对象包含相同的前缀，它们将出现在此列表中。

对象响应实体

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

名称	类型	描述
`目录`	对象	对象的容器。
`密钥`	String	对象的键。
`LastModified`	日期	对象的最后修改日期/时间。
`ETag`	String	对象的 MD-5 哈希值。（实体标签）
`大小`	整数	对象的大小。
`StorageClass`	String	应始终返回`STANDARD`。
`类型`	String	`Appendable` 或 `Normal`。

Get Bucket Location

检索存储桶的区域。用户需要是存储桶所有者才能调用此操作。通过在 PUT 请求期间提供LocationConstraint，可以将存储桶约束到某个区域。

语法

将location子资源添加到存储桶资源，如下所示

GET /{bucket}?location HTTP/1.1
Host: cname.domain.com

Authorization: AWS {access-key}:{hash-of-header-and-secret}

Response Entities

名称	类型	描述
`LocationConstraint`	String	存储桶所在的区域，默认区域为空字符串。

Get Bucket ACL

检索存储桶访问控制列表。用户需要是存储桶所有者或已获得存储桶上的READ_ACP权限。

语法

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

GET /{bucket}?acl HTTP/1.1
Host: cname.domain.com

Authorization: AWS {access-key}:{hash-of-header-and-secret}

响应实体

名称	类型	描述
`AccessControlPolicy`	Container	响应的容器。
`AccessControlList`	Container	ACL 信息的容器。
`Owner`	Container	存储桶所有者的`ID`和`DisplayName`的容器。
`ID`	String	存储桶所有者的 ID。
`DisplayName`	String	存储桶所有者的显示名称。
`Grant`	Container	`Grantee`和`Permission`的容器。
`Grantee`	Container	接收权限授予的用户的`DisplayName`和`ID`的容器。
`Permission`	String	授予`Grantee`存储桶的权限。

PUT Bucket ACL

设置现有存储桶的访问控制。用户需要是存储桶所有者或已获得存储桶上的WRITE_ACP权限。

语法

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

PUT /{bucket}?acl HTTP/1.1

请求实体

名称	类型	描述
`AccessControlPolicy`	Container	请求的容器。
`AccessControlList`	Container	ACL 信息的容器。
`Owner`	Container	存储桶所有者的`ID`和`DisplayName`的容器。
`ID`	String	存储桶所有者的 ID。
`DisplayName`	String	存储桶所有者的显示名称。
`Grant`	Container	`Grantee`和`Permission`的容器。
`Grantee`	Container	接收权限授予的用户的`DisplayName`和`ID`的容器。
`Permission`	String	授予`Grantee`存储桶的权限。

List Bucket Multipart Uploads

GET /?uploads返回当前进行中的分段上传列表——即应用程序启动了分段上传，但服务尚未完成所有上传。

语法

GET /{bucket}?uploads HTTP/1.1

参数

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

名称	类型	描述
`prefix`	String	返回键包含指定前缀的进行中的上传。
`delimiter`	String	前缀和对象名称其余部分之间的分隔符。
`key-marker`	String	上传列表的起始标记。
`max-keys`	整数	进行中的上传最大数量。默认值为 1000。
`max-uploads`	整数	分段上传的最大数量。范围从 1 到 1000。默认值为 1000。
`upload-id-marker`	String	如果未指定`key-marker`，则忽略。指定在`ID`处或之后按字典顺序排列的要列出的第一个上传的`ID`。

响应实体

名称	类型	描述
`ListMultipartUploadsResult`	Container	结果的容器。
`ListMultipartUploadsResult.Prefix`	String	由`prefix`请求参数指定的（如果存在）前缀。
`Bucket`	String	将接收存储桶内容的存储桶。
`KeyMarker`	String	由`key-marker`请求参数指定的（如果存在）键标记。
`UploadIdMarker`	String	由`upload-id-marker`请求参数指定的（如果存在）上传 ID 标记。
`NextKeyMarker`	String	如果`IsTruncated`为`true`，则在后续请求中使用的键标记。
`NextUploadIdMarker`	String	如果`IsTruncated`为`true`，则在后续请求中使用的上传 ID 标记。
`MaxUploads`	整数	由`max-uploads`请求参数指定的最大上传数。
`Delimiter`	String	如果设置，具有相同前缀的对象将出现在`CommonPrefixes`列表中。
`IsTruncated`	Boolean	如果`true`，则仅返回存储桶上传内容的一个子集。
`Upload`	Container	`Key`、`UploadId`、`InitiatorOwner`、`StorageClass`和`Initiated`元素的容器。
`密钥`	String	分段上传完成后对象的键。
`UploadId`	String	标识分段上传的`ID`。
`Initiator`	Container	包含发起上传的用户的`ID`和`DisplayName`。
`DisplayName`	String	发起者的显示名称。
`ID`	String	发起者的 ID。
`Owner`	Container	拥有上传对象的用户的`ID`和`DisplayName`的容器。
`StorageClass`	String	用于存储结果对象的方法。`STANDARD`或`REDUCED_REDUNDANCY`
`Initiated`	日期	用户发起上传的日期和时间。
`CommonPrefixes`	Container	如果多个对象包含相同的前缀，它们将出现在此列表中。
`CommonPrefixes.Prefix`	String	前缀后面的键的子字符串，由`prefix`请求参数定义。

ENABLE/SUSPEND BUCKET VERSIONING

PUT /?versioning此子资源设置现有存储桶的版本控制状态。要设置版本控制状态，您必须是存储桶所有者。

您可以使用以下值之一设置版本控制状态

Enabled：启用存储桶中对象的版本控制，添加到存储桶的所有对象都会收到一个唯一的版本 ID。
Suspended：禁用存储桶中对象的版本控制，添加到存储桶的所有对象都会收到版本 ID null。

如果从未在存储桶上设置版本控制状态，则它没有版本控制状态；GET versioning请求不返回版本控制状态值。

语法

PUT  /{bucket}?versioning  HTTP/1.1

请求实体

名称	类型	描述
`VersioningConfiguration`	Container	请求的容器。
`Status`	String	设置存储桶的版本控制状态。有效值：Suspended/Enabled

PUT BUCKET OBJECT LOCK

将对象锁定配置应用于指定的存储桶。对象锁定配置中指定的规则将默认应用于放置在指定存储桶中的每个新对象。

Syntax

PUT /{bucket}?object-lock HTTP/1.1

请求实体

名称	类型	描述	必需
`ObjectLockConfiguration`	Container	请求的容器。	是
`ObjectLockEnabled`	String	指示此存储桶是否启用了对象锁定配置。	是
`Rule`	Container	为指定存储桶设置的对象锁定规则。	否
`DefaultRetention`	Container	应用于放置在指定存储桶中的新对象的默认保留期。	否
`Mode`	String	默认对象锁定保留模式。有效值：GOVERNANCE/COMPLIANCE	是
`Days`	整数	为默认保留期指定的天数。	否
`Years`	整数	为默认保留期指定的年数。	否

HTTP 响应

如果在创建存储桶时未启用存储桶对象锁定，则操作将失败。

HTTP状态	状态码	描述
`400`	MalformedXML	XML 格式不正确。
`409`	InvalidBucketState	未启用存储桶对象锁定。

GET BUCKET OBJECT LOCK

获取存储桶的对象锁定配置。对象锁定配置中指定的规则将默认应用于放置在指定存储桶中的每个新对象。

语法

GET /{bucket}?object-lock HTTP/1.1

响应实体

名称	类型	描述	必需
`ObjectLockConfiguration`	Container	请求的容器。	是
`ObjectLockEnabled`	String	指示此存储桶是否启用了对象锁定配置。	是
`Rule`	Container	为指定存储桶设置的对象锁定规则。	否
`DefaultRetention`	Container	应用于放置在指定存储桶中的新对象的默认保留期。	否
`Mode`	String	默认对象锁定保留模式。有效值：GOVERNANCE/COMPLIANCE	是
`Days`	整数	为默认保留期指定的天数。	否
`Years`	整数	为默认保留期指定的年数。	否

Create Notification

为特定存储桶创建一个发布者到主题。

语法

PUT /{bucket}?notification HTTP/1.1

请求实体

参数以 XML 编码在请求正文中，格式如下

<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>

名称	类型	描述	必需
`NotificationConfiguration`	Container	包含`TopicConfiguration`实体的列表。	是
`TopicConfiguration`	Container	包含`Id`、`Topic`和`Event`实体的列表。	是
`Id`	String	通知名称。	是
`Topic`	String	主题 ARN。必须事先创建主题。	是
`Event`	String	支持的事件列表，请参阅：S3 存储桶通知兼容性。可以使用多个`Event`实体。如果省略，则处理所有“Created”和“Removed”事件。“Lifecycle”和“Synced”事件类型必须显式指定。	否
`Filter`	Container	包含`S3Key`、`S3Metadata`和`S3Tags`实体。	否
`S3Key`	Container	包含`FilterRule`实体的列表，用于基于对象键进行过滤。列表中最多可以有 3 个实体，其中`Name`为`prefix`、`suffix`或`regex`。列表中所有过滤规则都必须匹配，过滤器才能匹配。	否
`S3Metadata`	Container	包含`FilterRule`实体的列表，用于基于对象元数据进行过滤。列表中所有过滤规则必须匹配对象上定义的元数据。但是，即使对象具有过滤器中未列出的其他元数据条目，它仍然匹配。	否
`S3Tags`	Container	包含`FilterRule`实体的列表，用于基于对象标签进行过滤。列表中所有过滤规则必须匹配对象上定义的标签。但是，即使对象具有过滤器中未列出的其他标签，它仍然匹配。	否
`S3Key.FilterRule`	Container	包含`Name`和`Value`实体。`Name`将是：`prefix`、`suffix`或`regex`。`Value`将相应地保存键前缀、键后缀或用于匹配键的正则表达式。	是
`S3Metadata.FilterRule`	Container	包含`Name`和`Value`实体。`Name`将是元数据属性的名称（例如`x-amz-meta-xxx`）。`Value`将是此属性的期望值。	是
`S3Tags.FilterRule`	Container	包含`Name`和`Value`实体。`Name`将是标签键，`Value`将是标签值。	是

HTTP 响应

HTTP状态	状态码	描述
`400`	MalformedXML	XML 格式不正确。
`400`	InvalidArgument	缺少 ID；缺少/无效的主题 ARN；无效的事件。
`404`	NoSuchBucket	存储桶不存在。
`404`	NoSuchKey	主题不存在。

Delete Notification

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

注意

通知删除是 S3 通知 API 的扩展
当存储桶被删除时，其上定义的任何通知也会被删除
删除未知通知（例如重复删除）不被视为错误

语法

DELETE /{bucket}?notification[=<notification-id>] HTTP/1.1

参数

名称	类型	描述
`notification-id`	String	通知名称。如果未提供，则删除存储桶上的所有通知。

HTTP 响应

HTTP状态	状态码	描述
`404`	NoSuchBucket	存储桶不存在。

Get/List Notification

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

语法

GET /{bucket}?notification[=<notification-id>] HTTP/1.1

参数

名称	类型	描述
`notification-id`	String	通知名称。如果未提供，则列出存储桶上的所有通知。

响应实体

响应以 XML 编码在请求正文中，格式如下

<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>

名称	类型	描述	必需
`NotificationConfiguration`	Container	包含`TopicConfiguration`实体的列表。	是
`TopicConfiguration`	Container	包含`Id`、`Topic`和`Event`实体的列表。	是
`Id`	String	通知名称。	是
`Topic`	String	主题 ARN。	是
`Event`	String	处理的事件。可能存在多个`Event`实体。	是
`Filter`	Container	包含为此通知配置的过滤器。	否

HTTP 响应

HTTP状态	状态码	描述
`404`	NoSuchBucket	存储桶不存在。
`404`	NoSuchKey	通知不存在（如果提供）。

Enable Bucket Logging

启用存储桶的日志记录。

语法

PUT /{bucket}?logging HTTP/1.1

请求实体

参数以 XML 编码在请求正文中，格式如下

<BucketLoggingStatus xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <LoggingEnabled>
    <TargetBucket>string</TargetBucket>
    <TargetGrants>
      <Grant>
        <Grantee>
          <DisplayName>string</DisplayName>
          <EmailAddress>string</EmailAddress>
          <ID>string</ID>
          <xsi:type>string</xsi:type>
          <URI>string</URI>
        </Grantee>
        <Permission>string</Permission>
      </Grant>
    </TargetGrants>
    <TargetObjectKeyFormat>
      <PartitionedPrefix>
        <PartitionDateSource>DeliveryTime|EventTime</PartitionDateSource>
      </PartitionedPrefix>
      <SimplePrefix>
      </SimplePrefix>
    </TargetObjectKeyFormat>
    <TargetPrefix>string</TargetPrefix>
    <LoggingType>Standard|Journal</LoggingType>
    <ObjectRollTime>integer</ObjectRollTime>
    <Filter>
      <S3Key>
        <FilterRule>
          <Name>suffix/prefix/regex</Name>
          <Value></Value>
        </FilterRule>
      </S3Key>
    </Filter>
  </LoggingEnabled>
</BucketLoggingStatus>

名称	类型	描述	必需
`BucketLoggingStatus`	Container	启用/禁用存储桶的日志记录配置。	是
`LoggingEnabled`	Container	包含存储桶的日志记录配置。	是
`TargetBucket`	String	存储日志的存储桶。日志存储桶不能启用存储桶日志记录。	是
`TargetGrants`	Container	不支持。日志存储桶的所有者是日志对象的所有者。	否
`TargetObjectKeyFormat`	Container	日志对象键的格式。包含`PartitionedPrefix`或`SimplePrefix`实体。	否
`PartitionedPrefix`	Container	指示分区日志对象键格式。请注意，`PartitionDateSource`被忽略并硬编码为`DeliveryTime`。	否
`SimplePrefix`	Container	指示简单日志对象键格式（默认格式）。	否
`TargetPrefix`	String	日志对象的前缀。两种格式都使用。可用于区分写入同一日志存储桶的不同源存储桶的日志记录。	否
`LoggingType`	String	日志记录类型。有效值：`Standard`（默认）所有存储桶操作在执行后都会记录。日志记录将包含所有字段。`Journal`仅记录修改对象的操作。将记录日志记录中所需的最小字段子集，以用于日志记录。	否
`ObjectRollTime`	整数	创建新日志对象并将前一个日志对象添加到日志存储桶所需的时间（以秒为单位）。默认值为 3600 秒（1 小时）。	否

响应实体

响应以 XML 编码在请求正文中，仅当配置更改触发当前日志记录对象的刷新时。在这种情况下，它将返回刷新的日志记录对象的名称，格式如下

<PostBucketLoggingOutput xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <FlushedLoggingObject>string</FlushedLoggingObject>
</PostBucketLoggingOutput>

HTTP 响应

HTTP状态	状态码	描述
`400`	MalformedXML	XML 格式不正确。
`400`	InvalidArgument	缺少必需值或无效值。
`404`	NoSuchBucket	存储桶不存在。

Disable Bucket Logging

禁用存储桶的日志记录。

语法

PUT /{bucket}?logging HTTP/1.1

请求实体

参数以 XML 编码在请求正文中，格式如下

<BucketLoggingStatus xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
</BucketLoggingStatus>

HTTP 响应

HTTP状态	状态码	描述
`404`	NoSuchBucket	存储桶不存在。

Get Bucket Logging

获取存储桶上配置的日志记录。

语法

GET /{bucket}?logging HTTP/1.1

响应实体

响应标头包含日志记录配置的Last-Modified日期/时间。日志记录配置以 XML 编码在响应正文中，格式如下

<BucketLoggingStatus xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <LoggingEnabled>
    <TargetBucket>string</TargetBucket>
    <TargetGrants>
      <Grant>
        <Grantee>
          <DisplayName>string</DisplayName>
          <EmailAddress>string</EmailAddress>
          <ID>string</ID>
          <xsi:type>string</xsi:type>
          <URI>string</URI>
        </Grantee>
        <Permission>string</Permission>
      </Grant>
    </TargetGrants>
    <TargetObjectKeyFormat>
      <PartitionedPrefix>
        <PartitionDateSource>DeliveryTime|EventTime</PartitionDateSource>
      </PartitionedPrefix>
      <SimplePrefix>
      </SimplePrefix>
    </TargetObjectKeyFormat>
    <TargetPrefix>string</TargetPrefix>
    <LoggingType>Standard|Journal</LoggingType>
    <ObjectRollTime>integer</ObjectRollTime>
    <Filter>
      <S3Key>
        <FilterRule>
          <Name>suffix/prefix/regex</Name>
          <Value></Value>
        </FilterRule>
      </S3Key>
    </Filter>
  </LoggingEnabled>
</BucketLoggingStatus>

HTTP 响应

HTTP状态	状态码	描述
`404`	NoSuchBucket	存储桶不存在。

Flush Bucket Logging

刷新给定源存储桶的日志记录对象（如果未刷新，日志记录对象将延迟写入日志存储桶）。返回已刷新的对象的名称。即使日志记录对象为空，也会发生刷新。

语法

POST /{bucket}?logging HTTP/1.1

响应实体

响应以 XML 编码在请求正文中，格式如下

<PostBucketLoggingOutput xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <FlushedLoggingObject>string</FlushedLoggingObject>
</PostBucketLoggingOutput>

HTTP 响应

HTTP状态	状态码	描述
`201`	Created	成功刷新待处理的日志记录对象。
`404`	NoSuchBucket	存储桶不存在。

由 Ceph 基金会为您呈现

Ceph 文档是由非营利性 Ceph 基金会资助和托管的社区资源。如果您希望支持这项工作和我们的其他努力，请考虑立即加入。