SequoiaDB巨杉数据库_SequoiaDB
  • 数据库实例
  • 分布式引擎
  • 图形化界面
  • 参考手册
  • 注册 登录
    • 文档中心
    v3.4

    对象存储实例

    1. 文档中心
    2. 数据库实例
    3. 对象存储实例
    4. S3对象存储实例
    5. 操作
    6. Rest接口

    Rest接口

    本文档将介绍 SequoiaS3 支持的 Rest 接口。

    桶API

    下述将介绍桶相关的接口。

    GET Service

    查询用户创建的所有存储桶

    请求语法

    GET / HTTP/1.1
Host: ip:port
Date: date
Authorization: authorization string

    结果解析

    查询结果以 XML 形式在响应消息体中显示。

    元素 说明
    ListAllMyBucketsResult 包含 Owner 和 Buckets
    Owner 存储桶所有者，包含 ID 和 DisplayName，属于 ListAllMyBucketsResult
    ID 存储桶所有者的 ID，属于 ListAllMyBucketsResult.Owner
    DisplayName 存储桶所有者的名称，属于 ListAllMyBucketsResult.Owner
    Buckets 桶列表，包含若干 Bucket，属于 ListAllMyBucketsResult
    Bucket 存储桶，包含 Name 和 CreationDate，属于 ListAllMyBucketsResult.Buckets
    Name 存储桶名称，属于 ListAllMyBucketsResult.Buckets.Bucket
    CreationDate 存储桶创建时间，属于 ListAllMyBucketsResult.Buckets.Bucket

    示例

    响应结果如下：

    <ListAllMyBucketsResult>
  <Owner>
    <DisplayName>username</DisplayName>
    <ID>34455</ID>
  </Owner>
  <Buckets>
    <Bucket>
      <Name>mybucket</Name>
      <CreationDate>2019-02-03T16:45:09.000Z</CreationDate>
    </Bucket>
    <Bucket>
      <Name>samples</Name>
      <CreationDate>2019-02-03T16:41:58.000Z</CreationDate>
    </Bucket>
  </Buckets>
</ListAllMyBucketsResult>

    PUT Bucket

    创建存储桶

    Note:

    存储桶名需在整个系统内唯一，长度在 3~63 之间。

    请求语法

    PUT /bucketname HTTP/1.1
Host: ip:port
Content-Length: length
Date: date
Authorization: authorization string
<CreateBucketConfiguration>
  <LocationConstraint>Region</LocationConstraint>
</CreateBucketConfiguration>

    请求元素

    用户需要在请求消息体中使用 XML 形式指定存储桶创建的区域，如果不指定则存储桶创建在默认的区域上。

    元素 说明
    CreateBucketConfiguration 包含 LocationConstraint
    LocationConstraint 指定创建存储桶的区域，类型为 string

    示例

    响应结果如下：

    HTTP/1.1 200 OK
Location: /bucketName
Content-Length: 0
Date: Fri, 16 Aug 2019 11:11:53 GMT

    DELETE Bucket

    删除存储桶

    请求语法

    DELETE /bucketname HTTP/1.1
Host: ip:port
Date: date
Authorization: authorization string

    示例

    响应结果如下：

    HTTP/1.1 204 No Content
Date: Fri, 16 Aug 2019 10:11:53 GMT

    HEAD Bucket

    检查一个存储桶是否存在

    请求语法

    HEAD /bucketname HTTP/1.1
Date: date
Authorization: authorization string
Host: ip:port

    示例

    响应结果如下：

    HTTP/1.1 200 OK
Date: Fri, 16 Aug 2019 10:10:53 GMT

    PUT Bucket versioning

    修改存储桶的版本控制状态

    请求语法

    PUT /bucketname?versioning HTTP/1.1
Host: ip:port
Content-Length: length
Date: date
Authorization: authorization string

<VersioningConfiguration>
  <Status>VersioningState</Status>
</VersioningConfiguration>

    参数说明

    参数名 说明
    versioning 表示该请求为修改存储桶的版本控制状态

    请求元素

    在请求消息体中使用 XML 形式指定存储桶的版本控制状态。

    元素 说明
    VersioningConfiguration 包含 Status
    Status 版本控制状态，有效值为 Suspended|Enabled，属于 VersioningConfiguration

    示例

    响应结果如下：

    HTTP/1.1 200 OK
Date: Wed, 01 Mar  2006 12:00:00 GMT

    GET Bucket versioning

    查询桶的版本控制状态

    请求语法

    GET /bucketname?versioning HTTP/1.1
Host: ip:port
Content-Length: length
Date: date
Authorization: authorization string

    结果解析

    查询结果以 XML 形式在响应消息头中显示。

    元素 说明
    VersioningConfiguration 包含 Status
    Status 版本控制状态，有效值为 Suspended

    示例

    • 打开版本控制开关，查询结果如下：

      <VersioningConfiguration>
  <Status>Enabled</Status>
</VersioningConfiguration>

    • 禁用版本控制，查询结果如下：

      <VersioningConfiguration>
  <Status>Suspended</Status>
</VersioningConfiguration>

    • 从未开启或禁用过版本控制，查询结果如下：

      <VersioningConfiguration/>

    GET Bucket location

    查询桶所在的区域

    请求语法

    GET /bucketname?location HTTP/1.1
Host: ip:port
Date: date
Authorization: authorization string

    结果解析

    查询结果以 XML 格式在响应消息体中显示。

    元素 说明
    LocationConstraint 桶所在的区域

    示例

    • 已经配置了区域的存储桶，查询结果如下：

      <LocationConstraint>region</LocationConstraint>

    • 未配置区域的存储桶，查询结果如下：

      <LocationConstraint/>

    GET Bucket (List Objects) Version 1

    查询存储桶内对象列表

    请求语法

    GET /bucketname HTTP/1.1
Host: ip:port
Date: date
Authorization: authorization string

    请求参数

    参数名 说明
    prefix 前缀，类型为 string，返回具有前缀的对象列表，
    delimiter 分隔符，类型为 string，如果指定 prefix，则 prefix 后第一次出现的分隔符之间包含相同字符串的所有键都被分组在一个 CommonPrefixes；如果未指定 prefix 参数，则子字符串从对象名称的开头开始
    marker 指定在存储桶中列出对象要开始的键，类型为 string，返回对象键按照 UTF-8 二进制顺序从该标记后的键开始按顺序排列
    max-keys 设置响应中返回的最大键数，类型为 string，默认值为 1000，如果要查询返回数量少于 1000，可以填写其他值，填写超过 1000 的值，仍然按照 1000 条返回
    encoding-type 响应结果编码类型，只支持 url，由于对象名称可以包含任意字符，但是 XML 对某些特别的字符无法解析，所以需要对响应中的对象名称进行编码

    结果解析

    查询结果以 XML 形式在响应消息体中显示。

    元素 说明
    ListBucketResult 包含存储桶信息、查询条件和查询的对象信息
    Name 存储桶名称
    Prefix 查询的 prefix 条件
    Delimiter 查询的 delimiter 条件
    Marker 查询的 marker 条件
    MaxKeys 查询的 maxKeys 条件
    Encoding-Type 查询的 encoding-type 条件
    IsTruncated 如果该字段为 true，说明由于条数限制，本次没有查询完所有符合条件的结果，可以使用 NextMarker 作为下一次查询的 Marker 条件继续查询剩余内容
    NextMarker 当 IsTruncated 为 true 时，该字段返回的是本次查询的最后一条的记录
    CommonPrefixes 当查询条件指定了 Delimter 时，Prefix 后面第一次出现 Delimiter 的位置（包括 Delimiter）之前的内容作为 CommonPrefix，当有多个对象具有相同的 CommonPrefix 时，只返回一条 CommonPrefix，计数一次，对象信息不返回
    Prefix CommonPrefix 包含的前缀，属于 ListBucketResult.CommonPrefixes
    Contents 包含对象的元数据
    Key 对象的名称，属于 ListBucketResult.Contents
    LastModified 创建对象的时间，属于 ListBucketResult.Contents
    ETag 对象的 MD5 值，属于 ListBucketResult.Contents
    Size 对象的大小，单位为字节，属于 ListBucketResult.Contents
    Owner 存储桶的所有者，属于 ListBucketResult.Contents
    ID 存储桶所有者的 ID，属于 ListBucketResult.Contents.Owner
    DisplayName 桶所有者的名字，属于 ListBucketResult.Contents.Owner

    示例

    • 不携带查询条件，查询存储桶内所有记录

      GET /bucketname HTTP/1.1
Host: ip:port
Date: date
Authorization: authorization string

      查询结果如下：

      <ListBucketResult>
    <Name>bucketname</Name>
    <Prefix/>
    <Marker/>
    <MaxKeys>1000</MaxKeys>
    <IsTruncated>false</IsTruncated>
    <Contents>
        <Key>my-image.jpg</Key>
        <LastModified>2019-08-12T17:50:30.000Z</LastModified>
        <ETag>"fba9dede5f27731c9771645a39863328"</ETag>
        <Size>434234</Size>
        <Owner>
            <ID>125664</ID>
            <DisplayName>username</DisplayName>
        </Owner>
    </Contents>
    <Contents>
       <Key>my-third-image.jpg</Key>
         <LastModified>2019-08-12T17:51:30.000Z</LastModified>
         <ETag>"1b2cf535f27731c974343645a3985328"</ETag>
         <Size>64994</Size>
         <Owner>
            <ID>125664</ID>
            <DisplayName>username</DisplayName>
        </Owner>
    </Contents>
</ListBucketResult>

    • 本次请求指定 prefix 为 N，起始位置为 Ned，并只返回 100 条记录

      GET /mybucket?prefix=N&marker=Ned&max-keys=100 HTTP/1.1
Host: iP:port
Date: date
Authorization: authorization string

      查询结果如下：

      <ListBucketResult>
  <Name>mybucket</Name>
  <Prefix>N</Prefix>
  <Marker>Ned</Marker>
  <MaxKeys>100</MaxKeys>
  <IsTruncated>false</IsTruncated>
  <Contents>
    <Key>Nelson</Key>
    <LastModified>2019-08-12T12:00:00.000Z</LastModified>
    <ETag>"828ef3fdfa96f00ad9f27c383fc9ac7f"</ETag>
    <Size>5</Size>
    <Owner>
      <ID>125664</ID>
      <DisplayName>username</DisplayName>
     </Owner>
  </Contents>
  <Contents>
    <Key>Neo</Key>
    <LastModified>2019-08-12T12:01:00.000Z</LastModified>
    <ETag>"828ef3fdfa96f00ad9f27c383fc9ac7f"</ETag>
    <Size>4</Size>
     <Owner>
      <ID>125664</ID>
      <DisplayName>username</DisplayName>
    </Owner>
 </Contents>
</ListBucketResult>

    • 桶内已经有如下对象：

      sample.jpg
photos/2006/January/sample.jpg
photos/2006/February/sample2.jpg
photos/2006/February/sample3.jpg
photos/2006/February/sample4.jpg

      本次请求携带分隔符/

      GET /mybucket-2?delimiter=/ HTTP/1.1
Host: ip:port
Date: date
Authorization: authorization string

      查询结果如下：

      <ListBucketResult>
  <Name>mybucket-2</Name>
  <Prefix/>
  <Marker/>
  <MaxKeys>1000</MaxKeys>
  <Delimiter>/</Delimiter>
  <IsTruncated>false</IsTruncated>
  <Contents>
    <Key>sample.jpg</Key>
    <LastModified>2019-08-12T12:01:00.000Z</LastModified>
    <ETag>"bf1d737a4d46a19f3bced6905cc8b902"</ETag>
    <Size>142863</Size>
    <Owner>
      <ID>canonical-user-id</ID>
      <DisplayName>display-name</DisplayName>
    </Owner>
  </Contents>
  <CommonPrefixes>
    <Prefix>photos/</Prefix>
  </CommonPrefixes>
</ListBucketResult>

    GET Bucket (List Objects) Version 2

    查询桶内对象列表

    请求语法

    GET /bucketname?list-type=2 HTTP/1.1
Host: ip:port
Date: date
Authorization: authorization string

    请求参数

    参数名 说明
    list-type 固定设置为 2，List Objects 的第二个版本
    prefix 前缀，类型为 string，返回具有前缀的对象列表
    delimiter 分隔符，类型为 string，如果指定 prefix，则 prefix 后第一次出现的分隔符之间包含相同字符串的所有键都被分组在一个 CommonPrefixes；如果未指定 prefix 参数，则子字符串从对象名称的开头开始
    start-after 指定在存储桶中列出对象要开始的键，类型为 string，返回对象键按照 UTF-8 二进制顺序从该标记后的键开始按顺序排列
    max-keys 设置响应中返回的最大键数，类型为 string，默认值 1000，如果要查询返回数量少于 1000，可以填写其他值，填写超过 1000 的值，仍然按照 1000 条返回
    encoding-type 响应结果编码类型，只支持 url，由于对象名称可以包含任意字符，但是 XML 对某些特别的字符无法解析，所以需要对响应中的对象名称进行编码
    continuation-token 当响应结果被截断，还有部分未返回时，响应结果中会包含 NextContinuationToken，要列出下一组对象，可以使用 NextContinuationToken 下一个请求中的元素作为 continuation-token
    fetch-owner 默认情况下，结果中不会返回 Owner 信息，如果要在响应中包含 Owner 信息，将该参数置为 true

    结果解析

    查询结果以 XML 形式在响应消息体中显示。

    元素 说明
    ListBucketResult 包含存储桶信息、查询条件和查询的对象信息
    Name 存储桶名称
    Prefix 查询的 prefix 条件
    Delimiter 查询的 delimiter 条件
    StartAfter 查询的 start-after 条件
    ContinuationToken 查询的 continuation-token 条件
    MaxKeys 查询的 maxKeys 条件
    Encoding-Type 查询的 encoding-type 条件
    KeyCount 本次查询返回的记录数
    IsTruncated 如果该字段为 true，说明由于条数限制，本次没有查询完所有符合条件的结果，可以使用 NextMarker 作为下一次查询的 Marker 条件继续查询剩余内容
    NextContinuationToken 当 IsTruncated 为 true 时，NextContinuationToken 记录位置，下一次请求在 continuation-token 携带该令牌继续查询下一组记录
    CommonPrefixes 当查询条件指定了 Delimter 时，Prefix 后面第一次出现 Delimiter 的位置（包括 Delimiter）之前的内容作为 CommonPrefix，当有多个对象具有相同的 CommonPrefix 时，只返回一条 CommonPrefix，计数一次，对象信息不返回
    Prefix CommonPrefix 包含的前缀，属于 ListBucketResult.CommonPrefixes
    Contents 包含对象的元数据
    Key 对象的名称，属于 ListBucketResult.Contents
    LastModified 创建对象的时间，属于 ListBucketResult.Contents
    ETag 对象的 MD5 值，属于 ListBucketResult.Contents
    Size 对象的大小，单位为字节，属于 ListBucketResult.Contents
    Owner 存储桶的所有者，属于 ListBucketResult.Contents
    ID 存储桶所有者的 ID，属于 ListBucketResult.Contents.Owner
    DisplayName 桶所有者的名字，属于 ListBucketResult.Contents.Owner

    示例

    • 不携带查询条件，查询存储桶内所有记录

      GET /bucketname?list-type=2 HTTP/1.1
Host: ip:port
Date: Sat, 17 Aug 2019 17:51:00 GMT
Authorization: authorization string

      查询结果如下：

      <ListBucketResult>
    <Name>bucketname</Name>
    <Prefix/>
    <Marker/>
    <KeyCount>205</KeyCount>
    <MaxKeys>1000</MaxKeys>
    <IsTruncated>false</IsTruncated>
    <Contents>
        <Key>my-image.jpg</Key>
        <LastModified>2019-08-12T17:50:30.000Z</LastModified>
        <ETag>"fba9dede5f27731c9771645a39863328"</ETag>
        <Size>434234</Size>
        <Owner>
            <ID>125664</ID>
            <DisplayName>username</DisplayName>
        </Owner>
    </Contents>
    <Contents>
       ...
    </Contents>
    ...
</ListBucketResult>

    • 指定 prefix 为 N，起始位置为 Ned，并只返回 100 条记录

      GET /mybucket?list-type=2&prefix=N&start-after=Ned&max-keys=100 HTTP/1.1
Host: iP:port
Date: Sat, 17 Aug 2019 17:45:00 GMT
Authorization: authorization string

      查询结果如下，实际查询到两条符合条件的记录：

      <ListBucketResult>
  <Name>mybucket</Name>
  <Prefix>N</Prefix>
  <Marker>Ned</Marker>
  <KeyCount>2</KeyCount>
  <MaxKeys>100</MaxKeys>
  <IsTruncated>false</IsTruncated>
  <Contents>
    <Key>Nelson</Key>
    <LastModified>2019-08-12T12:00:00.000Z</LastModified>
    <ETag>"828ef3fdfa96f00ad9f27c383fc9ac7f"</ETag>
    <Size>5</Size>
    <Owner>
      <ID>125664</ID>
      <DisplayName>username</DisplayName>
     </Owner>
  </Contents>
  <Contents>
    <Key>Neo</Key>
    <LastModified>2019-08-12T12:01:00.000Z</LastModified>
    <ETag>"828ef3fdfa96f00ad9f27c383fc9ac7f"</ETag>
    <Size>4</Size>
     <Owner>
      <ID>125664</ID>
      <DisplayName>username</DisplayName>
    </Owner>
 </Contents>
</ListBucketResult>

    • 桶内已经有如下对象

      sample.jpg
photos/2006/January/sample.jpg
photos/2006/February/sample2.jpg
photos/2006/February/sample3.jpg
photos/2006/February/sample4.jpg

      本次请求携带分隔符/

      GET /mybucket-2?list-type=2&delimiter=/ HTTP/1.1
Host: ip:port
Date: date
Authorization: authorization string

      查询结果如下：

      <ListBucketResult>
  <Name>mybucket-2</Name>
  <Prefix/>
  <Marker/>
  <KeyCount>2</KeyCount>
  <MaxKeys>1000</MaxKeys>
  <Delimiter>/</Delimiter>
  <IsTruncated>false</IsTruncated>
  <Contents>
    <Key>sample.jpg</Key>
    <LastModified>2019-08-12T12:01:00.000Z</LastModified>
    <ETag>"bf1d737a4d46a19f3bced6905cc8b902"</ETag>
    <Size>142863</Size>
    <Owner>
      <ID>canonical-user-id</ID>
      <DisplayName>display-name</DisplayName>
    </Owner>
  </Contents>
  <CommonPrefixes>
    <Prefix>photos/</Prefix>
  </CommonPrefixes>
</ListBucketResult>

    GET Bucket Object versions

    查询桶内对象的所有版本

    请求语法

    GET /bucketname?versions HTTP/1.1
Host: ip:port
Date: date
Authorization: authorization string

    请求参数

    参数名 说明
    prefix 前缀，类型为 string，返回具有前缀的对象列表
    delimiter 分隔符，类型为 string，如果指定 prefix，则 prefix 后第一次出现的分隔符之间包含相同字符串的所有键都被分组在一个 CommonPrefixes；如果未指定 prefix 参数，则子字符串从对象名称的开头开始
    key-marker 指定在存储桶中列出对象要开始的键，类型为 string，返回对象键按照 UTF-8 二进制顺序从该标记后的键开始按顺序排列
    version-id-marker 指定起始位置的 version，仅在指定了 key-marker 的情况下有效
    max-keys 设置响应中返回的最大键数，类型为 string，默认值 1000，如果要查询返回数量少于 1000，可以填写其他值，填写超过 1000 的值，仍然按照 1000 条返回
    encoding-type 响应结果编码类型，只支持 url，由于对象名称可以包含任意字符，但是 XML 对某些特别的字符无法解析，所以需要对响应中的对象名称进行编码

    结果解析

    查询结果以 XML 形式在响应消息体中显示。

    元素 说明
    ListVersionsResult 包含存储桶信息、查询条件和查询的对象版本信息
    Name 存储桶名称
    Prefix 查询的 prefix 条件
    Delimiter 查询的 delimiter 条件
    KeyMarker 查询的 key-marker 条件
    VersionIDMarker 查询的 version-id-marker 条件
    MaxKeys 查询的 maxKeys 条件
    Encoding-Type 查询的 encoding-type 条件
    IsTruncated 如果该字段为 true，说明由于条数限制，本次没有查询完所有符合条件的结果，可以使用 NextMarker 作为下一次查询的 Marker 条件继续查询剩余内容
    NextKeyMarker 当 IsTruncated 为 true 时，NextKeyMarker 记录本次返回的最后一个对象或者 CommonPrefix
    NextVersionIdMarker 当 IsTruncated 为 true 时，NextVersionIdMarker 记录本次返回的最后一条记录的 version
    CommonPrefixes 当查询条件指定了 Delimter 时，Prefix 后面第一次出现 Delimiter 的位置（包括 Delimiter）之前的内容作为 CommonPrefix，当有多个对象具有相同的 CommonPrefix 时，只返回一条 CommonPrefix，计数一次，对象信息不返回
    Prefix CommonPrefix 包含的前缀，属于 ListVersionsResult.CommonPrefixes
    Version 包含对象版本的元数据
    DeleteMarker 包含删除标记
    Key 对象的名称，属于 ListVersionsResult.Version|ListVersionsResult.DeleteMarker
    VersionId 对象的版本号，属于 ListVersionsResult.Version|ListVersionsResult.DeleteMarker
    IsLatest 是否是最新版本，属于 ListVersionsResult.Version|ListVersionsResult.DeleteMarker
    LastModified 创建对象的时间，属于 ListVersionsResult.Version|ListVersionsResult.DeleteMarker
    ETag 对象的 MD5 值，属于 ListVersionsResult.Version
    Size 对象的大小，单位为字节，属于 ListVersionsResult.Version
    Owner 存储桶的所有者，属于 ListVersionsResult.Version|ListVersionsResult.DeleteMarker
    ID 存储桶所有者的 ID，属于 ListVersionsResult.Version.Owner|ListVersionsResult.DeleteMarker.Owner
    DisplayName 桶所有者的名字，属于 ListVersionsResult.Version.Owner|ListVersionsResult.DeleteMarker.Owner

    示例

    • 查询存储桶内所有版本

      GET /bucketname?versions HTTP/1.1
Host: ip:port
Date: date
Authorization: authorization string

      查询结果如下：

      <ListVersionsResult>
    <Name>bucket</Name>
    <Prefix>my</Prefix>
    <KeyMarker/>
    <VersionIdMarker/>
    <MaxKeys>1000</MaxKeys>
    <IsTruncated>false</IsTruncated>
    <Version>
        <Key>my-image.jpg</Key>
        <VersionId>234</VersionId>
        <IsLatest>true</IsLatest>
        <LastModified>2019-08-16T17:50:32.000Z</LastModified>
        <ETag>"fba9dede5f27731c9771645a39863328"</ETag>
        <Size>434234</Size>
        <Owner>
            <ID>125664</ID>
            <DisplayName>username</DisplayName>
        </Owner>
    </Version>
    <DeleteMarker>
        <Key>my-second-image.jpg</Key>
        <VersionId>55566666</VersionId>
        <IsLatest>true</IsLatest>
        <LastModified>2019-08-16T17:50:31.000Z</LastModified>
        <Owner>
            <ID>125664</ID>
            <DisplayName>username</DisplayName>
        </Owner>
    </DeleteMarker>
    <Version>
        <Key>my-second-image.jpg</Key>
        <VersionId>45667</VersionId>
        <IsLatest>false</IsLatest>
        <LastModified>2019-08-16T17:50:30.000Z</LastModified>
        <ETag>"9b2cf535f27731c974343645a3985328"</ETag>
        <Size>166434</Size>
        <Owner>
            <ID>125664</ID>
            <DisplayName>username</DisplayName>
        </Owner>
    </Version>
</ListVersionsResult>

    • 携带分隔符/进行查询

      GET /mybucket-2?versions&delimiter=/ HTTP/1.1
Host: ip:port
Date: date
Authorization: authorization string

      响应结果如下：

      <ListVersionsResult>
  <Name>mvbucketwithversionon1</Name>
  <Prefix/>
  <KeyMarker/>
  <VersionIdMarker/>
  <MaxKeys>1000</MaxKeys>
  <Delimiter>/</Delimiter>
  <IsTruncated>false</IsTruncated>
  <Version>
    <Key>Sample.jpg</Key>
    <VersionId>toxMzQlBsGyGCz1YuMWMp90cdXLzqOCH</VersionId>
    <IsLatest>true</IsLatest>
    <LastModified>2019-02-02T18:46:20.000Z</LastModified>
    <ETag>"3305f2cfc46c0f04559748bb039d69ae"</ETag>
    <Size>3191</Size>
    <Owner>
        <ID>125664</ID>
        <DisplayName>username</DisplayName>
    </Owner>
  </Version>
  <CommonPrefixes>
    <Prefix>photos/</Prefix>
  </CommonPrefixes>
  <CommonPrefixes>
    <Prefix>videos/</Prefix>
  </CommonPrefixes>
</ListVersionsResult>

    List Multipart Uploads

    查询桶内所有已初始化未完成的分段上传请求

    请求语法

    GET /bucketname?uploads HTTP/1.1
Host: ip:port
Date: Date
Authorization: authorization string

    请求参数

    参数 说明
    prefix 前缀，类型为 string，返回具有前缀的对象列表
    delimiter 分隔符，类型为 string，如果指定 prefix，则 prefix 后第一次出现的分隔符之间包含相同字符串的所有键都被分组在一个 CommonPrefixes；如果未指定 prefix 参数，则子字符串从对象名称的开头开始
    key-marker 指定在存储桶中列出对象要开始的键，类型为 string，返回对象键按照 UTF-8 二进制顺序从该标记后的键开始按顺序排列
    upload-id-marker 指定起始位置的 uploadId，仅在指定了 key-marker 的情况下有效
    max-uploads 设置响应中返回的最大键数，类型为 string，默认值 1000，如果要查询返回数量少于 1000，可以填写其他值，填写超过 1000 的值，仍然按照 1000 条返回
    encoding-type 对响应内容进行的编码方法，只支持 url，由于对象名称可以包含任意字符，但是 XML 对某些特别的字符无法解析，所以需要对响应中的对象名称进行编码

    结果解析

    查询结果在响应消息体中以 XML 形式体现。

    元素 说明
    ListMultipartUploadsResult 包含桶信息、查询条件和未完成的分段上传信息
    Bucket 存储桶名称
    Prefix 查询的 prefix 条件
    Delimiter 查询的 delimiter 条件
    KeyMarker 查询的 key-marker 条件
    UploadIdMarker 查询的 upload-id-marker 条件
    MaxUploads 查询的 maxUploads 条件
    Encoding-Type 查询的 encoding-type 条件
    IsTruncated 如果该字段为 true，说明由于条数限制，本次没有查询完所有符合条件的结果，可以使用 NextMarker 作为下一次查询的 Marker 条件继续查询剩余内容
    NextKeyMarker 当 IsTruncated 为 true 时，NextKeyMarker 记录本次返回的最后一个对象或者 CommonPrefix
    NextUploadIdMarker 当 IsTruncated 为 true 时，NextUploadIdMarker 记录本次返回的最后一条记录的 uploadId
    CommonPrefixes 当查询条件指定了 Delimter 时，Prefix 后面第一次出现 Delimiter 的位置（包括 Delimiter）之前的内容作为 CommonPrefix，当有多个对象具有相同的 CommonPrefix 时，只返回一条 CommonPrefix，计数一次，对象信息不返回
    Prefix CommonPrefix 包含的前缀，属于 ListMultipartUploadsResult.CommonPrefixes
    Upload 包含分段上传信息
    Key 对象的名称，属于 ListMultipartUploadsResult.Upload
    UploadId 分段上传的 uploadId，属于 ListMultipartUploadsResult.Upload
    Initiated 分段上传的的初始化时间，属于 ListMultipartUploadsResult.Upload
    Owner 存储桶的所有者，属于 ListMultipartUploadsResult.Upload
    ID 存储桶所有者的 ID，属于 ListMultipartUploadsResult.Upload.Owner
    DisplayName 桶所有者的名字，属于 ListMultipartUploadsResult.Upload.Owner

    示例

    查询 uploads，携带分隔符/

    GET /example-bucket?uploads&delimiter=/ HTTP/1.1
Host: ip:port
Date: Sat, 17 Aug 2019 20:34:56 GMT
Authorization: authorization string

    查询结果如下：

    <ListMultipartUploadsResult>
  <Bucket>example-bucket</Bucket>
  <KeyMarker/>
  <UploadIdMarker/>
  <NextKeyMarker>sample.jpg</NextKeyMarker>
  <NextUploadIdMarker>4444</NextUploadIdMarker>
  <Delimiter>/</Delimiter>
  <Prefix/>
  <MaxUploads>1000</MaxUploads>
  <IsTruncated>false</IsTruncated>
  <Upload>
    <Key>sample.jpg</Key>
    <UploadId>4444</UploadId>
    <Initiator>
      <ID>2234</ID>
      <DisplayName>s3-nickname</DisplayName>
    </Initiator>
    <Owner>
      <ID>2234</ID>
      <DisplayName>s3-nickname</DisplayName>
    </Owner>
    <Initiated>2019-08-16T19:24:17.000Z</Initiated>
  </Upload>
  <CommonPrefixes>
    <Prefix>photos/</Prefix>
  </CommonPrefixes>
  <CommonPrefixes>
    <Prefix>videos/</Prefix>
  </CommonPrefixes>
</ListMultipartUploadsResult>

    对象API

    下述将介绍对象相关的接口。

    PUT Object

    上传一个对象到桶中，如果已有则覆盖

    Note:

    当开启了版本控制，同一个名称的对象可以在系统中保留多个版本。系统会为每次上传的对象生成一个 version ID，并保留每个版本。

    请求语法

    PUT /bucketname/ObjectName HTTP/1.1
Host: ip:port
Date: date
Authorization: authorization string

    请求头部

    头域 说明
    Cache-Control 指定请求/响应链中的缓存属性
    Content-Disposition 当获取对象时，该属性提示将对象保存为的文件名
    Content-Encoding 对象的附加编码类型，例如压缩文档使用的 gzip 类型
    Content-MD5 对象内容（不包含头部）的 MD5 值经过 BASE64 编码后得到字符串，服务端收到对象后也会做同样的计算，比较 Content-MD5 和服务端计算得出的结果，可以防止上传的对象内容被篡改或不完整
    Content-Type 请求内容的 MIME 类型
    Expect 当 expect 设置为 100-continue，发送 put object 的请求时并不立刻发送对象内容，而是等收到 100 临时响应或等待超时再发送
    Expires 缓存的超时时间
    x-amz-meta- 自定义元数据

    结果解析

    响应信息通过 header 返回。

    头域 说明
    ETag 对象内容的 MD5 值转换为 16 进制之后生成的字符串
    x-amz-version-id 版本号，当版本控制状态为 Enabled 时，该字段返回此次上传对象的版本号；当版本控制状态为 Suspended 时，该字段返回 null；当未开启或禁用版本控制，该字段不返回

    示例

    上传一个对象

    PUT /bucketname/my-image.jpg HTTP/1.1
Host: ip:port
Date: Sat, 17 Aug 2019 17:50:00 GMT
Authorization: authorization string
Content-Type: text/plain
Content-Length: 11434
Expect: 100-continue
[11434 bytes of object data]

    响应结果如下：

    HTTP/1.1 100 Continue

HTTP/1.1 200 OK
Date: Sat, 17 Aug 2019 17:50:00 GMT
ETag: "1b2cf535f27731c974343645a3985328"
Content-Length: 0

    PUT Object - Copy

    从系统中已有的对象拷贝到目标对象

    Note:

    该操作不需要从本地上传对象内容。

    请求语法

    PUT /destinationbucket/destinationObject HTTP/1.1
Host: ip:port
x-amz-copy-source: /source_bucket/sourceObject
x-amz-metadata-directive: metadata_directive
x-amz-copy-source-if-match: etag
x-amz-copy-source-if-none-match: etag
x-amz-copy-source-if-unmodified-since: time_stamp
x-amz-copy-source-if-modified-since: time_stamp
<request metadata>
Authorization: authorization string

    请求头部

    头域 说明
    x-amz-copy-source 必须携带的头部，复制对象的源对象地址，包含源存储桶和源对象，例如：/source_bucket/sourceObject ，默认复制源对象的最新版本；如果要指定版本复制，则需要增加版本号，例如：/source_bucket/sourceObject?versionId=3344
    x-amz-metadata-directive 指定是否从源对象复制元数据到目标对象，取值包括"COPY"和"REPLACE"，默认值为"COPY"
    当指定为"COPY"时，从源对象复制元数据到目标对象；当指定为"REPLACE"时，源对象的元数据都不会复制到目标对象，目标对象使用复制对象请求中携带的元数据
    x-amz-copy-if-modified-since 时间，只有当源对象的创建时间在此时间后才进行复制
    x-amz-copy-if-unmodified-since 时间，只有当源对象的创建时间在此之前才进行复制
    x-amz-copy-if-match ETag，只有当源对象的 ETag 与此 ETag 匹配才进行复制
    x-amz-copy-if-none-match ETag，只有当源对象的 ETag 与此 ETag 不匹配才进行复制
    Cache-Control 指定请求/响应链中的缓存属性
    Content-Disposition 当获取对象时，该属性提示将对象保存为的文件名
    Content-Encoding 对象的附加编码类型，例如压缩文档使用的 gzip 类型
    Content-MD5 对象内容（不包含头部）计算 MD5 值后经过 BASE64 编码得到字符串，服务端收到对象后也会做同样的计算，比较 Content-MD5 和服务端计算得出的结果是否一致，可以防止上传的对象内容被篡改或不完整
    Expires 缓存的超时时间
    x-amz-meta- 自定义元数据

    结果解析

    版本号在响应 header 中体现。

    头域 说明
    x-amz-version-id 复制后生成对象的版本号
    x-amz-copy-source-version-id 源对象的版本号，复制后对象的 ETag 和创建时间在消息体中以 XML 形式体现
    CopyObjectResult 包含 ETag 和 LastModified
    ETag 新对象内容计算 MD5 值后转换为 16 进制得到的字符串，与源对象一致
    LastModified 新对象的创建时间

    示例

    复制指定的版本

    PUT /bucketname/my-second-image.jpg HTTP/1.1
Host: ip:port
Date: Sat, 17 Aug 2019 17:50:00 GMT
x-amz-copy-source: /bucketname/my-image.jpg?versionId=3344
Authorization: authorization string

    响应结果如下：

    HTTP/1.1 200 OK
x-amz-version-id:5656
x-amz-copy-source-version-id:3344
Date: Sat, 17 Aug 2019 17:50:00 GMT

<CopyObjectResult>
   <LastModified>2019-08-17T17:50:00</LastModified>
   <ETag>"9b2cf535f27731c974343645a3985328"</ETag>
</CopyObjectResult>

    GET Object

    获取对象内容

    请求语法

    GET /bucketname/ObjectName HTTP/1.1
Host: ip:port
Date: date
Authorization: authorization string

    请求参数

    参数名 说明
    versionId 获取指定版本的对象时通过此参数指定版本号
    response-content-type 指定响应消息中的 Content-Type 头部值
    response-content-language 指定响应消息中的 Content-Language 头部值
    response-expires 指定响应消息中的 Expires 头部值
    response-cache-control 指定响应消息中的 Cache-Control 头部值
    response-content-disposition 指定响应消息中的 Content-Disposition 头部值
    response-content-encoding 指定响应消息中的 Content-Encoding 头部值

    请求头部

    头域 说明
    Range 下载指定位置的字节数
    If-Modified-Since 指定时间，只有在指定时间之后更新过，才返回对象，否则返回 304
    If-Unmodified-Since 指定时间，只有在指定时间之前未更新，才返回对象，否则返回 412
    If-Match 指定 ETag，只有对象的 ETag 和 ETag 匹配，才返回对象，否则返回 412
    If-None-Match 指定 ETag，只有对象的 ETag 和 ETag 不匹配，才返回对象，否则返回 304

    结果解析

    响应信息通过 header 返回。

    头域 说明
    x-amz-version-id 获取的对象的版本号
    x-amz-meta- 对象的自定义元数据，与上传对象时的设置一致
    x-amz-delete-marker 当获取的对象是一个删除标记，响应中会携带该头部且值为 true；当获取的对象不是删除标记，则不会携带该头部

    示例

    • 获取一个对象

      GET /bucketname/ObjectName HTTP/1.1
Host: ip:port
Date: Sat, 17 Aug 2019 17:50:00 GMT
Authorization: authorization string

      响应结果如下：

      HTTP/1.1 200 OK
Date: Sat, 17 Aug 2019 17:50:00 GMT
Last-Modified: Sat, 17 Aug 2019 17:40:00 GMT
ETag: "fba9dede5f27731c9771645a39863328"
Content-Length: 434234

[434234 bytes of object data]

    • 指定版本号获取一个对象

      GET /bucketname/myObject?versionId=4433 HTTP/1.1
Host: ip:port
Date: Sat, 17 Aug 2019 17:50:00 GMT
Authorization: authorization string

      响应结果如下：

      HTTP/1.1 200 OK
Date: Sat, 17 Aug 2019 17:50:00 GMT
Last-Modified: Sat, 17 Aug 2019 17:40:00 GMT
x-amz-version-id: 4433
ETag: "fba9dede5f27731c9771645a39863328"
Content-Length: 434234
Content-Type: text/plain

[434234 bytes of object data]

    HEAD Object

    获取对象的元数据信息，不获取对象内容

    请求语法

    HEAD /bucketname/ObjectName HTTP/1.1
Host: ip:port
Authorization: authorization string

    请求参数

    参数名 说明
    versionId 获取指定版本的对象时通过此参数指定版本号

    请求头部

    头域 说明
    Range 下载指定位置的字节数
    If-Modified-Since 指定时间，只有在指定时间之后更新才返回对象，否则返回 304
    If-Unmodified-Since 指定时间，只有在指定时间之前未更新才返回对象，否则返回 412
    If-Match 指定 ETag，只有对象的 ETag 和 ETag 匹配才返回对象，否则返回 412
    If-None-Match 指定 ETag，只有对象的 ETag 和 ETag 不匹配，才返回对象，否则返回 304

    结果解析

    响应信息通过 header 返回。

    头域 说明
    x-amz-version-id 获取的对象的版本号
    x-amz-meta- 对象的自定义元数据，与上传对象时的设置一致

    示例

    • 获取对象的元数据

      HEAD /bucketname/my-image.jpg HTTP/1.1
Host: ip:port
Date: Sat, 17 Aug 2019 17:50:00 GMT
Authorization: authorization string

      响应结果如下：

      HTTP/1.1 200 OK
x-amz-version-id: 3344
Date: Sat, 17 Aug 2019 17:50:00 GMT
Last-Modified: Sat, 17 Aug 2019 17:40:00 GMT
ETag: "fba9dede5f27731c9771645a39863328"
Content-Length: 434234
Content-Type: text/plain

    • 获取指定版本对象的元数据

      HEAD /bucketname/my-image.jpg?versionId=3344 HTTP/1.1
Host: ip:port
Date: Sat, 17 Aug 2019 17:55:00 GMT
Authorization: authorization string

      响应结果如下：

      HTTP/1.1 200 OK
x-amz-version-id: 3344
Date: Sat, 17 Aug 2019 17:55:00 GMT
Last-Modified: Sat, 17 Aug 2019 17:40:00 GMT
ETag: "fba9dede5f27731c9771645a39863328"
Content-Length: 434234
Content-Type: text/plain

    DELETE Object

    删除对象

    Note:

    当用户打开了版本控制，删除对象时会生成一个删除标记，原来的对象还保存在系统中。如果用户需要永久删除对应版本，可以指定版本号进行删除。

    请求语法

    DELETE /bucketname/ObjectName HTTP/1.1
Host: ip:port
Date: date
Authorization: authorization string

    请求参数

    参数名 说明
    versionId 指定版本号，用于删除指定版本的对象

    结果解析

    响应信息通过 header 返回。

    头域 说明
    x-amz-delete-marker 1. 当删除操作生成一个删除标记时，会返回该头部且值为 true
    2. 当通过指定版本号删除对象时，如果删除的是一个删除标记，则会返回该头部且值为 true
    x-amz-version-id 1. 当删除操作生成一个删除标记时，该头部记录删除标记的版本号
    2. 当通过指定版本号删除对象时，该头部记录被删除的版本号

    示例

    • 删除一个未开启版本控制的桶内的对象

      DELETE /bucketname/my-second-image.jpg HTTP/1.1
Host: ip:port
Date: Sat, 17 Aug 2019 17:55:00 GMT
Authorization: authorization string
Content-Type: text/plain

      响应结果如下：

      HTTP/1.1 204 NoContent
Date: Sat, 17 Aug 2019 17:55:00 GMT
Content-Length: 0

    • 删除指定版本对象

      DELETE /bucketname/my-third-image.jpg?versionId=4455 HTTP/1.1
Host: ip:port
Date: Sat, 17 Aug 2019 17:58:00 GMT
Authorization: authorization string

      响应结果如下：

      HTTP/1.1 204 NoContent
x-amz-version-id: 4455
Date: Sat, 17 Aug 2019 17:58:00 GMT
Content-Length: 0

    DELETE Objects

    删除多个对象

    请求语法

    POST /bucketname?delete HTTP/1.1
Host: ip:port
Date: date
Authorization: authorization string

<Delete>
   <Object>
      <Key>string</Key>
      <VersionId>string</VersionId>
   </Object>
   <Quiet>boolean</Quiet>
</Delete>

    请求元素

    用户需要在请求消息体中使用 XML 形式指定待删除的对象列表，系统对每个待删除的对象都会执行单独的删除操作，并将删除结果返回，单个对象的删除操作参考 DELETE object。

    元素 说明
    Delete 包含 Object 和 Quiet
    Object 待删除的对象，包含 Key 和 VersionId
    Key 对象名称
    VersionId 对象版本号，可选
    Quiet 静默标志，boolean类型，当请求中包含该字段且值为true时，返回结果中仅包含删除失败的对象的结果。默认不携带此标志，返回结果中包含全部删除对象的操作结果。

    结果解析

    响应消息体中返回 XML 形式的结果，包含各个对象的删除结果。

    元素 说明
    DeleteResult 包含 Deleted 和 Error
    Deleted 删除成功的记录，包含 Key，VersionId，DeleteMarker 和 DeleteMarkerVersionId
    Key 已删除的对象名称
    VersionId 指定删除的对象版本号
    DeleteMarker 当删除操作产生了 DeleteMarker 或指定版本号删除的对象是一个DeleteMarker 时，该字段为true。
    DeleteMarkerVersionId 当删除操作产生了 DeleteMarker 或指定版本号删除的对象是一个DeleteMarker 时，该字段为新产生或指定的 VersionId
    Error 删除失败的记录，包括Code, Key, Message, VersionId
    Code 错误码
    Key 删除失败的对象名称
    Message 失败的描述
    VersionId 指定删除的对象版本号

    示例

    • 在未开启版本控制的桶内删除多个对象

      POST /bucketname?delete HTTP/1.1
Host: ip:port
Date: date
Authorization: authorization string

<Delete>
  <Object>
     <Key>key1</Key>
  </Object>
  <Object>
     <Key>key2</Key>
  </Object>
</Delete>

      删除成功，响应结果如下：

      <DeleteResult>
  <Deleted>
     <Key>key1</Key>
  </Deleted>
  <Deleted>
     <Key>key2</Key>
  </Deleted>
</DeleteResult>

    • 在开启版本控制的桶内删除多个对象

      POST /bucketname?delete HTTP/1.1
Host: ip:port
Date: date
Authorization: authorization string

<Delete>
  <Object>
     <Key>key1</Key>
  </Object>
  <Object>
     <Key>key2</Key>
  </Object>
</Delete>

      生成DeleteMarker，响应结果如下：

      <DeleteResult>
  <Deleted>
     <Key>key1</Key>
     <DeleteMarker>true</DeleteMarker>
     <DeleteMarkerVersionId>1</DeleteMarkerVersionId>
  </Deleted>
  <Deleted>
     <Key>key2</Key>
     <DeleteMarker>true</DeleteMarker>
     <DeleteMarkerVersionId>1</DeleteMarkerVersionId>
  </Deleted>
</DeleteResult>

    • 指定版本删除多个对象

      POST /bucketname?delete HTTP/1.1
Host: ip:port
Date: date
Authorization: authorization string

<Delete>
  <Object>
     <Key>key1</Key>
     <VersionId>0</VersionId>
  </Object>
  <Object>
     <Key>key2</Key>
     <VersionId>0</VersionId>
  </Object>
  <Object>
     <Key>key1</Key>
     <VersionId>1</VersionId>
  </Object>
</Delete>

      删除成功，响应结果如下：

      <DeleteResult>
  <Deleted>
     <Key>key1</Key>
     <VersionId>0</VersionId>
  </Deleted>
  <Deleted>
     <Key>key2</Key>
     <VersionId>0</VersionId>
  </Deleted>
  <Deleted>
     <Key>key1</Key>
     <VersionId>1</VersionId>
     <DeleteMarker>true</DeleteMarker>
     <DeleteMarkerVersionId>1</DeleteMarkerVersionId>
  </Deleted>
</DeleteResult>

    Initiate Multipart Upload

    初始化分段上传，获得 upload ID

    请求语法

    POST /bucketname/ObjectName?uploads HTTP/1.1
Host: ip:port
Date: date
Authorization: authorization string

    请求头部

    初始化时携带的元数据，在合并分段上传生成一个完整对象时作为对象的元数据。

    头域 说明
    Cache-Control 指定请求/响应链中的缓存属性
    Content-Disposition 当获取对象时，该属性提示将对象保存为的文件名
    Content-Encoding 对象的附加编码类型，例如压缩文档使用的 gzip 类型
    Content-Type 请求内容的 MIME 类型
    Expires 缓存的超时时间
    x-amz-meta- 自定义元数据

    结果解析

    响应消息体中返回 XML 形式的结果，包含 upload ID。

    元素 说明
    InitiateMultipartUploadResult 包含初始化分段的结果
    Bucket 初始化分段上传对象所在存储桶
    Key 初始化分段上传的对象名称
    UploadId 初始化分段上传的 ID，用来唯一标识一个分段上传请求

    示例

    初始化分段上传后，响应结果如下：

    HTTP/1.1 200 OK
Date: Sat, 17 Aug 2019 17:59:00 GMT
Content-Length: 151

<InitiateMultipartUploadResult>
  <Bucket>bucketname</Bucket>
  <Key>ObjectName</Key>
  <UploadId>56778</UploadId>
</InitiateMultipartUploadResult>

    Upload Part

    上传分段

    请求语法

    PUT /bucketname/ObjectName?partNumber=PartNumber&uploadId=UploadId HTTP/1.1
Host: ip:port
Date: date
Content-Length: Size
Authorization: authorization string

    请求参数

    参数名 说明
    partNumber 分段编号，有效范围为 1~10000
    uploadId upload ID，可以在 Initiate Multipart Upload 获得

    示例

    上传一个分段

    PUT /bucketname/ObjectName?partNumber=1&uploadId=56778 HTTP/1.1
Host: ip:port
Date: Sat, 17 Aug 2019 18:05:00 GMT
Content-Length: 10485760
Content-MD5: pUNXr/BjKK5G2UKvaRRrOA==
Authorization: authorization string

[10485760 bytes of object data]

    响应结果如下：

    HTTP/1.1 200 OK
Date: Sat, 17 Aug 2019 18:05:00 GMT
ETag: "b54357faf0632cce46e942fa68356b38"
Content-Length: 0

    List Parts

    查询分段列表

    请求语法

    GET /bucketname/ObjectName?uploadId=UploadId HTTP/1.1
Host: ip:port
Date: Date
Authorization: authorization string

    请求参数

    参数名 说明
    uploadId upload ID，可以在 Initiate Multipart Upload 获得
    max-parts 一次返回的最大分段数
    part-number?-marker 查询的起始位置
    encoding-type 响应结果编码类型，只支持 url；由于对象名称可以包含任意字符，但是 XML 对某些特别的字符无法解析，所以需要对响应中的对象名称进行编码

    结果解析

    查询结果以 XML 形式返回。

    元素 说明
    ListPartsResult 包含查询分段列表结果
    Bucket 分段上传的存储桶名称
    Key 分段上传的对象名称
    UploadId 分段上传请求的 upload ID
    Initiator 分段上传的发起者
    Owner 存储桶的拥有者
    DisplayName 用户的名称
    ID 用户 ID
    PartNumberMarker 查询的 part-number?-marker 条件
    MaxParts 查询的 max-parts 条件
    IsTruncated 是否被截断
    NextPartNumberMarker 当 IsTruncated 为 true 时，该字段记录下一次查询的起始位置
    Encoding-Type 查询的 encoding-type 条件
    Part 包含分段内容
    PartNumber 分段编号
    LastModified 分段的最新修改时间
    ETag 分段的 ETag
    Size 分段的大小

    示例

    查询 upload ID 为 56778 的分段列表，指定 max-parts 为 2，part-number-marker 为 1

    GET /bucketname/ObjectName?uploadId=56778&max-parts=2&part-number-marker=1 HTTP/1.1
Host: ip:port
Date: Sat, 17 Aug 2019 18:10:00 GMT
Authorization: authorization string

    响应结果如下：

    HTTP/1.1 200 OK
Date: Sat, 17 Aug 2019 18:10:00 GMT
Content-Length: 838

<ListPartsResult>
  <Bucket>bucketname</Bucket>
  <Key>ObjectName</Key>
  <UploadId>56778</UploadId>
  <Initiator>
    <DisplayName>username</DisplayName>
    <ID>34455</ID>
  </Initiator>
  <Owner>
    <DisplayName>username</DisplayName>
    <ID>34455</ID>
  </Owner>
  <PartNumberMarker>1</PartNumberMarker>
  <NextPartNumberMarker>3</NextPartNumberMarker>
  <MaxParts>2</MaxParts>
  <IsTruncated>true</IsTruncated>
  <Part>
    <PartNumber>2</PartNumber>
    <LastModified>2019-08-1T17:06:06.000Z</LastModified>
    <ETag>"7778aef83f66abc1fa1e8477f296d394"</ETag>
    <Size>10485760</Size>
  </Part>
  <Part>
    <PartNumber>3</PartNumber>
    <LastModified>2019-08-1T17:06:23.000Z</LastModified>
    <ETag>"aaaa18db4cc2f85cedef654fccc4a4x8"</ETag>
    <Size>10485760</Size>
  </Part>
</ListPartsResult>

    Complete Multipart Upload

    完成分段上传，合并分段

    请求语法

    POST /bucketname/ObjectName?uploadId=UploadId HTTP/1.1
Host: ip:port
Date: Date
Content-Length: Size
Authorization: authorization string

<CompleteMultipartUpload>
  <Part>
    <PartNumber>PartNumber</PartNumber>
    <ETag>ETag</ETag>
  </Part>
  ...
</CompleteMultipartUpload>

    请求元素

    元素 说明
    CompleteMultipartUpload 包含所有要合并的的分段信息
    Part 一个分段
    PartNumber 分段编码
    ETag 分段的 ETag

    结果解析

    响应消息体中包含 XML 形式的合并结果，包含合并后对象的 ETag。

    元素 说明
    CompleteMultipartUploadResult 合并分段结果
    Location 合并后对象的地址
    Bucket 存储桶名称
    Key 对象名称
    ETag 合并后对象的 ETag，不一定是合并后完整对象的 MD5 值

    示例

    完成分段上传，合并分段

    POST /bucketname/ObjectName?uploadId=56778 HTTP/1.1
Host: ip:port
Date: Sat, 17 Aug 2019 18:10:30 GMT
Content-Length: 391
Authorization: authorization string

<CompleteMultipartUpload>
  <Part>
    <PartNumber>1</PartNumber>
    <ETag>"a54357aff0632cce46d942af68356b38"</ETag>
  </Part>
  <Part>
    <PartNumber>2</PartNumber>
    <ETag>"0c78aef83f66abc1fa1e8477f296d394"</ETag>
  </Part>
  <Part>
    <PartNumber>3</PartNumber>
    <ETag>"acbd18db4cc2f85cedef654fccc4a4d8"</ETag>
  </Part>
</CompleteMultipartUpload>

    响应结果如下：

    HTTP/1.1 200 OK
Date: Sat, 17 Aug 2019 18:10:30 GMT

<CompleteMultipartUploadResult>
  <Location>http://ip:port/bucketname/ObjectName</Location>
  <Bucket>bucketname</Bucket>
  <Key>ObjectName</Key>
  <ETag>"3858f62230ac3c915f300c664312c11f-9"</ETag>
</CompleteMultipartUploadResult>

    Abort Multipart Upload

    取消分段上传

    请求语法

    DELETE /bucketname/ObjectName?uploadId=UploadId HTTP/1.1
Host: ip:port
Date: Date
Authorization: authorization string

    请求参数

    参数名 说明
    uploadId 待取消的 upload ID

    示例

    取消分段上传响应结果如下：

    HTTP/1.1 204 OK
Date: Sat, 17 Aug 2019 18:15:30 GMT
Content-Length: 0

    区域API

    下述将介绍区域相关的接口。

    Create Region

    增加一个区域或更新区域配置

    Note:

    用户创建区域时可对区域内数据存储位置进行配置，即指定集合空间的生成方式，生成方式分为指定模式和自动创建模式。不能够同时指定两种模式，更新区域配置是也不能修改模式，更新区域配置只能够修改自动创建模式下的集合空间生成规则。

    请求语法

    POST /region/?Action=CreateRegion&RegionName={regionname} HTTP/1.1
Host: ip:port
Content-Length: length
Date: date
Authorization: authorization string

<RegionConfiguration>
  <DataCSShardingType>year</DataCSShardingType>
  <DataCLShardingType>month</DataCLShardingType>
  <DataDomain>domain1</DataDomain>
  <MetaDomain>domain2</MetaDomain>
</RegionConfiguration>

    参数说明

    参数名 说明
    Action 固定为 CreateRegion，表示该操作为创建一个区域
    RegionName 指定区域名称

    请求元素

    用户可以在请求消息体中使用 XML 形式指定区域的配置。

    元素 说明
    RegionConfiguration 包含区域配置内容
    DataCSShardingType 对象数据集合空间的生成规则，按照设定的时间生成指定的集合空间，类型为 string，默认值为"year"，有效值包括"year"、"quarter"和"month"
    DataCLShardingType 对象数据集合的生成规则，按照设定的时间生成指定的集合，类型为 string，默认值为"quarter"，有效值包括"year"、"quarter"和"month"
    DataCSRange 对象数据集合的生成规则，在设定时间段内能够生成的集合空间数量，类型为 int32
    DataDomain 对象数据集合空间所属域，类型为 string，域必须已在 SequoiaDB 中定义，如果不填写域名称，则对象数据集合空间建立在系统域上
    DataLobPageSize 对象数据集合空间的 LobPageSize，默认值为 262144，有效值包括 0、4096、8192、16384、32768、65536、131072、262144、524288 之一，0 表示选择默认值
    DataReplSize 对象集合的ReplSize，写操作同步的副本数，默认值为 -1，有效值包括 -1、0、1~7
    MetaDomain 元数据集合空间所属域，类型为 string，域必须已在 SequoiaDB 中定义，若不填写则元数据集合空间建在系统域上
    DataLocation 指定模式为对象数据的集合空间.集合名称，类型为 string，如 CS.CL
    MetaLocation 指定模式为元数据的集合空间.集合名称，类型为 string，如 CS.CL
    MetaHisLocation 指定模式为历史元数据的集合空间.集合名称，类型 string，如 CS.CL

    示例

    创建区域的请求，指定对象数据集合空间和元数据集合空间的域，指定对象数据集合空间和对象数据集合的生成规则

    POST /region/?Action=CreateRegion&RegionName=region1 HTTP/1.1
Host: ip:port
Content-Length: length
Date: date
Authorization: authorization string

<RegionConfiguration>
  <DataCSShardingType>year</DataCSShardingType>
  <DataCLShardingType>month</DataCLShardingType>
  <DataDomain>domain1</DataDomain>
  <MetaDomain>domain2</MetaDomain>
</RegionConfiguration>

    响应结果如下：

    HTTP/1.1 200 OK
Date: date
Content-Length: 0

    GetRegion

    获取一个区域的配置

    请求语法

    POST /region/?Action=GetRegion&RegionName={regionname} HTTP/1.1 
Host: ip:port
Date: date 
Authorization: authorization string

    参数说明

    参数名 说明
    Action 固定为 GetRegion，表示该操作为删除一个区域
    RegionName 指定区域名称

    示例

    查询一个区域的配置信息

    POST /region/?Action=GetRegion&RegionName=region1 HTTP/1.1
Host: ip:port
Date: Wed, 12 Oct 2009 17:50:00 GMT
Authorization: authorization string

    响应结果如下：

    <RegionConfiguration>
  <Name>region1</Name>
  <DataCSShardingType>year</DataCSShardingType>
  <DataCLShardingType>month</DataCLShardingType>
  <DataCSRange>1</DataCSRange>
  <DataDomain>domain1</DataDomain>
  <MetaDomain>domain2</MetaDomain>
  <DataLobPageSize>262144</DataLobPageSize>
  <DataReplSize>-1</DataReplSize>
  <DataLocation/>
  <MetaLocation/>
  <MetaHisLocation/>
  <Buckets>
    <Bucket>bucketname1</Bucket>
    <Bucket>bucketname2</Bucket>
  </Buckets>
</RegionConfiguration>

    DeleteRegion

    删除一个区域

    请求语法

    POST /region/?Action=DeleteRegion&RegionName={regionname} HTTP/1.1
Host: ip:port
Date: date 
Authorization: authorization string

    参数说明

    参数名 说明
    Action 固定为 DeleteRegion，表示该操作为删除一个区域
    RegionName 指定区域名称

    示例

    删除一个区域的请求

    POST /region/?Action=DeleteRegion&RegionName=region1 HTTP/1.1
Host: ip:port
Date: date 
Authorization: authorization string

    响应结果如下：

    HTTP/1.1 204 No Content 
Date: date

    ListRegions

    查询区域列表，可以查询当前系统中所有区域名称

    请求语法

    POST /region/?Action=ListRegions HTTP/1.1 
Host: ip:port
Date: date 
Authorization: authorization string

    参数说明

    参数名 说明
    Action 固定为 ListRegions，表示该操作为查询区域列表

    结果解析

    查询结果以 XML 形式在响应消息头中显示。

    元素 说明
    ListAllRegionsResult 包含一个到多个 Region
    Region 区域名称

    示例

    查询区域列表的响应结果如下：

    <ListAllRegionsResult>
  <Region>region1</Region>
  <Region>region1</Region>
  <Region>region1</Region>
</ListAllRegionsResult>

    HeadRegion

    查询区域是否存在

    请求语法

    POST /region/?Action=HeadRegion&RegionName={regionname} HTTP/1.1
Host: ip:port
Date: date 
Authorization: authorization string

    示例

    响应结果如下：

    HTTP/1.1 200 OK
Date: date

    用户API

    下述将介绍用户相关的接口。

    Create User

    创建用户

    Note:

    该操作需管理员用户权限，系统默认生成一个管理员用户，可用该用户创建其他用户。

    请求语法

    POST /users/?Action=CreateUser&UserName=username&Role=admin HTTP/1.1 
Host: ip:port
Date: date 
Authorization: authorization string

    参数说明

    参数名 说明
    Action 固定为 CreateUser，表示该操作为创建一个用户
    UserName 指定用户名称
    Role 指定用户的角色，可选管理员 admin 用户或普通 normal 用户，管理员用户可以管理用户也可以使用 S3 业务，普通用户可以使用 S3 业务但不能管理用户

    结果解析

    创建用户成功后，会收到 AccessKeys，AccessKeys 用于访问 SequoiaS3 系统的用户验证。

    元素 说明
    AccessKeys 包含用户 Key 值
    AccessKeyID 用户的 Access Key ID，代表用户身份
    SecretAccessKey 新用户的 Secret Access Key 类似密码，用于计算签名，和 Access Key ID 一起在请求消息中携带，用来验证用户身份

    示例

    创建用户后，响应结果如下：

    HTTP/1.1 200 OK
Date: Wed, 01 Mar  2006 12:00:00 GMT

<AccessKeys>
  <AccessKeyID>AKIAIC6UQBTBIW7THT5A</AccessKeyID>
  <SecretAccessKey>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</SecretAccessKey>
</AccessKeys>

    Create AccessKey

    更新用户的访问密钥

    Note:

    该操作需要管理员用户权限。生成新的密钥之后，旧密钥失效。

    请求语法

    POST /users/?Action=CreateAccessKey&UserName=username HTTP/1.1 
Host: ip:port
Date: date 
Authorization: authorization string

    参数说明

    参数名 说明
    Action 固定为 CreateAccessKey，表示该操作为更新 AccessKeys
    UserName 指定用户名称

    示例

    更新密钥后，响应结果如下：

    HTTP/1.1 200 OK
Date: Wed, 01 Mar  2006 12:00:00 GMT

<AccessKeys>
  <AccessKeyID>AKIAIC6UQBCDGW7TH35T</AccessKeyID>
  <SecretAccessKey>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</SecretAccessKey>
</AccessKeys>

    Delete User

    删除一个用户

    Note:

    • 该操作需要管理员用户权限。
    • 当该用户还有桶未清理时，不允许删除用户。
    • 当请求携带了 Force 标识时，可以强制删除未清理桶的用户，并将该用户拥有的桶以及桶内对象全部清理。

    请求语法

    POST /users/?Action=DeleteUser&UserName=username HTTP/1.1 
Host: ip:port
Date: date 
Authorization: authorization string

    参数说明

    参数名 说明
    Action 固定为 DeleteUser，表示该操作为删除用户
    UserName 指定用户名称
    Force 强制删除标记，当请求携带 Force 参数且值为 true 时删除用户，并清理该用户拥有的桶及桶内对象

    示例

    • 删除用户

      POST /users/?Action=DeleteUser&UserName=user1 HTTP/1.1 
Host: ip:port
Date: date 
Authorization: authorization string

      响应结果如下：

      HTTP/1.1 200 OK
Date: date

    • 强制删除用户

      POST/users/?Action=DeleteUser&UserName=username&Force=true HTTP/1.1 
Host: ip:port
Date: date 
Authorization: authorization string

      响应结果如下：

      HTTP/1.1 200 OK
Date: date

    Get AccessKey

    获取用户的访问密钥

    Note:

    该操作需要管理员用户权限。

    请求语法

    POST /users/?Action=GetAccessKey&UserName=username HTTP/1.1 
Host: ip:port
Date: date 
Authorization: authorization string

    参数说明

    参数名 说明
    Action 固定为 GetAccessKey，表示该操作为获取用户的访问密钥
    UserName 指定用户名称

    示例

    获取 user1 的访问密钥请求

    POST /users/?Action=GetAccessKey&UserName=user1 HTTP/1.1 
Host: ip:port
Date: date 
Authorization: authorization string

    响应结果如下：

    HTTP/1.1 200 OK
Date: date

<AccessKeys>
  <AccessKeyID>AKIAIC6UQBTBIW7THT5A</AccessKeyID>
  <SecretAccessKey>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</SecretAccessKey>
</AccessKeys>
    收起
    建议反馈
    本页导航
    粤ICP备16118040号
    回到顶部