GetBucketVersions接口用于列出 Bucket 中包括删除标记(Delete Marker)在内的所有 Object 的版本信息。

说明 对于一个开启过版本控制的 Bucket,GetBucket(ListObjects)接口仅返回 Object 的当前版本,且当前版本不能为删除标记。当您需要列举 Bucket 中所有 Object 的所有版本时,需使用GetBucketVersions接口。

请求参数

调用GetBucketVersions接口时,可以通过PrefixKey-markerVersion-id-markerDelimiterMax-keys对 list 做限定,返回部分结果。
名称 类型 是否必需 描述
Delimiter 字符串

对Object名字进行分组的字符。所有Object名字包含指定的前缀(Prefix),第一次出现Delimiter字符之间的Object作为一组元素(即CommonPrefixes)。

默认值:无

Key-marker 字符串 如果version-id-marker不为空,则key-marker不能为空

设定结果从 Key-marker 之后按字母序开始返回,与 Version-id-marker 组合使用。参数的长度必须小于1024 字节。

默认值:无

Version-id-marker 字符串 设定结果从 Key-marker 对象的 Version-id-marker 之后按新旧版本排序开始返回,该版本不会在返回的结果当中。如果 Version-id-marker 未设定,则默认从 Key-marker 按字母序排序的下一个 Key 的第一个版本开始返回。

默认值:无

有效值:有效的版本 ID

Max-keys 字符串

限定此次返回 Object 的最大数。

取值:大于 0 小于 1000

默认值:100

说明 如果因为 Max-keys 的设定无法一次完成列举,返回结果会附加 <NextKeyMarker> 和 <NextVersionIdMarker> 作为下一次列举的 Marker。
Prefix 字符串

限定返回的 Object Key 必须以 Prefix 作为前缀。

默认值:无

说明
  • 参数的长度必须小于 1024 字节。
  • 使用 Prefix 查询时,返回结果的 Key 中仍会包含 Prefix。
Encoding-type 字符串

指定对返回的内容进行编码,并指定编码的类型。

默认值:无

可选值:url

说明 Delimiter、Key-Marker、Prefix、NextKeyMarker 以及 Key 需使用 UTF-8 字符。如果Delimiter、Key-Marker、Prefix、NextKeyMarker 以及 Key 中包含 XML 1.0 标准不支持的控制字符时,您可以通过指定 Encoding-type 对返回结果中的 Delimiter、Key-Marker、Prefix、NextKeyMarker 以及 Key 进行编码。

响应元素

名称 类型 描述
ListVersionsResult 容器

保存 GetBucketVersions 请求结果的容器。

子节点:Name、Prefix、Marker、MaxKeys、Delimiter、IsTruncated、Nextmarker、Version、DeleteMarker

父节点:None

CommonPrefixes 字符串

如果请求中指定了 Delimiter 参数,则 OSS 返回的响应中包含 CommonPrefixes 元素。该元素标明以 delimiter 结尾,并有共同前缀的 Object 名称的集合。

父节点:ListVersionsResult

Delimiter 字符串

用于对 Object 名字进行分组的字符。所有名字包含指定的前缀且第一次出现 Delimiter 字符之间的 Object 作为一组元素 CommonPrefixes。

父节点:ListVersionsResult

EncodingType 字符串

指明返回结果中编码使用的类型。如果请求的参数中指定了EncodingType,则表示对返回结果中的 Delimiter、Marker、Prefix、NextMarker 和 Key 这些元素进行编码。

父节点:ListVersionsResult

IsTruncated 字符串
指明是否已返回所有结果。
  • true:表示本次没有返回全部结果。
  • false:表示本次已返回全部结果。

有效值:true、false

父节点:ListVersionsResult

KeyMarker 字符串

表明这次 GetBucketVersions 的起点Object。

父节点:ListVersionsResult

VersionIdMarker 字符串

与 KeyMarker 参数一同使用来指定 GetBucketVersions 的起点 Version。

父节点:ListVersionsResult

NextKeyMarker 字符串

如果本次没有返回全部结果,响应请求中将包含 NextUploadMarker 元素,用于标明接下来请求的 Key-marker。

父节点:ListVersionsResult

NextVersionIdMarker 字符串

如果本次没有返回全部结果,响应请求中将包含 NextUploadMarker 元素,用于标明接下来请求的 Version-id-marker。

父节点:ListVersionsResult

MaxKeys 字符串

响应请求内返回结果的最大数目。

父节点:ListVersionsResult

Name 字符串

Bucket 名字。

父节点:ListVersionsResult

Owner 容器

保存 Bucket 拥有者信息的容器。

父节点:ListVersionsResult

Prefix 字符串

本次查询结果的前缀。

父节点:ListVersionsResult

Version 容器

保存除“删除标记”外的 Object 版本的容器。

父节点:ListVersionsResult

DeleteMarker 容器

保存 Object 为 “删除标记” 的容器。

父节点:ListVersionsResult

ETag 字符串 每个 Object 生成的时创建的 ETag (entity tag) ,用于标明 Object 的内容。
  • 对于 PutObject 请求创建的 Object,ETag 值是其内容的 MD5 值。
  • 对于其他方式创建的 Object,ETag 值是其内容的 UUID。
说明 ETag 值可以用于检查Object 内容是否发生变化。不建议使用 ETag 值作为 Object 内容的 MD5 数据完整性校验的依据。

父节点:ListVersionsResult.Version

Key 字符串

Object 的 Key。

父节点:ListVersionsResult.Version | ListVersionsResult.DeleteMarker

LastModified 时间

Object 最后被修改的时间。

父节点:ListVersionsResult.Version | ListVersionsResult.DeleteMarker

VersionId 字符串

对象的版本 ID。

父节点:ListVersionsResult.Version | ListVersionsResult.DeleteMarker

IsLatest 字符串

是否为当前版本,如果是当前版本则为 true,否则为 false。

父节点:ListVersionsResult.Version | ListVersionsResult.DeleteMarker

Size 字符串

Object 的字节数。

父节点:ListVersionsResult.Version | ListVersionsResult.DeleteMarker

StorageClass 字符串

Object 的存储类型。

父节点:ListVersionsResult.Version | ListVersionsResult.DeleteMarker

DisplayName 字符串

Object 拥有者的名字。

父节点:ListVersionsResult.Version.Owner | ListVersionsResult.DeleteMarker.Owner

ID 字符串

Bucket 拥有者的用户 ID。

父节点:ListVersionsResult.Version.Owner | ListVersionsResult.DeleteMarker.Owner

细节分析

  • 不同 Object 之间按字母排序返回,同一个 Object 的不同版本则按从新到旧排序,与版本 ID 的字母序无关。
  • GetBucketVersions 请求时不会返回 Object 中用户自定义的 meta。
  • 如果因为 max-keys 的设定无法一次完成列举,返回结果会附加 NextKeyMarker 和 NextVersionIdMarker,这两个 Marker 作为下一次列举的 Marker。列举结果中包含 NextKeyMarker 和 NextVersionIdMarker 的值。
  • prefix、marker 用于实现分页显示效果,参数的长度必须小于 1024 字节。
  • 如果将 prefix 设为某个文件夹名,则列举以此 prefix 开头的文件,即该文件夹下递归的所有的文件和子文件夹。

    如果再把 delimiter 设置为正斜线(/)时,返回值则只罗列该文件夹下的文件,该文件夹下的子文件名在 CommonPrefixes 中返回,子文件夹下递归的文件和文件夹不被显示。

    假设某个 Bucket 下有 3个 Object,分别为 fun/test.jpg、 fun/movie/001.avi、fun/movie/007.avi。其中,
    • fun/test.jpg 有新旧两个版本分别为 V111111 和 V222222。
    • fun/movie/001.avi 仅有一个版本为 V121212。
    • fun/movie/007.avi 仅有一个版本为 V212121。

    若设定 Prefix 为 fun/,则返回四个结果 fun/test.jpg(V111111)、fun/test.jpg(V222222)、fun/movie/001.avi(V121212) 和 fun/movie/007.avi(V212121)。如果增加设定 delimiter 为正斜线(/),则返回 fun/test.jpg(V111111)、fun/test.jpg(V222222)和 fun/movie/ 。

示例

假设在名为 oss example 的 Bucket 中有名为 example 和 pic.jpg 的 2 个 Object,其中 example 这个 Object 有 3 个版本,从新到旧排序的版本 ID 依次为 111222、000123(删除标记)、222333 。pic.jpg 这个 Object 仅有 1 个版本,其版本 ID 为 232323 。

列举文件时将 key-marker 设置为 example,version-id-marker 指定为 111222 ,则按 example 000123、example 222333、pic.jpg 232323 的顺序返回 3 个版本。

请求示例
GET /?versions&key-marker=example&version-id-marker=CAEQMxiBgICbof2D0BYiIGRhZjgwMzJiMjA3MjQ0ODE5MWYxZDYwMzJlZjU1YmMy HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Date: Tue, 09 Apr 2019 07:27:48 GMT
Authorization: OSS ami4tq0x76ov9cu:WFx4kLpx+e7Rc0jawCsh7hlk****
返回示例
HTTP/1.1 200 OK
x-oss-request-id: 5CAC4974B7AEADE01700****
Date: Tue, 09 Apr 2019 07:27:48 GMT
Content-Type: application/xml
Connection: keep-alive
Server: AliyunOSS
<?xml version="1.0" encoding="UTF-8"?>
<ListVersionsResult xmlns=”http://doc.oss-cn-hangzhou.aliyuncs.com”>
    <Name>oss-example</Name>
    <Prefix></Prefix>
    <KeyMarker>example</KeyMarker>
    <VersionIdMarker>CAEQMxiBgICbof2D0BYiIGRhZjgwMzJiMjA3MjQ0ODE5MWYxZDYwMzJlZjU1****</VersionIdMarker>
    <MaxKeys>100</MaxKeys>
    <Delimiter></Delimiter>
    <IsTruncated>false</IsTruncated>
    <DeleteMarker>
        <Key>example</Key>
        <VersionId>CAEQMxiBgICAof2D0BYiIDJhMGE3N2M1YTI1NDQzOGY5NTkyNTI3MGYyMzJm****</VersionId>
        <IsLatest>false</IsLatest>
        <LastModified>2019-04-09T07:27:28.000Z</LastModified>
        <Owner>
          <ID>1234512528586****</ID>
          <DisplayName>12345125285864390</DisplayName>
        </Owner>
    </DeleteMarker>
    <Version>
        <Key>example</Key>
        <VersionId>CAEQMxiBgMDNoP2D0BYiIDE3MWUxNzgxZDQxNTRiODI5OGYwZGMwNGY3MzZjN****</VersionId>
        <IsLatest>false</IsLatest>
        <LastModified>2019-04-09T07:27:28.000Z</LastModified>
        <ETag>"250F8A0AE989679A22926A875F0A2****"</ETag>
        <Type>Normal</Type>
        <Size>93731</Size>
        <StorageClass>Standard</StorageClass>
        <Owner>
          <ID>1234512528586****</ID>
          <DisplayName>12345125285864390</DisplayName>
        </Owner>
    </Version>
    <Version>
        <Key>pic.jpg</Key>
        <VersionId>CAEQMxiBgMCZov2D0BYiIDY4MDllOTc2YmY5MjQxMzdiOGI3OTlhNTU0ODIx****</VersionId>
        <IsLatest>true</IsLatest>
        <LastModified>2019-04-09T07:27:28.000Z</LastModified>
        <ETag>"3663F7B0B9D3153F884C821E7CF4****"</ETag>
        <Type>Normal</Type>
        <Size>574768</Size>
        <StorageClass>Standard</StorageClass>
        <Owner>
          <ID>1234512528586****</ID>
          <DisplayName>12345125285864390</DisplayName>
        </Owner>
    </Version>
</ListVersionsResult>

错误码

错误码 HTTP状态码 描述
NoSuchBucket 404 目标 Bucket 不存在,包括试图访问因命名不规范而无法创建的 Bucket。
AccessDenied 403 无访问此 Bucket 的权限。
InvalidArgument 400
  • Max-keys 小于 0 或者大于 1000。
  • Prefix、Marker、Delimiter 参数长度不符合要求。
  • Version-id-marker 为无效的版本ID。