全部產品
Search
文件中心

Object Storage Service:ListObjectVersions(GetBucketVersions)

更新時間:Oct 23, 2024

ListObjectVersions(GetBucketVersions)介面用於列出Bucket中包括刪除標記(Delete Marker)在內的所有Object的版本資訊。

注意事項

  • 調用ListObjectVersions(GetBucketVersions)介面返回Bucket中所有Object的所有版本。而調用ListObjects(GetBucket)介面僅返回Object的目前的版本,且目前的版本不能為刪除標記。

  • 調用ListObjectVersions(GetBucketVersions)介面時不同Object之間按字母排序返回,同一個Object的不同版本則按從新到舊排序,與版本ID的字母序無關。

  • 如果您開啟了日誌轉存以及即時日誌查詢,則調用該介面產生的訪問日誌中對應的operation欄位為GetBucket。

  • 調用ListObjectVersions(GetBucketVersions)介面按照Put類請求次數計費。更多資訊,請參見Put類請求

請求文法

GET /?versions HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue

要求標頭

此介面僅涉及公用要求標頭。更多資訊,請參見公用要求標頭(Common Request Headers)

請求參數

調用GetBucketVersions(ListObjectVersions)介面時,可通過設定prefixkey-markerversion-id-markerdelimitermax-keys參數限制僅返回部分結果。

名稱

類型

是否必選

樣本值

描述

delimiter

字串

/

對Object名字進行分組的字元。所有Object名字包含指定的首碼(prefix),第一次出現delimiter字元之間的Object作為一組元素(即CommonPrefixes)。

如果將prefix設為檔案夾名稱後,再把delimiter設定為正斜線(/),則只返回該檔案夾下的檔案,該檔案夾下的子檔案名稱在CommonPrefixes中返回,子檔案夾下遞迴的檔案和檔案夾不顯示。

預設值:無

key-marker

字串

如果version-id-marker不為空白,則key-marker不可為空

example

設定結果從key-marker之後按字母序開始返回,與version-id-marker組合使用。

參數的長度必須小於1024位元組。

預設值:無

version-id-marker

字串

CAEQMxiBgICbof2D0BYiIGRhZjgwMzJiMjA3MjQ0ODE5MWYxZDYwMzJlZjU1****

設定結果從key-marker對象的version-id-marker之後按新舊版本排序開始返回。如果version-id-marker未設定,則預設從key-marker按字母序排序的下一個Key的第一個版本開始返回。

預設值:無

有效值:版本ID

max-keys

字串

100

限定此次返回Object的最大個數。

如果因為max-keys的設定無法一次完成列舉,返回結果會附加NextKeyMarkerNextVersionIdMarker作為下一次列舉的marker。列舉結果中包含NextKeyMarkerNextVersionIdMarker的值。

取值:大於0小於1000

預設值:100

prefix

字串

fun

限定返回的Object Key必須以prefix作為首碼。

  • prefix的長度必須小於1024位元組。

  • 使用prefix查詢時,返回結果的Key仍會包含prefix。

如果將prefix設為某個檔案夾名,則列舉以此prefix開頭的檔案,即該檔案夾下遞迴的所有的檔案和子檔案夾。

預設值:無

encoding-type

字串

URL

對返回的內容進行編碼並指定編碼類別型。

預設值:無

可選值:URL

重要

delimiter、marker、prefix、NextMarker以及Key使用UTF-8字元。如果delimiter、marker、prefix、NextMarker以及Key中包含XML 1.0標準不支援的控制字元,您可以通過指定encoding-type對返回結果中的Delimiter、Marker、Prefix、NextMarker以及Key進行編碼。

響應元素

名稱

類型

樣本值

描述

ListVersionsResult

容器

不涉及

儲存ListObjectVersions(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

字串

URL

指明返回結果中編碼使用的類型。如果請求的參數中指定了encoding-type,則表示對返回結果中的Delimiter、Marker、Prefix、NextMarker和Key這些元素進行編碼。

父節點:ListVersionsResult

IsTruncated

字串

true

指明是否已返回所有結果。

  • true:表示本次沒有返回全部結果。

  • false:表示本次已返回全部結果。

有效值:true、false

父節點:ListVersionsResult

KeyMarker

字串

example

標識此次GetBucketVersions的起點Object。

父節點:ListVersionsResult

VersionIdMarker

字串

CAEQMxiBgICbof2D0BYiIGRhZjgwMzJiMjA3MjQ0ODE5MWYxZDYwMzJlZjU1****

與KeyMarker參數一同使用,以指定ListObjectVersions(GetBucketVersions)的起點。

父節點:ListVersionsResult

NextKeyMarker

字串

test

如果本次沒有返回全部結果,響應請求中將包含NextKeyMarker元素,用於標明接下來請求的key-marker。

父節點:ListVersionsResult

NextVersionIdMarker

字串

CAEQGBiBgIC_jq7P9xYiIDRiZWJkNjY2Y2Q4NDQ5ZTI5ZGE5ODIxMTIyZThl****

如果本次沒有返回全部結果,響應請求中將包含NextVersionIdMarker元素,用於標明接下來請求的version-id-marker。

父節點:ListVersionsResult

MaxKeys

字串

1000

響應請求內返回結果的最大數目。

父節點:ListVersionsResult

Name

字串

examplebucket-1250000000

Bucket名稱。

父節點:ListVersionsResult

Owner

容器

不涉及

儲存Bucket擁有者資訊的容器。

父節點:ListVersionsResult

Prefix

字串

fun

本次查詢結果的首碼。

父節點:ListVersionsResult

Version

容器

不涉及

儲存除刪除標記以外的Object版本的容器。

父節點:ListVersionsResult

DeleteMarker

容器

不涉及

儲存刪除標記的容器。

父節點:ListVersionsResult

ETag

字串

250F8A0AE989679A22926A875F0A2****

每個Object產生時建立的ETag ,用於標識Object的內容。

  • 對於PutObject請求建立的Object,ETag值是其內容的MD5值。

  • 對於其他方式建立的Object,ETag值是基於一定計算規則產生的唯一值,但不是其內容的MD5值。

說明

ETag值僅用於檢查Object內容是否發生變化。不建議使用ETag值作為Object內容的MD5資料完整性校正的依據。

父節點:ListVersionsResult.Version

Key

字串

example

Object的名稱。

父節點:ListVersionsResult.Version、ListVersionsResult.DeleteMarker

LastModified

時間

2019-04-09T07:27:28.000Z

Object最後被修改的時間。

說明
  • 低頻訪問類型最低儲存時間(30天)以Object儲存在OSS的Last Modified時間開始計算。如果擷取到Object的Last-Modified時間距離目前時間超過30天,則提前刪除Object不會產生低頻儲存不足規定時間長度費用。

  • 歸檔類型最低儲存時間(60天)以Object儲存在OSS的Last Modified時間開始計算。如果擷取到Object的Last-Modified時間距離目前時間超過60天,則提前刪除Object不會產生Archive Storage不足規定時間長度費用。

父節點:ListVersionsResult.Version、ListVersionsResult.DeleteMarker

TransitionTime

時間

2024-04-23T07:21:42.000Z

Object通過生命週期規則轉儲為冷歸檔或者深度冷Archive Storage類型的時間。

說明
  • 如果擷取的轉儲時間距離目前時間超過180天,則提前刪除冷歸檔或者深度冷歸檔Object不會產生儲存不足規定時間長度費用。如果轉儲時間距離目前時間不超過180天,則提前刪除冷歸檔或者深度冷歸檔Object會產生儲存不足規定時間長度費用。

  • 不支援通過該欄位統計Object通過生命週期規則轉儲為低頻或者Archive Storage類型的時間。判斷低頻或者Archive Storage類型是否滿足最低儲存時間長度的要求取決於Last-Modified時間。

父節點:ListVersionsResult.Version、ListVersionsResult.DeleteMarker

VersionId

字串

CAEQMxiBgMDNoP2D0BYiIDE3MWUxNzgxZDQxNTRiODI5OGYwZGMwNGY3MzZjN****

Object的版本ID。

父節點:ListVersionsResult.Version、 ListVersionsResult.DeleteMarker

IsLatest

字串

true

Object是否為目前的版本。

取值:

  • true:Object為目前的版本。

  • false:Object為非目前的版本。

父節點:ListVersionsResult.Version、 ListVersionsResult.DeleteMarker

Size

字串

93731

Object的位元組數。

父節點:ListVersionsResult.Version、ListVersionsResult.DeleteMarker

StorageClass

字串

Standard

Object的儲存類型。

父節點:ListVersionsResult.Version、ListVersionsResult.DeleteMarker

DisplayName

字串

12345125285864390

Object擁有者的名稱。

父節點:ListVersionsResult.Version.Owner、ListVersionsResult.DeleteMarker.Owner

ID

字串

1234512528586****

Bucket擁有者的使用者ID。

父節點:ListVersionsResult.Version.Owner、ListVersionsResult.DeleteMarker.Owner

RestoreInfo

字串

ongoing-request="true"

Object的解凍狀態。

  • 如果沒有提交RestoreObject請求或者RestoreObject請求已到期,則不返回該欄位。

  • 如果已經提交RestoreObject請求,但解凍操作未完成,則返回的RestoreInfo值為ongoing-request="true"

  • 如果已經提交RestoreObject請求,且解凍操作已完成,則返回的RestoreInfo值為ongoing-request="false”, expiry-date="Thu, 24 Sep 2020 12:40:33 GMT"。其中,expiry-date欄位表示解凍完成後Object進入可讀狀態的到期時間。

此介面涉及的其他公用回應標頭,例如x-oss-request-idContent-Type等。更多資訊,請參見公用回應標頭(Common Response Headers)

樣本

  • 未啟用版本控制

    請求樣本

    GET /?versions HTTP/1.1
    Host: oss-example.oss-cn-hangzhou.aliyuncs.com
    Date: Tue, 09 Apr 2019 07:27:48 GMT
    Authorization: OSS qn6q**************:77Dv****************

    返回樣本

    HTTP/1.1 200 OK
    Content-Type: application/xml
    Content-Length: 1262
    Connection: keep-alive
    Date: Thu, Tue, 09 Apr 2019 07:27:48 GMT
    Server: AliyunOSS
    x-oss-request-id: 534B371674E88A4D8906****
    
    <ListVersionsResult>
        <Name>examplebucket-1250000000</Name>
        <Prefix/>
        <KeyMarker/>
        <VersionIdMarker/>
        <MaxKeys>1000</MaxKeys>
        <IsTruncated>false</IsTruncated>
        <Version>
            <Key>example-object-1.jpg</Key>
            <VersionId/>
            <IsLatest>true</IsLatest>
            <LastModified>2019-08-5T12:03:10.000Z</LastModified>    
            <ETag>5B3C1A2E053D763E1B669CC607C5A0FE1****</ETag>
            <Size>20</Size>
            <StorageClass>STANDARD</StorageClass>
            <Owner>
                <ID>1250000000</ID>
                <DisplayName>1250000000</DisplayName>
            </Owner>
            <TransitionTime>2024-04-23T07:21:42.000Z</TransitionTime>
        </Version>
        <Version>
            <Key>example-object-2.jpg</Key>
            <VersionId/>
            <IsLatest>true</IsLatest>
            <LastModified>2019-08-9T12:03:09.000Z</LastModified>
            <ETag>5B3C1A2E053D763E1B002CC607C5A0FE1****</ETag>
            <Size>20</Size>
            <StorageClass>STANDARD</StorageClass>
            <Owner>
                <ID>1250000000</ID>
                <DisplayName>1250000000</DisplayName>
            </Owner>
        </Version>
        <Version>
            <Key>example-object-3.jpg</Key>
            <VersionId/>
            <IsLatest>true</IsLatest>
            <LastModified>2019-08-10T12:03:08.000Z</LastModified>
            <ETag>4B3F1A2E053D763E1B002CC607C5AGTRF****</ETag>
            <Size>20</Size>
            <StorageClass>STANDARD</StorageClass>
            <Owner>
                <ID>1250000000</ID>
                <DisplayName>1250000000</DisplayName>
            </Owner>
        </Version>
    </ListVersionsResult>
  • 已開啟版本控制

    假設在名為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=CAEQMxiBgICbof2D0BYiIGRhZjgwMzJiMjA3MjQ0ODE5MWYxZDYwMzJlZjU1**** HTTP/1.1
    Host: oss-example.oss-cn-hangzhou.aliyuncs.com
    Date: Tue, 09 Apr 2019 07:27:48 GMT
    Authorization: OSS qn6q**************:77Dv****************

    返回樣本:

    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>
  • 請求的Bucket包含歸檔或冷歸檔類型檔案

    假設examplebucket中包含檔案exampleobject1.txtexampleobject2.txtexampleobject3.txt,其儲存類型均為冷Archive Storage類型(ColdArchive)。這三個檔案所處的狀態說明如下:

    • exampleobject1.txt未提交RestoreObject請求或者RestoreObject請求已到期。

    • exampleobject2.txt已提交RestoreObject請求,但解凍操作未完成。

    • exampleobject3.txt已提交RestoreObject請求,並且解凍操作已完成。

    請求樣本

    GET / HTTP/1.1
    Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
    Date: Fri, 24 Feb 2012 08:43:27 GMT
    Authorization: OSS qn6q**************:77Dv****************

    返回樣本

    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>
        <Version>
            <Key>exampleobject1.txt</Key>
            <VersionId>CAEQMxiBgICAof2D0BYiIDJhMGE3N2M1YTI1NDQzOGY5NTkyNTI3MGYyMzJm****</VersionId>
            <IsLatest>false</IsLatest>
            <LastModified>2019-04-09T07:27:28.000Z</LastModified>
            <Owner>
              <ID>1234512528586****</ID>
              <DisplayName>12345125285864390</DisplayName>
            </Owner>
         </Version>
        <Version>
            <Key>exampleobject2.txt</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>
            <RestoreInfo>ongoing-request="true"</RestoreInfo>
            <Owner>
              <ID>1234512528586****</ID>
              <DisplayName>12345125285864390</DisplayName>
            </Owner>
         </Version>
        <Version>
            <Key>exampleobject3.txt</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>
            <RestoreInfo>ongoing-request="false", expiry-date="Thr, 24 Mon 2020 12:40:33 GMT"</RestoreInfo>
            <Owner>
              <ID>1234512528586****</ID>
              <DisplayName>12345125285864390</DisplayName>
            </Owner>
         </Version>
    </ListVersionsResult>

SDK

此介面所對應的各語言SDK如下:

錯誤碼

錯誤碼

HTTP狀態代碼

描述

NoSuchBucket

404

請求的目標Bucket不存在。請檢查請求的Bucket名稱是否符合規範。

AccessDenied

403

沒有訪問該Bucket的許可權。只有Bucket擁有者以及被授予oss:ListObjectVersions許可權的使用者可以訪問該Bucket。

InvalidArgument

400

  • max-keys小於0或者大於1000。

  • prefix、marker、delimiter參數的長度不符合要求。