bucket 操作

优质

小牛编辑

127浏览

2023-12-01

PUT Bucket

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

Note

当前版本我们不支持通过 PUT /{bucket} 来请求实例。

约束条件

一般而言，bucket 名称应该遵循下述域名命名约束条件

Bucket 名必须是唯一的
Bucket 名必须以小写字母开始和结尾
Bucket 名可以包含破折号 (-).

语法

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

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

参数

Name	Description	Valid Values	Required
`x-amz-acl`	Canned ACLs.	`private`, `public-read`, `public-read-write`, `authenticated-read`	No

HTTP 响应

如果 bucket 的名称是独一无二的，满足约束条件并且没有被使用，操作就会成功的。如果已经存在同名的 bucket，并且 bucket 的所有者就是当前请求用户，操作也会返回成功的。如果 bucket 名称已经被使用，操作将会返回失败。

HTTP Status	Status Code	Description
`409`	BucketAlreadyExists	Bucket already exists under different user’s ownership.

删除 Bucket

删除一个 bucket，得到成功删除 bucket 的返回信息后就可以重用该 bucket 名。

语法

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

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

HTTP 响应

HTTP Status	Status Code	Description
`204`	No Content	Bucket removed.

获取 Bucket

返回 bucket 中的对象列表

语法

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

参数

Name	Type	Description
`prefix`	String	Only returns objects that contain the specified prefix.
`delimiter`	String	The delimiter between the prefix and the rest of the object name.
`marker`	String	A beginning index for the list of objects returned.
`max-keys`	Integer	The maximum number of keys to return. Default is 1000.

HTTP 响应

HTTP Status	Status Code	Description
`200`	OK	Buckets retrieved

Bucket 响应实例

GET /{bucket} 返回一个容器，包含 bucket 的下列字段

Name	Type	Description
`ListBucketResult`	Entity	The container for the list of objects.
`Name`	String	The name of the bucket whose contents will be returned.
`Prefix`	String	A prefix for the object keys.
`Marker`	String	A beginning index for the list of objects returned.
`MaxKeys`	Integer	The maximum number of keys returned.
`Delimiter`	String	If set, objects with the same prefix will appear in the `CommonPrefixes` list.
`IsTruncated`	Boolean	If `true`, only a subset of the bucket’s contents were returned.
`CommonPrefixes`	Container	If multiple objects contain the same prefix, they will appear in this list.

对象响应实例

ListBucketResult 包含很多对象，每个对象都包含一个 Contents 容器.

Name	Type	Description
`Contents`	Object	A container for the object.
`Key`	String	The object’s key.
`LastModified`	Date	The object’s last-modified date/time.
`ETag`	String	An MD-5 hash of the object. (entity tag)
`Size`	Integer	The object’s size.
`StorageClass`	String	Should always return `STANDARD`.

获取 Bucket 位置

获取 bucket 的 region。只有 bucket 的所有者才能发起这个请求。一个 bucket 可以在发起 PUT 请求的时候通过指定 LocationConstraint 参数来限制它的 region。

语法

如下所示在 bucket 资源后面添加 location 子资源

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

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

响应实例

Name	Type	Description
`LocationConstraint`	String	The region where bucket resides, empty string for defult region

获取 Bucket ACL

获取 bucket 的访问控制列表。请求用户需要是该 bucket 的所有者或者已经针对这个 bucket 授权了 READ_ACP 权限的用户.

语法

如下所示，在 bucket 请求后面添加 acl 子资源.

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

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

响应实例

Name	Type	Description
`AccessControlPolicy`	Container	A container for the response.
`AccessControlList`	Container	A container for the ACL information.
`Owner`	Container	A container for the bucket owner’s `ID` and `DisplayName`.
`ID`	String	The bucket owner’s ID.
`DisplayName`	String	The bucket owner’s display name.
`Grant`	Container	A container for `Grantee` and `Permission`.
`Grantee`	Container	A container for the `DisplayName` and `ID` of the user receiving a grant of permission.
`Permission`	String	The permission given to the `Grantee` bucket.

设置 Bucket ACL

为一个已经存在的 bucket 设置一个访问控制。请求用户需要是该 bucket 的所有者或者已经针对这个 bucket 授权了 WRITE_ACP 权限的用户.

语法

如下所示，在 bucket 请求后面添加 acl 子资源.

PUT /{bucket}?acl HTTP/1.1

响应实例

Name	Type	Description
`AccessControlPolicy`	Container	A container for the request.
`AccessControlList`	Container	A container for the ACL information.
`Owner`	Container	A container for the bucket owner’s `ID` and `DisplayName`.
`ID`	String	The bucket owner’s ID.
`DisplayName`	String	The bucket owner’s display name.
`Grant`	Container	A container for `Grantee` and `Permission`.
`Grantee`	Container	A container for the `DisplayName` and `ID` of the user receiving a grant of permission.
`Permission`	String	The permission given to the `Grantee` bucket.

列出 Bucket 的分块上传

GET /?uploads 返回当前正在进行中的分块上传的列表。比如：应用程序启动了一个分块上传，但是服务尚未完成所有块的上传。

语法

GET /{bucket}?uploads HTTP/1.1

参数

你可以为 GET /{bucket}?uploads 指定一些参数，但下面这些参数都不是必须的.

Name	Type	Description
`prefix`	String	Returns in-progress uploads whose keys contains the specified prefix.
`delimiter`	String	The delimiter between the prefix and the rest of the object name.
`key-marker`	String	The beginning marker for the list of uploads.
`max-keys`	Integer	The maximum number of in-progress uploads. The default is 1000.
`max-uploads`	Integer	The maximum number of multipart uploads. The range from 1-1000. The default is 1000.
`upload-id-marker`	String	Ignored if `key-marker` isn’t specified. Specifies the `ID` of first upload to list in lexicographical order at or following the `ID`.

响应实例

Name	Type	Description
`ListMultipartUploadsResult`	Container	A container for the results.
`ListMultipartUploadsResult.Prefix`	String	The prefix specified by the `prefix` request parameter (if any).
`Bucket`	String	The bucket that will receive the bucket contents.
`KeyMarker`	String	The key marker specified by the `key-marker` request parameter (if any).
`UploadIdMarker`	String	The marker specified by the `upload-id-marker` request parameter (if any).
`NextKeyMarker`	String	The key marker to use in a subsequent request if `IsTruncated` is `true`.
`NextUploadIdMarker`	String	The upload ID marker to use in a subsequent request if `IsTruncated` is `true`.
`MaxUploads`	Integer	The max uploads specified by the `max-uploads` request parameter.
`Delimiter`	String	If set, objects with the same prefix will appear in the `CommonPrefixes` list.
`IsTruncated`	Boolean	If `true`, only a subset of the bucket’s upload contents were returned.
`Upload`	Container	A container for `Key`, `UploadId`, `InitiatorOwner`, `StorageClass`, and `Initiated` elements.
`Key`	String	The key of the object once the multipart upload is complete.
`UploadId`	String	The `ID` that identifies the multipart upload.
`Initiator`	Container	Contains the `ID` and `DisplayName` of the user who initiated the upload.
`DisplayName`	String	The initiator’s display name.
`ID`	String	The initiator’s ID.
`Owner`	Container	A container for the `ID` and `DisplayName` of the user who owns the uploaded object.
`StorageClass`	String	The method used to store the resulting object. `STANDARD` or `REDUCED_REDUNDANCY`
`Initiated`	Date	The date and time the user initiated the upload.
`CommonPrefixes`	Container	If multiple objects contain the same prefix, they will appear in this list.
`CommonPrefixes.Prefix`	String	The substring of the key after the prefix as defined by the `prefix` request parameter.

启用/禁用 BUCKET 版本

PUT /?versioning 这个子资源用于设置已有 bucket 的版本化状态。只有 bucket 所有者才能设置这个版本状态。

版本状态可以设置为如下取值之一：

Enabled : 为 bucket 内的对象启用版本，放入 bucket 内的对象都会收到一个唯一的版本 ID 。
Suspended : 为 bucket 内的对象禁用版本，放入 bucket 内的对象其版本 ID 都是 null 。

如果从没给某一个 bucket 设置过版本状态，那它就没有版本状态；获取版本的 GET 请求就不会返回版本的状态值。

语法

PUT  /{bucket}?versioning  HTTP/1.1

请求实体

Name	Type	Description
`VersioningConfiguration`	Container	A container for the request.
`Status`	String	Sets the versioning state of the bucket. Valid Values: Suspended/Enabled