注意

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

Bucket Operations

PUT 桶

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

限制

通常，桶名应遵循域名限制。

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

Note

如果选项“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`		否

请求实体

名称	类型	描述
`CreateBucketConfiguration`	容器	桶配置的容器。
`LocationConstraint`	字符串	一个zonegroup api名称，可选S3桶放置

HTTP响应

如果桶名是唯一的、在限制内且未被使用，则操作将成功。如果已存在同名桶且用户是桶的所有者，则操作将成功，除非非默认选项aaf820: 。如果桶名已被使用，则操作将失败。rgw_bucket_eexist_override是true. If the bucket name is already in use, the operation will fail.

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

删除桶

删除桶。在成功删除桶后，您可以重用桶名。

语法

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

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

HTTP响应

HTTP状态	状态代码	描述
`204`	无内容	桶已删除。

获取桶

返回桶对象列表。

语法

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

参数

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

HTTP响应

HTTP状态	状态代码	描述
`200`	确定	桶检索

桶响应实体

GET /{bucket}返回包含以下字段的桶容器。

名称	类型	描述
`ListBucketResult`	实体	对象列表的容器。
`Name`	字符串	将返回其内容的桶名称。
`Prefix`	字符串	对象键的前缀。
`Marker`	字符串	返回对象列表的起始索引。
`MaxKeys`	整数	返回的键数。
`Delimiter`	字符串	如果设置，具有相同前缀的对象将出现在`CommonPrefixes`列表中。
`IsTruncated`	布尔值	如果`true`，仅返回了桶的部分内容。
`CommonPrefixes`	容器	如果多个对象包含相同的前缀，它们将出现在此列表中。

对象响应实体

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

名称	类型	描述
`Contents`	对象	对象的容器。
`Key`	字符串	对象的键。
`LastModified`	日期	对象的最后修改日期/时间。
`ETag`	字符串	对象的MD-5哈希值。（实体标签）
`Size`	整数	对象的大小。
`StorageClass`	字符串	应始终返回`STANDARD`.
`Type`	字符串	`Appendable`或`Normal`.

获取桶位置

检索桶的区域。调用此方法时，用户必须是桶的所有者。通过在PUT请求中提供LocationConstraint，可以将桶约束到某个区域。

语法

添加location作为桶资源的子资源显示如下

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

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

响应实体

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

获取桶ACL

检索桶访问控制列表。用户必须是桶的所有者或被授予READ_ACP对桶的权限。

语法

添加acl作为桶请求的子资源显示如下。

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

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

响应实体

名称	类型	描述
`AccessControlPolicy`	容器	响应的容器。
`AccessControlList`	容器	ACL信息的容器。
`Owner`	容器	桶所有者信息的容器。`ID`和`DisplayName`.
`ID`	字符串	桶所有者的ID。
`DisplayName`	字符串	桶所有者的显示名称。
`Grant`	容器	接收权限的用户信息的容器。`Grantee`和`Permission`.
`Grantee`	容器	接收权限的用户信息的容器。`DisplayName`和`ID`用户ID。
`Permission`	字符串	给予的权限。`Grantee`桶。

PUT 桶ACL

为现有桶设置访问控制。用户必须是桶的所有者或被授予WRITE_ACP对桶的权限。

语法

添加acl作为桶请求的子资源显示如下。

PUT /{bucket}?acl HTTP/1.1

请求实体

名称	类型	描述
`AccessControlPolicy`	容器	请求的容器。
`AccessControlList`	容器	ACL信息的容器。
`Owner`	容器	桶所有者信息的容器。`ID`和`DisplayName`.
`ID`	字符串	桶所有者的ID。
`DisplayName`	字符串	桶所有者的显示名称。
`Grant`	容器	接收权限的用户信息的容器。`Grantee`和`Permission`.
`Grantee`	容器	接收权限的用户信息的容器。`DisplayName`和`ID`用户ID。
`Permission`	字符串	给予的权限。`Grantee`桶。

列出桶多部分上传

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

语法

GET /{bucket}?uploads HTTP/1.1

参数

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

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

响应实体

名称	类型	描述
`ListMultipartUploadsResult`	容器	A container for the results.
`ListMultipartUploadsResult.Prefix`	字符串	由`prefix`请求参数指定的标记。
`Bucket`	字符串	将接收桶内容的桶。
`KeyMarker`	字符串	由`key-marker`请求参数指定的标记。
`UploadIdMarker`	字符串	由`upload-id-marker`请求参数指定的标记。
`NextKeyMarker`	字符串	如果在后续请求中使用键标记，则使用此标记。`IsTruncated`是`true`.
`NextUploadIdMarker`	字符串	如果在后续请求中使用上传ID标记，则使用此标记。`IsTruncated`是`true`.
`MaxUploads`	整数	由`max-uploads`请求参数定义的前缀之后键的子字符串。
`Delimiter`	字符串	如果设置，具有相同前缀的对象将出现在`CommonPrefixes`列表中。
`IsTruncated`	布尔值	如果`true`，仅返回了桶的部分上传内容。
`Upload`	容器	接收权限的用户信息的容器。`Key`, `UploadId`, `InitiatorOwner`, `StorageClass`, and `Initiated` elements.
`Key`	字符串	完成多部分上传后对象的键。
`UploadId`	字符串	The `ID`标识多部分上传的字符串。
`Initiator`	容器	包含`ID`和`DisplayName`启动上传的用户。
`DisplayName`	字符串	启发者的显示名称。
`ID`	字符串	启发者的ID。
`Owner`	容器	接收权限的用户信息的容器。`ID`和`DisplayName`拥有上传对象的用户的容器。
`StorageClass`	字符串	存储结果对象的方法。`STANDARD`或`REDUCED_REDUNDANCY`
`Initiated`	日期	用户启动上传的日期和时间。
`CommonPrefixes`	容器	如果多个对象包含相同的前缀，它们将出现在此列表中。
`CommonPrefixes.Prefix`	字符串	由`prefix`请求参数定义的前缀之后键的子字符串。

启用/暂停桶版本控制

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

您可以使用以下值之一来设置版本状态：

启用：为桶中的对象启用版本控制，添加到桶中的所有对象都将获得一个唯一的版本ID。
暂停：为桶中的对象禁用版本控制，添加到桶中的所有对象都将获得null版本ID。

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

语法

PUT  /{bucket}?versioning  HTTP/1.1

请求实体

名称	类型	描述
`VersioningConfiguration`	容器	请求的容器。
`Status`	字符串	设置桶的版本状态。有效值：暂停/启用

PUT BUCKET OBJECT LOCK

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

语法

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

请求实体

名称	类型	描述	必需
`ObjectLockConfiguration`	容器	请求的容器。	是
`ObjectLockEnabled`	字符串	指示此桶是否启用了对象锁定配置。	是
`Rule`	容器	指定桶中正在应用的对象锁定规则。	否
`DefaultRetention`	容器	放入指定桶中的新对象应用的默认保留期。	否
`Mode`	字符串	默认对象锁定保留模式。有效值：治理/合规	是
`Days`	整数	默认保留期指定的天数。	否
`Years`	整数	默认保留期指定的年数。	否

HTTP响应

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

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

GET BUCKET OBJECT LOCK

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

语法

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

响应实体

名称	类型	描述	必需
`ObjectLockConfiguration`	容器	请求的容器。	是
`ObjectLockEnabled`	字符串	指示此桶是否启用了对象锁定配置。	是
`Rule`	容器	指定桶中正在应用的对象锁定规则。	否
`DefaultRetention`	容器	放入指定桶中的新对象应用的默认保留期。	否
`Mode`	字符串	默认对象锁定保留模式。有效值：治理/合规	是
`Days`	整数	默认保留期指定的天数。	否
`Years`	整数	默认保留期指定的年数。	否

创建通知

为特定桶到主题创建发布者。

语法

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`	容器	包含`TopicConfiguration`实体的列表	是
`TopicConfiguration`	容器	包含`Id`, `Topic`和`Event`实体的列表	是
`Id`	字符串	通知的名称	是
`Topic`	字符串	主题ARN。主题必须事先创建	是
`Event`	字符串	支持的事件列表，见：S3 通知兼容性。可以使用多个`Event`实体。如果省略，则处理所有“创建”和“删除”事件。	否
`Filter`	容器	包含`S3Key`, `S3Metadata`和`S3Tags`实体的列表	否
`S3Key`	容器	包含`FilterRule`实体的列表，用于根据对象键进行过滤。`Name` be `prefix`, `suffix`或`regex`。列表中的所有过滤规则必须匹配，才能匹配。	否
`S3Metadata`	容器	包含`FilterRule`实体的列表，用于根据对象元数据进行过滤。	否
`S3Tags`	容器	包含`FilterRule`实体的列表，用于根据对象标签进行过滤。	否
`S3Key.FilterRule`	容器	包含`Name`和`Value`实体。`Name`将是：`prefix`, `suffix`或`regex`一起使用。该`Value`将包含键前缀、键后缀或用于匹配键的正则表达式，相应地。	是
`S3Metadata.FilterRule`	容器	包含`Name`和`Value`实体。`Name`将是元数据`x-amz-meta-xxx`应该是 ASCII 字符串（如 Python 的`Value`将是此属性的预期值。	是
`S3Tags.FilterRule`	容器	包含`Name`和`Value`实体。`Name`将是标签键，`Value`将是标签值。	是

HTTP响应

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

删除通知

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

Note

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

语法

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

参数

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

HTTP响应

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

获取/列出通知

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

语法

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

参数

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

响应实体

响应以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`	容器	包含`TopicConfiguration`实体的列表	是
`TopicConfiguration`	容器	包含`Id`, `Topic`和`Event`实体的列表	是
`Id`	字符串	通知的名称	是
`Topic`	字符串	主题ARN	是
`Event`	字符串	处理的事件。可以存在多个`Event`实体	是
`Filter`	容器	包含为此通知配置的过滤器	否

HTTP响应

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

启用桶日志记录

为桶启用日志记录。

语法

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`	容器	为桶启用/禁用日志记录配置。	是
`LoggingEnabled`	容器	包含桶的日志记录配置。	是
`TargetBucket`	字符串	存储日志的桶。日志桶不能启用桶日志记录。	是
`TargetGrants`	容器	不支持。日志桶的所有者是日志对象的所有者。	否
`TargetObjectKeyFormat`	容器	日志对象键的格式。包含`PartitionedPrefix`或`SimplePrefix`实体。	否
`PartitionedPrefix`	容器	指示分区日志对象键格式。请注意，`PartitionDateSource`被忽略并硬编码为`DeliveryTime`	否
`SimplePrefix`	容器	指示简单日志对象键格式（默认格式）	否
`TargetPrefix`	字符串	日志对象的前缀。在两种格式中都使用。可用于区分将日志记录写入同一日志桶的不同源桶。	否
`LoggingType`	字符串	日志记录的类型。有效值是：`Standard`（默认）所有桶操作在执行后都会被记录。日志记录将包含所有字段。`Journal`仅记录PUT、COPY、MULTI/DELETE和MPU操作。将记录日志记录中所需的字段的最小子集，用于记录。	否
`ObjectRollTime`	整数	新日志对象创建和先前日志对象添加到日志桶的秒数。默认为3600秒（1小时）。	否

HTTP响应

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

禁用桶日志记录

从桶中禁用日志记录。

语法

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

HTTP响应

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

冲洗桶日志记录

刷新给定源桶的所有日志对象（日志桶被懒惰地写入）。

语法

POST /{bucket}?logging HTTP/1.1

HTTP响应

HTTP状态	状态代码	描述
`201`	创建	成功刷新所有日志对象
`404`	NoSuchBucket	桶不存在

由 Ceph 基金会带给您

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