Home

S3 API

S3 API 参考

本文档提供了 Alluxio S3 API 的详细参考，允许您使用流行的 Amazon S3 协议与 Alluxio 进行交互。提供的示例同时使用了 AWS CLI 和标准 REST 客户端（如 curl）。

存储桶操作

CreateBucket

在 Alluxio 中创建一个新的存储桶。

方法： PUT

路径： /{bucket}

响应：

  • 200 - OK：存储桶创建成功。

示例：

AWS CLI
$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api create-bucket \
  --bucket=testbucket

$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api list-buckets
{
    "Buckets": [
        {
            "Name": "testbucket",
            "CreationDate": "2022-05-03T11:32:34.156000+00:00"
        }
    ]
}
REST 客户端
$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
  -X PUT http://localhost:29998/testbucket

HTTP/1.1 200 OK
Date: Tue, 03 May 2022 21:35:05 GMT
Content-Length: 0
Server: Jetty(9.4.43.v20210629)

$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
  -X GET http://localhost:29998/
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 21:35:23 GMT
Content-Type: application/xml
Content-Length: 161
Server: Jetty(9.4.43.v20210629)

<ListAllMyBucketsResult>
  <Buckets>
    <Bucket>
      <Name>testbucket</Name>
      <CreationDate>2022-05-03T14:34:56.420Z</CreationDate>
    </Bucket>
  </Buckets>
</ListAllMyBucketsResult>

DeleteBucket

删除一个现有的存储桶。存储桶必须为空才能被删除。

方法： DELETE

路径： /{bucket}

响应：

  • 204 - No Content：存储桶删除成功。

示例：

AWS CLI
REST 客户端

ListBuckets

列出请求发送者拥有的所有存储桶。

方法： GET

路径： /

响应：

  • 200 - OK：返回一个包含存储桶列表的 XML 文档。

示例：

AWS CLI
REST 客户端

HeadBucket

此操作用于确定存储桶是否存在以及您是否有权访问它。

方法： HEAD

路径： /{bucket}

响应：

  • 200 - OK：存储桶存在且您有权访问。

  • 404 - Not Found：存储桶不存在。

示例：

AWS CLI
REST 客户端

GetBucketTagging

检索与存储桶关联的标签。

方法： GET

路径： /{bucket}?tagging

响应：

  • 200 - OK：返回一个带有标签集的 XML 文档。

示例：

AWS CLI
REST 客户端

PutBucketTagging

向现有存储桶添加一组标签。

方法： PUT

路径： /{bucket}?tagging

请求体： 包含标签集的 XML 文档。

响应：

  • 200 - OK：标签添加成功。

示例：

AWS CLI
REST 客户端

DeleteBucketTagging

从存储桶中删除标签。

方法： DELETE

路径： /{bucket}?tagging

响应：

  • 204 - No Content：标签删除成功。

示例：

AWS CLI
REST 客户端

对象操作

GetObject

从存储桶中检索对象。

方法： GET

路径： /{bucket}/{key}

响应：

  • 200 - OK：对象数据在响应体中返回。

示例：

AWS CLI
REST 客户端

PutObject

向存储桶添加对象。

方法： PUT

路径： /{bucket}/{key}

请求体： 对象内容。

响应：

  • 200 - OK：对象上传成功。

示例：

AWS CLI
REST 客户端

CopyObject

创建已存储在 Alluxio 中的对象的副本。

方法： PUT

路径： /{bucket}/{key}

请求头：

  • x-amz-copy-source：源存储桶和键的名称，用斜杠（/）分隔。

响应：

  • 200 - OK：返回一个包含复制操作结果的 XML 文档。

示例：

AWS CLI
REST 客户端

DeleteObject

从存储桶中删除对象。

方法： DELETE

路径： /{bucket}/{key}

响应：

  • 204 - No Content：对象删除成功。

示例：

AWS CLI
REST 客户端

DeleteObjects

在单个请求中从存储桶中删除多个对象。

方法： POST

路径： /{bucket}?delete

请求体： 一个 XML 文档，指定要删除的对象的键。

响应：

  • 200 - OK：返回一个 XML 文档，其中包含每个对象的删除操作结果。

示例：

AWS CLI
REST Client

HeadObject

从对象中检索元数据，而不返回对象本身。

方法: HEAD

路径: /{bucket}/{key}

响应:

  • 200 - OK: 元数据将在响应头中返回。

示例:

AWS CLI
REST Client

ListObjects

返回存储桶中部分或全部（最多 1,000 个）对象。

方法: GET

路径: /{bucket}

响应:

  • 200 - OK: 返回一个包含对象列表的 XML 文档。

示例:

AWS CLI
REST Client

ListObjectsV2

返回存储桶中部分或全部（最多 1,000 个）对象。这是 ListObjects的新版本。

方法: GET

路径: /{bucket}?list-type=2

响应:

  • 200 - OK: 返回一个包含对象列表的 XML 文档。

示例:

AWS CLI
REST Client

GetObjectTagging

检索与对象关联的标签。

方法: GET

路径: /{bucket}/{key}?tagging

响应:

  • 200 - OK: 返回一个包含标签集合的 XML 文档。

示例:

AWS CLI
REST Client

PutObjectTagging

向现有对象添加一组标签。

方法: PUT

路径: /{bucket}/{key}?tagging

请求体: 包含标签集合的 XML 文档。

响应:

  • 200 - OK: 标签已成功添加。

示例:

AWS CLI
REST Client

DeleteObjectTagging

从对象中删除标签。

方法: DELETE

路径: /{bucket}/{key}?tagging

响应:

  • 204 - No Content: 标签已成功删除。

示例:

AWS CLI
REST Client

分片上传操作

CreateMultipartUpload

启动一个分片上传并返回上传 ID。

方法: POST

路径: /{bucket}/{key}?uploads

响应:

  • 200 - OK: 返回一个包含 UploadId 的 XML 文档。

示例:

AWS CLI
REST Client

UploadPart

在分片上传中上传一个分片。

方法: PUT

路径: /{bucket}/{key}

查询参数:

  • partNumber: 正在上传的分片编号，为 1 到 10,000 之间的正整数。

  • uploadId: 分片上传的上传 ID。

请求体: 分片的内容。

响应:

  • 200 - OK: 分片上传成功。

示例:

AWS CLI
REST Client

UploadPartCopy

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

方法: PUT

路径: /{bucket}/{key}

查询参数:

  • partNumber: 正在上传的分片编号。

  • uploadId: 分片上传的上传 ID。

请求头:

  • x-amz-copy-source: 源存储桶名称和对象键。

响应:

  • 200 - OK: 分片复制成功。

示例:

AWS CLI
REST Client

ListParts

列出特定分片上传中已上传的分片。

方法: GET

路径: /{bucket}/{key}

查询参数:

  • uploadId: 分片上传的上传 ID。

响应:

  • 200 - OK: 返回包含分片列表的 XML 文档。

示例:

AWS CLI
REST Client

ListMultipartUploads

此操作列出正在进行的分片上传。

方法: GET

路径: /{bucket}?uploads

响应:

  • 200 - OK: 返回包含正在进行的分片上传列表的 XML 文档。

示例:

AWS CLI
REST Client

AbortMultipartUpload

中止分片上传。中止分片上传后，无法再使用该上传 ID 上传任何分片。

方法: DELETE

路径: /{bucket}/{key}

查询参数:

  • uploadId: 要中止的分片上传 ID。

响应:

  • 204 - No Content: 分片上传已成功中止。

示例:

AWS CLI
REST Client

CompleteMultipartUpload

通过组装先前上传的分片完成分片上传。

方法: POST

路径: /{bucket}/{key}

查询参数:

  • uploadId: 要完成的分片上传 ID。

请求体: 一个包含待组装分片列表的 XML 文档。

响应:

  • 200 - OK: 返回一个包含已完成对象信息的 XML 文档。

示例:

AWS CLI
REST Client

Last updated