3.4. S3 对象操作

表 3.3. 对象操作
功能	Status
获取对象	支持
Get Object Information	支持
Put Object Lock	支持
Get Object Lock	支持
Put Object Legal Hold	支持
Get Object Legal Hold	支持
Put Object Retention	支持
Get Object Retention	支持
Put Object Tagging	支持
Get Object Tagging	支持
Delete Object Tagging	支持
放置对象	支持
删除对象	支持
Delete Multiple Objects	支持
获取对象 ACL	支持
放置对象 ACL	支持
复制对象	支持
后对象	支持
选项对象	支持
启动多部分上传	支持
Add a Part to a Multipart Upload	支持
List Parts of a Multipart Upload	支持
assemble Multipart Upload	支持
Copy Multipart Upload	支持
Abort Multipart Upload	支持
Multi-Tenancy	支持

3.4.1. S3 从存储桶获取对象

从存储桶检索对象：

语法

GET /BUCKET/OBJECT HTTP/1.1

添加 versionId 子资源以检索对象的特定版本：

语法

GET /BUCKET/OBJECT?versionId=VERSION_ID HTTP/1.1

请求 Headers

PartNumber

描述: 被读取的对象的一部分号。这为指定部分启用范围 GET 请求。使用此请求可用于只下载对象的一部分。
有效值: 1 到 10,000 之间的正整数。
必需: 否

range

描述: 要检索的对象范围。
注意
不支持每个 GET 请求的多个范围。
有效值: Range:bytes=beginbyte-endbyte
必需: 否

if-modified-since

描述: 仅当自时间戳起修改时才会获得。
有效值: Timestamp
必需: 否

if-unmodified-since

描述: 只有自时间戳起没有修改时才会获得。
有效值: Timestamp
必需: 否

if-match

描述: 仅在对象 ETag 匹配 ETag 时才会获得。
有效值: 实体标签
必需: 否

if-none-match

描述: 仅在对象 ETag 不匹配 ETag 时才会获得。
有效值: 实体标签
必需: 否

带有请求标头的 Sytnax

GET /BUCKET/OBJECT?partNumber=PARTNUMBER&versionId=VersionId HTTP/1.1
Host: Bucket.s3.amazonaws.com
If-Match: IfMatch
If-Modified-Since: IfModifiedSince
If-None-Match: IfNoneMatch
If-Unmodified-Since: IfUnmodifiedSince
Range: Range

响应标头

Content-Range

描述: 只有在请求中指定范围标头字段时，才会返回数据范围

x-amz-version-id

描述: 返回版本 ID 或 null。

3.4.2. S3 获取对象信息

返回有关对象的信息。此请求将返回与 Get Object 请求相同的标头信息，但将仅包含元数据，而不包括对象数据有效负载。

检索对象的当前版本：

语法

HEAD /BUCKET/OBJECT HTTP/1.1

添加 versionId 子资源以检索特定版本的信息：

语法

HEAD /BUCKET/OBJECT?versionId=VERSION_ID HTTP/1.1

请求 Headers

range

描述: 要检索的对象范围。
有效值: Range:bytes=beginbyte-endbyte
必需: 否

if-modified-since

描述: 仅当自时间戳起修改时才会获得。
有效值: Timestamp
必需: 否

if-match

描述: 仅在对象 ETag 匹配 ETag 时才会获得。
有效值: 实体标签
必需: 否

if-none-match

描述: 仅在对象 ETag 匹配 ETag 时才会获得。
有效值: 实体标签
必需: 否

响应标头

x-amz-version-id

描述: 返回版本 ID 或 null。

3.4.3. S3 put 对象锁定

put 对象锁定 API 将锁定配置放在所选存储桶中。使用对象锁定，您可以使用 Write-Once-Read-Many (WORM)模型存储对象。对象锁定可确保，在一个固定的时间端内或无限期内，对象不会被删除或被覆盖。对象锁定配置中指定的规则默认应用于放置在所选存储桶中的每个新对象。

重要

除非创建存储桶时启用对象锁定，否则操作会失败。

语法

PUT /BUCKET?object-lock HTTP/1.1

示例

PUT /testbucket?object-lock HTTP/1.1

请求实体

ObjectLockConfiguration

描述: 用于请求的容器。
Type: Container
必需: 是

ObjectLockEnabled

描述: 指明此存储桶是否启用了对象锁定配置。
Type: 字符串
必需: 是

规则

描述: 指定存储桶的对象锁定规则。
Type: Container
必需: 否

DefaultRetention

描述: 应用到放置在指定存储桶中的新对象的默认保留周期。
Type: Container
必需: 否

模式

描述: 默认对象锁定保留模式。有效值：GOVERNANCE/COMPLIANCE.
Type: Container
必需: 是

Days

描述: 为默认保留周期指定的天数。
Type: 整数
必需: 否

Years

描述: 在默认保留周期内指定的年数。
Type: 整数
必需: 否

HTTP 响应

400

状态代码: MalformedXML
描述: XML 不正确。

409

状态代码: InvalidBucketState
描述: 没有启用存储桶对象锁定。

其它资源

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

3.4.4. S3 get 对象锁定

get 对象锁定 API 检索存储桶的锁定配置。

语法

GET /BUCKET?object-lock HTTP/1.1

示例

GET /testbucket?object-lock HTTP/1.1

响应实体

ObjectLockConfiguration

描述: 用于请求的容器。
Type: Container
必需: 是

ObjectLockEnabled

描述: 指明此存储桶是否启用了对象锁定配置。
Type: 字符串
必需: 是

规则

描述: 指定存储桶的对象锁定规则就位。
Type: Container
必需: 否

DefaultRetention

描述: 应用到放置在指定存储桶中的新对象的默认保留周期。
Type: Container
必需: 否

模式

描述: 默认对象锁定保留模式。有效值：GOVERNANCE/COMPLIANCE.
Type: Container
必需: 是

Days

描述: 为默认保留周期指定的天数。
Type: 整数
必需: 否

Years

描述: 在默认保留周期内指定的年数。
Type: 整数
必需: 否

其它资源

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

3.4.5. S3 put 对象法律持有

放置对象法律持有 API 将法律持有的配置应用到所选对象。在法律持有的情况下，您无法覆盖或删除对象版本。法律持有没有关联的保留周期，除非明确删除为止。

语法

PUT /BUCKET/OBJECT?legal-hold&versionId= HTTP/1.1

示例

PUT /testbucket/testobject?legal-hold&versionId= HTTP/1.1

versionId 子资源检索对象的特定版本。

请求实体

LegalHold

描述: 用于请求的容器。
Type: Container
必需: 是

Status

描述: 指明指定对象是否有法律持有。有效值： ON/OFF
Type: 字符串
必需: 是

其它资源

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

3.4.6. S3 get 对象法律持有

get 对象法律持有 API 检索对象当前法律持有状态。

语法

GET /BUCKET/OBJECT?legal-hold&versionId= HTTP/1.1

示例

GET /testbucket/testobject?legal-hold&versionId= HTTP/1.1

versionId 子资源检索对象的特定版本。

响应实体

LegalHold

描述: 用于请求的容器。
Type: Container
必需: 是

Status

描述: 指明指定对象是否有法律持有。有效值： ON/OFF
Type: 字符串
必需: 是

其它资源

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

3.4.7. S3 放置对象保留

放置对象保留 API 将对象保留配置放在对象中。保留周期为固定时间保护对象版本。有两种模式：GOVERNANCE 和 COMPLIANCE。这两个保留模式对对象应用不同的保护级别。

注意

在此期间，您的对象是 Write-Once-Read-Many-protected (WORM-protected)，且无法覆盖或删除。

语法

PUT /BUCKET/OBJECT?retention&versionId= HTTP/1.1

示例

PUT /testbucket/testobject?retention&versionId= HTTP/1.1

versionId 子资源检索对象的特定版本。

请求实体

保留

描述: 用于请求的容器。
Type: Container
必需: 是

模式

描述: 指定对象的保留模式。有效值：GOVERNANCE、COMPLIANCE.
Type: 字符串
必需: 是

RetainUntilDate

描述: 保留日期。
格式: 2020-01-05T00:00:00.000Z
Type: Timestamp
必需: 是

其它资源

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

3.4.8. S3 get 对象保留

get 对象保留 API 会检索对象上的对象保留配置。

语法

GET /BUCKET/OBJECT?retention&versionId= HTTP/1.1

示例

GET /testbucket/testobject?retention&versionId= HTTP/1.1

versionId 子资源检索对象的特定版本。

响应实体

保留

描述: 用于请求的容器。
Type: Container
必需: 是

模式

描述: 指定对象的保留模式。有效值： GOVERNANCE/COMPLIANCE
Type: 字符串
必需: 是

RetainUntilDate

描述: 保留日期。格式：2020-01-05T00:00:00.000Z
Type: Timestamp
必需: 是

其它资源

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

3.4.9. S3 put 对象标记

put 对象标记 API 将标签与对象相关联。标签是键值对。若要放置任何其他版本的标签，请使用 versionId 查询参数。您必须具有执行 s3:PutObjectTagging 操作的权限。默认情况下，bucket 所有者具有这个权限，并可向其他用户授予此权限。

语法

PUT /BUCKET/OBJECT?tagging&versionId= HTTP/1.1

示例

PUT /testbucket/testobject?tagging&versionId= HTTP/1.1

请求实体

Tagging

描述: 用于请求的容器。
Type: Container
必需: 是

TagSet

描述: 一组标签的集合。
Type: 字符串
必需: 是

其它资源

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

3.4.10. S3 get 对象标记

get 对象标记 API 返回对象标签。默认情况下，GET 操作返回对象当前版本的信息。

注意

对于版本化的存储桶，您可以在存储桶中拥有多个版本的对象。要检索任何其他版本的标签，请在请求中添加 versionId 查询参数。

语法

GET /BUCKET/OBJECT?tagging&versionId= HTTP/1.1

示例

GET /testbucket/testobject?tagging&versionId= HTTP/1.1

其它资源

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

3.4.11. S3 删除对象标记

delete 对象标记 API 从指定对象中删除整个标签集。您必须具有执行 s3:DeleteObjectTagging 操作的权限才能使用此操作。

注意

要删除特定对象版本的标签，请在请求中添加 versionId 查询参数。

语法

DELETE /BUCKET/OBJECT?tagging&versionId= HTTP/1.1

示例

DELETE /testbucket/testobject?tagging&versionId= HTTP/1.1

其它资源

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

3.4.12. S3 将对象添加到存储桶

添加对象到存储桶。您必须在存储桶上具有写入权限才能执行此操作。

语法

PUT /BUCKET/OBJECT HTTP/1.1

请求 Headers

content-md5

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

content-type

描述: 标准 MIME 类型。
有效值: 任何 MIME 类型。默认：binary/octet-stream。
必需: 否

x-amz-meta-<…>*

描述: 用户元数据。与对象存储。
有效值: 字符串最多 8kb。无默认值。
必需: 否

x-amz-acl

描述: 可以拒绝 ACL。
有效值: 私有,public-read,public-read-write,authenticated-read
必需: 否

响应标头

x-amz-version-id

描述: 返回版本 ID 或 null。

3.4.13. S3 删除对象

删除对象。要求在包含存储桶上设置 WRITE 权限。

删除对象。如果对象版本控制为 on，它会创建一个标记。

语法

DELETE /BUCKET/OBJECT HTTP/1.1

要在对对象进行版本控制时删除对象，您必须指定 versionId 子资源以及要删除的对象的版本。

DELETE /BUCKET/OBJECT?versionId=VERSION_ID HTTP/1.1

3.4.14. S3 删除多个对象

此 API 调用从存储桶中删除多个对象。

语法

POST /BUCKET/OBJECT?delete HTTP/1.1

3.4.15. S3 获取对象的访问控制列表(ACL)

返回对象的当前版本的 ACL：

语法

GET /BUCKET/OBJECT?acl HTTP/1.1

添加 versionId 子资源以检索特定版本的 ACL：

语法

GET /BUCKET/OBJECT?versionId=VERSION_ID&acl HTTP/1.1

响应标头

x-amz-version-id

描述: 返回版本 ID 或 null。

响应实体

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.16. S3 设置对象的访问控制列表(ACL)

为对象的当前版本设置对象 ACL。

语法

PUT /BUCKET/OBJECT?acl

请求实体

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.17. S3 复制一个对象

要复制对象，请使用 PUT 并指定目标存储桶和对象名称。

语法

PUT /DEST_BUCKET/DEST_OBJECT HTTP/1.1
x-amz-copy-source: SOURCE_BUCKET/SOURCE_OBJECT

请求 Headers

x-amz-copy-source

描述: 源 bucket 名称 + 对象名称。
有效值: BUCKET/OBJECT
必需: 是

x-amz-acl

描述: 可以拒绝 ACL。
有效值: 私有,public-read,public-read-write,authenticated-read
必需: 否

x-amz-copy-if-modified-since

描述: 仅在自时间戳以来修改时才复制。
有效值: Timestamp
必需: 否

x-amz-copy-if-unmodified-since

描述: 仅在自时间戳起未修改时才复制。
有效值: Timestamp
必需: 否

x-amz-copy-if-match

描述: 只有在对象 ETag 匹配 ETag 时复制。
有效值: 实体标签
必需: 否

x-amz-copy-if-none-match

描述: 只有在对象 ETag 匹配 ETag 时复制。
有效值: 实体标签
必需: 否

响应实体

CopyObjectResult

描述: 用于响应元素的容器。
Type: Container

LastModified

描述: 源对象的最后修改日期。
Type: Date

Etag

描述: 新对象的 ETag。
Type: 字符串

3.4.18. S3 使用 HTML 表单向存储桶添加对象

使用 HTML 表单将对象添加到存储桶。您必须在存储桶上具有写入权限才能执行此操作。

语法

POST /BUCKET/OBJECT HTTP/1.1

3.4.19. S3 确定请求选项

用于确定实际请求是否可以通过特定原始卷、HTTP 方法和标头发送的 preflight 请求。

语法

OPTIONS /OBJECT HTTP/1.1

3.4.20. S3 启动多部分上传

启动多部分上传过程。返回 UploadId，您可以在添加额外部分、列出部分和完成或带出多部分上传时指定。

语法

POST /BUCKET/OBJECT?uploads

请求 Headers

content-md5

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

content-type

描述: 标准 MIME 类型。
有效值: 任何 MIME 类型。默认： binary/octet-stream
必需: 否

x-amz-meta-<…>

描述: 用户元数据。与对象存储。
有效值: 字符串最多 8kb。无默认值。
必需: 否

x-amz-acl

描述: 可以拒绝 ACL。
有效值: 私有,public-read,public-read-write,authenticated-read
必需: 否

响应实体

InitiatedMultipartUploadsResult

描述: 用于结果的容器。
Type: Container

Bucket

描述: 将接收对象内容的存储桶。
Type: 字符串

键

描述: key 请求参数指定的密钥（若有）。
Type: 字符串

UploadId

描述: 由 upload-id 请求参数指定的 ID，标识多部分上传（如果有）。
Type: 字符串

3.4.21. S3 在多部分上传中添加部分

添加部分到多部分上传。

指定 uploadId 子资源以及上传 ID，将部分添加到多部分上传：

语法

PUT /BUCKET/OBJECT?partNumber=&uploadId=UPLOAD_ID HTTP/1.1

可能会返回以下 HTTP 响应：

HTTP 响应

404

状态代码: NoSuchUpload
描述: 指定 upload-id 与此对象上启动的任何上传都不匹配。

3.4.22. S3 列出多部分上传

指定 uploadId 子资源以及上传 ID 来列出多部分上传：

语法

GET /BUCKET/OBJECT?uploadId=UPLOAD_ID HTTP/1.1

响应实体

InitiatedMultipartUploadsResult

描述: 用于结果的容器。
Type: Container

Bucket

描述: 将接收对象内容的存储桶。
Type: 字符串

键

描述: key 请求参数指定的密钥（若有）。
Type: 字符串

UploadId

描述: 由 upload-id 请求参数指定的 ID，标识多部分上传（如果有）。
Type: 字符串

initiator

描述: 包含开始上传的用户的 ID 和 DisplayName。
Type: Container

ID

描述: 启动器的 ID。
Type: 字符串

DisplayName

描述: 启动器的显示名称。
Type: 字符串

所有者

描述: 拥有上传对象的用户的 ID 和 DisplayName 的容器。
Type: Container

StorageClass

描述: 用于存储生成的对象的方法。STANDARD 或 REDUCED_REDUNDANCY
Type: 字符串

PartNumberMarker

描述: 如果 IsTruncated 为 true，则后续请求中使用的部分标记。在列表前面。
Type: 字符串

NextPartNumberMarker

描述: 如果 IsTruncated 为 true，则后续请求中使用的下一部分标记。列表的末尾。
Type: 字符串

IsTruncated

描述: 如果为 true，则仅返回对象上传内容的子集。
Type: 布尔值

Part

描述: Key, Part, InitiatorOwner, StorageClass, 和 Initiated 元素的容器。
Type: Container

PartNumber

描述: Key, Part, InitiatorOwner, StorageClass, 和 Initiated 元素的容器。
Type: 整数

ETag

描述: 部分的实体标签。
Type: 字符串

大小

描述: 上传部分的大小。
Type: 整数

3.4.23. S3 汇编上传的部分

装配已上传的部分并创建新的对象，从而完成多部分上传。

指定 uploadId 子资源以及上传 ID 以完成多部分上传：

语法

POST /BUCKET/OBJECT?uploadId=UPLOAD_ID HTTP/1.1

请求实体

CompleteMultipartUpload

描述: 由一个或多个部分组成的容器。
Type: Container
必需: 是

Part

描述: 适用于 PartNumber 和 ETag 的容器。
Type: Container
必需: 是

PartNumber

描述: 部分的标识符。
Type: 整数
必需: 是

ETag

描述: 部分的实体标签。
Type: 字符串
必需: 是

响应实体

CompleteMultipartUploadResult

描述: 用于响应的容器。
Type: Container

位置

描述: 新对象的资源标识符(path)。
Type: URI

bucket

描述: 包含新对象的存储桶的名称。
Type: 字符串

键

描述: 对象的密钥。
Type: 字符串

ETag

描述: 新对象的实体标签。
Type: 字符串

3.4.24. S3 复制多部分上传

通过从现有对象复制数据作为数据源来上传部分。

指定 uploadId 子资源以及上传 ID，以执行多部分上传副本：

语法

PUT /BUCKET/OBJECT?partNumber=PartNumber&uploadId=UPLOAD_ID HTTP/1.1
Host: cname.domain.com

Authorization: AWS ACCESS_KEY:HASH_OF_HEADER_AND_SECRET

请求 Headers

x-amz-copy-source

描述: 源存储桶名称和对象名称。
有效值: BUCKET/OBJECT
必需: 是

x-amz-copy-source-range

描述: 从源对象复制的字节数。
有效值: 范围： bytes=first-last，其中第一个和最后一个是要复制的零字节偏移。例如，bytes=0-9 表示您想要复制源的前 10 字节。
必需: 否

响应实体

CopyPartResult

描述: 用于所有响应元素的容器。
Type: Container

ETag

描述: 返回新部分的 ETag。
Type: 字符串

LastModified

描述: 返回部分上次修改的日期。
Type: 字符串

其它资源

有关此功能的更多信息，请参阅 Amazon S3 网站。

3.4.25. S3 中止多部分上传

中止多部分上传。

指定 uploadId 子资源以及上传 ID 以中止多部分上传：

语法

DELETE /BUCKET/OBJECT?uploadId=UPLOAD_ID HTTP/1.1

3.4.26. S3 Hadoop 互操作性

对于需要 Hadoop 分布式文件系统(HDFS)访问的数据分析应用，可以使用用于 Hadoop 的 Apache S3A 连接器来访问 Ceph 对象网关。S3A 连接器是一个开源工具，它将 S3 兼容对象存储呈现为 HDFS 文件系统，在数据存储在 Ceph 对象网关中时，对应用程序进行读写语义。

Ceph 对象网关与 Hadoop 2.7.3 附带的 S3A 连接器完全兼容。

其它资源

如需了解有关多租户的详细信息，请参阅 Red Hat Ceph Storage 对象网关指南。

3.4.1. S3 从存储桶获取对象

3.4.2. S3 获取对象信息

3.4.3. S3 put 对象锁定

3.4.4. S3 get 对象锁定

3.4.5. S3 put 对象法律持有

3.4.6. S3 get 对象法律持有

3.4.7. S3 放置对象保留

3.4.8. S3 get 对象保留

3.4.9. S3 put 对象标记

3.4.10. S3 get 对象标记

3.4.11. S3 删除对象标记

3.4.12. S3 将对象添加到存储桶

3.4.13. S3 删除对象

3.4.14. S3 删除多个对象

3.4.15. S3 获取对象的访问控制列表(ACL)

3.4.16. S3 设置对象的访问控制列表(ACL)

3.4.17. S3 复制一个对象

3.4.18. S3 使用 HTML 表单向存储桶添加对象

3.4.19. S3 确定请求选项

3.4.20. S3 启动多部分上传

3.4.21. S3 在多部分上传中添加部分

3.4.22. S3 列出多部分上传

3.4.23. S3 汇编上传的部分

3.4.24. S3 复制多部分上传

3.4.25. S3 中止多部分上传

3.4.26. S3 Hadoop 互操作性

学习

尝试、购买和销售

社区

关于红帽文档

让开源更具包容性

關於紅帽

Red Hat legal and privacy links

Red Hat legal and privacy links