土星云-分布式存储系统

Delete Bucket

描述

该操作可删除指定 Bucket。删除 Bucket 前需将其中的所有 Object 删除。

请求

语法

DELETE / HTTP/1.1
Host: <BUCKET_NAME>.s3.<REGION>.saturncloud.com.cn
Date: <date>
Authorization: <authorization string> (see Authenticating Requests (AWS Signature Version4))
Signature Version4))

请求参数

无请求参数

请求 Header

该操作仅使用通用的请求 Header，请参阅常见请求 Header。

请求元素

无请求元素

响应

响应 Header

该操作仅使用通用的请求 Header，请参阅常见响应 Header。

示例

请求示例

该请求删除名为"oss-example"的 bucket。

DELETE / HTTP/1.1
Host: oss-example.s3.<REGION>.saturncloud.com.cn
Date: Wed, 01 Mar 2006 12:00:00 GMT
Authorization: <authorization string>

响应示例

HTTP/1.1 204 No Content
x-amz-request-id:32FE2CEB32F5EE25
Date:Wed,01 Mar 2006 12:00:00 GMT
Connection:close
Server:SCSOSS

GET Bucket acl

描述

该操作可列出指定 Bucket，仅 Bukcet 的 Owner 可操作。

请求

语法

GET /?acl / HTTP/1.1 Host: <BUCKET_NAME>.s3.<REGION>.saturncloud.com.cn Date: <date> Authorization: <authorization string> (see Authenticating Requests (AWS Signature Version4)) Signature Version4))

请求参数

无请求参数

请求 Header

无特殊请求 Header

请求元素

无请求元素

响应

响应 Header

无特殊响应 Header

响应元素

名称	描述	Type	Ancestors
AccessControlList	acl 信息集合	Container	AccessControlPolicy
AccessControlPolicy	每个被授予人的 ACL 元素集合。	String	None
DisplayName	Bucket 拥有者名称。	String	AccessControlPolicy.Owner
Grant	被授权者及权限信息集合	Container	AccessControlPolicy.AccessControlList
Grantee	被授权者	String	AccessControlPolicy.AccessControlList.Grant
ID	bucket 拥有者或者被授权者的 ID	String	AccessControlPolicy.OwnerAccessControlPolicy.AccessControlList.Grant
Owner	bucket 拥有者的信息集合	Container	AccessControlPolicy
Permission	指定的权限	String	Valid Values: FULL_CONTROL、WRITE、READAncestors: AccessControlPolicy.AccessControlList.Grant

示例

请求示例

GET ?acl / HTTP/1.1 Host: <BUCKET_NAME>.s3..saturncloud.com.cn Date: Wed, 28 Oct 2009 22:32:00 GMT Authorization:

响应示例

HTTP/1.12000K x-amz-request-id:318BC8BC148832E5 Date:Wed,28 Oct 2009 22:32:00
GMT Last-Modified:Sun,1 Jan 2006 12:00:00 GMT Content-Length:124
Content-Type:text/plain Connection:close Server:SCSOSS
<AccessControlPolicy>
  <Owner>
    <ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea5 4ba06a</ID>
    <DisplayName>CustomersName@amazon.com</DisplayName>
  </Owner>
  <AccessControlList>
    <Grant>
      <Grantee
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:type="CanonicalUser"
      >
        <ID>
          75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a
          </ID>
        <DisplayName>CustomersName@amazon.com</DisplayName>
      </Grantee>
      <Permission>FULL CONTROL</Permission>
    </Grant>
  </AccessControlList>
</AccessControlPolicy>

Get Bucket(List Objects)Version 2

描述

此操作可列举出 Bukcet 中的部分或全部（最多 1000 个）Object。您可以使请求参数作为选择过滤条件来列举部分对象。注意：即使 Bucket 的访问权限为 public，也不允许匿名使用此操作，需要指定 Authorization。

请求

语法

GET /?list-type=2 HTTP/1.1
Host:<BUCKET NAME>.s3.<REGION>.saturncloud.com.cn
Date:<date>
Authorization:<authorization string>(see Authenticating
Requests (AWS Signature Version4))

请求参数

参数	描述	必须
delimiter	是一个用于对 Object 名字进行分组的字符。所有名字包含指定的前缀且第一次出现 delimiter 字符之间的 object 作为一组元素——CommonPrefixes。如果未指定 prefix，则从名字开头算起。Type: StringDefault: None	否
encoding-type	对响应进行编码并指定编码类型。Objcet Key 可以包含任何 Unicode 字符。但是，XML1.0 无法解析某些字符，例如 ASCII 值为 0 到 10 的字符。对于 XML 1.0 中不支持的字符，您可以添加此参数以请求 OSS 对响应中的键进行编码。Type: StringDefault: NoneValid value: url	否
max-keys	限定此次返回 object 的最大数。如果要检索少于默认的 1,000 个 object，可以将其添加到您的请求中。响应中 object 数量如果大于设定的最大数量，则超出的 object 不会返回，且响应中将包含 true。如果要返回额外超出的 object，请参阅 NextContinuationToken。Type: StringDefault: 1000	否
prefix	限定返回的 object 必须以 prefix 作为前缀。您可以使用 prefix 将 object 分成不同的组。Type: StringDefault: None	否
list-type	API Version 2 需要此参数，且该参数值必须设置为 2。Type: StringDefault:2	是
continuation-token	当响应元素 IsTruncated 为 true 时，则响应中会包含 NextContinuationToken 元素，您可以使用 NextContinuationToken 作为下一个请求中的 continuation-token 返回下一批 object。Type: StringDefault: None	否
fetch-owner	默认情况下不会返回 Bucket 所有者信息，如果需要返回所有者信息，需指定 fetch-owner 值为 tureType: StringDefault: false	否
start-after	如果您需要返回某个特定的 object 后的相关 object，你可以将该特定 object 名称设为参数值。Type: StringDefault: None	否

请求 Header

该操作仅使用通用的请求 Header，请参阅常见请求 Header。

请求元素

无请求元素

响应

响应 Header

该操作仅使用通用的响应 Header，请参阅常见响应 Header。

响应元素

名称	描述	Type	Ancestor
Contents	每个 object 返回的元数据	XML metadata	ListBucketResult
CommonPrefixes	在返回时，将所有包含指定 prefix 且第一次出现 delimiter 的 object 作为单个 CommonPrefixes 返回。只有在指定 delimiter 时返回 CommonPrefixes。	String	ListBucketResult
Delimiter	是一个用于对 Object 名字进行分组的字符。	String	ListBucketResult
DisplayName	object 拥有者的名称	String	ListBucketResult.Contents.Owner
Encoding-Type	对响应进行编码并指定编码类型。	String	ListBucketResult
ETag	ETag 是土星云存储中 Object 的 Hash 值，其仅反映 Object 的数据内容，而不包括元数据(Metadata)。	String	ListBucketResult.Contents
ID	object 拥有者的 ID。	String	ListBucketResult.Contents.Owner
IsTruncated	如果 object 数量超过 MaxKeys 值，则更多的 object 可能返回，为 ture；如果所有结果都返回，则为 false。
Key	object key	String	ListBucketResult.Contents
LastModified	object 最后修改时间。	Date	ListBucketResult.Contents
MaxKeys	限定此次返回 object 的最大数。	Date	ListBucketResult.Contents
Name	bucket 的名称。	String	ListBucketResult
Owner	bucket 拥有者。	StringChildren: DisplayName, ID	ListBucketResult.Contents
Prefix	限定返回的 object key 必须以 prefix 作为前缀。	String	ListBucketResult
Size	object 大小。	String	ListBucketResult.Contents
StorageClass	存储类型：STANDARD、REDUCED_REDUNDANCY	String	ListBucketResult.Contents
ContinuationToken	请求中包含此元素，则响应中也包含此元素。	String	ListBucketResult
KeyCount	响应中返回的 object 数量。	String	ListBucketResult
NextContinuationToken	如果响应被截断，OSS 将会返回延续 Token。你可以使用该 Token 作为下一条请求中的 continuation-token 来取回剩余的 object。	String	ListBucketResult
StartAfter	请求中包含此元素，则响应中也包含此元素。	String	ListBucketResult

示例

示例 1：Listing Keys

该请求可返回某 bucket 中的 object。该请求指定 list-type 元素为 2。

请求示例

GET /?list-type=2 HTTP/1.1
Host:<BUCKET NAME>.s3.<REGION>.saturncloud com.cn
×-amz-date:20160430T233541Z
Authorization:<authorization string>
Content-Type:text/plain

响应示例

HTTP/1.12000K x-amz-request-id: 3B3C7C725673C630 Date:Sat,30 Apr 2016 23:29:37
GMT Content-Type:application/xml Content-Length:length Connection:close
Server:SCSOSS
<?xml version="1.0"encoding="UTF-8"?>
<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Name>oss-example</Name>
  <Prefix />
  <KeyCount>205</KeyCount>
  <MaxKeys>1000</MaxKeys>
  <IsTruncated>false</IsTruncated>
  <Contents>
    <Key>my-image.jpg</Key>
    <LastModified>2009-10-12T17:50:30.000Z</LastModified>
    <Etag>"fba9dede5f27731c9771645a39863328"</Etag>
    <Size>434234</Size>
    <Storageclass>STANDARD</Storageclass>
  </Contents>
  <Contents> </Contents>
</ListBucketResult>

示例 2：Listing Keys（使用 max-keys,prefix,start-after 元素）

请求示例

GET
/?list-type=2&max-keys=3&prefix=E&start-after=ExampleGuide.pdf
HTTP/1.1
Host:<BUCKET NAME>.s3.<REGION>.saturncloud.com.cn
×-amz-date:20160430T232933Z
Authorization:<authorization string>

响应示例

HTTP/1.12000K X-amz-request-id:3B3C7C725673C630 Date:Sat,30 Apr 2016 23:29:37
GMT Content-Type:application/xml Content-Length:length Connection:close
Server:SCSOSS
<?xml version="1.0"encoding="UTF-8"?>
<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Name>oss-example</Name>
  <Prefix>E</Prefix>
  <StartAfter>ExampleGuide.pdf</StartAfter>
  <KeyCount>1</KeyCount>
  <MaxKeys>3</MaxKeys>
  <IsTruncated>false</IsTruncated>
  <Contents>
    <Key>Exampleobject.txt</Key>
    <LastModified>2013-09-17T18:07:53.000Z</LastModified>
    <Etag>"599bab3ed2c697f1d26842727561fd94"</Etag>
    <Size>857</Size>
    <Storageclass>REDUCED REDUNDANCY</Storageclass>
  </Contents>
</ListBucketResult>

示例 3：Listing Keys（使用 prefix 和 delimiter 元素）

该示例请求中使用 prefix 和 delimiter 元素，假如 bucket 中有以下 object： sample.jpg photos/2006/January/sample.jpg photos/2006/February/sample2.jpg photos/2006/February/sample3.jpg photos/2006/February/sample4.jpg

以下示例指定 delimiter 值为"/"：

GET /?list-type=2&delimiter=/HTTP/1.1
Host:<BUCKET NAME>.s3.<REGION>.saturncloud.com.cn
x-amz-date:20160430T235931Z
Authorization:<authorization string>

sample.jpg 不包含 delimiter 字符，所以 OSS 将它返回到 Contents 元素中。其他 object 包含 delimiter 字符，且包含共同的 prefix:photos/，所以 OSS 将其作为单个 CommonPrefixes 元素返回。
以下示例指定 delimiter 值为"/"，prefix 值为"photos/2006/"

以下示例指定 delimiter 值为"/"，prefix 值为"photos/2006/"

GET /?1ist-type=2&prefix=photos/2006/&delimiter=/HTTP/1.1
Host:<BUCKET NAME>.s3.<REGION>.saturncloud.com.cn
x-amz-date:20160501T000433Z
Authorization:<authorization string>

在响应中，OSS 将会返回指定的 prefix，并将包含 prefix 且第一次出现 delimiter 字符的不同字符串作为不同的 CommonPrefixes 进行分组并返回。

示例 4：使用 Continuation Token

在这个示例中，初次请求返回 object 数量超过 1000 个。在响应中，OSS 返回了值为 true 的 IsTruncated 元素以及 NextContinuationToken 元素。

以下为响应示例：

如下随后的请求中，我们加入了 continuation-token 作为请求参数，并将之前返回的作为该参数值。

在如下返回示例中，OSS 将返回上次请求超出未返会的 object。

Head Bucket

描述

此操作用于确定指定 Bucket 是否存在。

请求

语法

请求参数

无请求参数

请求 Header

该操作仅使用通用的请求 Header，请参阅常见请求 Header。

请求元素

无请求元素

响应

响应 Header

该操作仅使用通用的响应 Header，请参阅常见响应 Header。

响应元素

无响应元素

示例

请求示例

响应示例

Put Bucket

描述

该操作可实现创建一个 Bucket；创建的 Bucket 所在的 Region 和发送请求的 Endpoint 所对应的 Region 一致。Bucket 所在 Region 确定后，该 Bucket 下的所有 Object 将一直存放在对应的地区。每个 Region 最多创建 20 个 Bucket。 Bucket 命名规则： 1.长度必须在 3-63 字符之间 2.名称仅能由小写字母、数字、中划线(-)组成 3.名称必须以小写字母或数字开头和结尾

请求

语法

请求参数

该操作无请求参数

请求 Header

该操作仅使用通用的请求 Header，请参阅常见请求 Header。

请求元素

无请求元素

响应

响应元素

无响应元素

示例

请求示例

响应示例

Put Bucket acl

描述

该操作可指定 Bucket 的访问控制列表（acl）。目前 Bucket 有三种访问权限：private、public-read、public-read-write。Put Bucket ACL 操作通过 Put 请求中的“x-amz-acl”头来设置。这个操作只有该 Bucket 的创建者有权限执行。如果操作成功，则返回 200；否则返回相应的错误码和提示信息。

请求

语法

请求参数

无请求参数

请求 Header

除公共请求 Header 外，您还可以使用以下 Header：通过 Header 您可以使用以下方法设置访问权限：  指定固定的 ACL OSS 支持一组预定义的 ACL（固定 ACL），每种固定 ACL 都有一组预定义的被授权者和权限。要使用固定 ACL 设置访问权限，请使用以下 Header，并将固定 ACL 名称指定（默认私有读写 private）。

名称	描述	必须
x-amz-acl	指定固定 ACL 设置 Bucket 的 ACL。 Type: String

Valid Values: private、public-read、public-read-write Default: private | 否 |

若您想明确指定每个被授权者的权限请使用 put Bukcet policy 完成细粒度授权。

Bucket 操作

Delete Bucket

描述

请求

语法

请求参数

请求 Header

请求元素

响应

响应 Header

示例

请求示例

响应示例

GET Bucket acl

描述

请求

语法

请求参数

请求 Header

请求元素

响应

响应 Header

响应元素

示例

请求示例

响应示例

Get Bucket(List Objects)Version 2

描述

请求

语法

请求参数

请求 Header

请求元素

响应

响应 Header

响应元素

示例

示例 1：Listing Keys

请求示例

响应示例

示例 2：Listing Keys（使用 max-keys,prefix,start-after 元素）

请求示例

响应示例

示例 3：Listing Keys（使用 prefix 和 delimiter 元素）

示例 4：使用 Continuation Token

Head Bucket

描述

请求

语法

请求参数

请求 Header

请求元素

响应

响应 Header

响应元素

示例

请求示例

响应示例

Put Bucket

描述

请求

语法

请求参数

请求 Header

请求元素

响应

响应元素

示例

请求示例

响应示例

Put Bucket acl

描述

请求

语法

请求参数

请求 Header

请求示例

响应示例