全部產品
Search

搜尋本產品

    Object Storage Service：ListObjectVersions（GetBucketVersions）

    文件中心

    Object Storage Service：ListObjectVersions（GetBucketVersions）

    更新時間：Jun 19, 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)介面時，可通過設定prefix、key-marker、version-id-marker、delimiter和max-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的設定無法一次完成列舉，返回結果會附加NextKeyMarker和NextVersionIdMarker作為下一次列舉的marker。列舉結果中包含NextKeyMarker和NextVersionIdMarker的值。

    取值：大於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最後被修改的時間。

    父節點：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-id、Content-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>
    </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.txt、exampleobject2.txt和exampleobject3.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參數的長度不符合要求。