ListObjectVersions(GetBucketVersions)介面用於列出Bucket中包括刪除標記(Delete Marker)在內的所有Object的版本資訊。
注意事項
調用ListObjectVersions(GetBucketVersions)介面返回Bucket中所有Object的所有版本。而調用ListObjects(GetBucket)介面僅返回Object的目前的版本,且目前的版本不能為刪除標記。
調用ListObjectVersions(GetBucketVersions)介面時不同Object之間按字母排序返回,同一個Object的不同版本則按從新到舊排序,與版本ID的字母序無關。
調用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的設定無法一次完成列舉,返回結果會附加 取值:大於0小於1000 預設值:100 |
prefix | 字串 | 否 | fun | 限定返回的Object 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 父節點: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的內容。
說明 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 |
TransitionTime | 時間 | 2024-04-23T07:21:42.000Z | Object通過生命週期規則轉儲為冷歸檔或者深度冷Archive Storage類型的時間。 說明
父節點:ListVersionsResult.Version、ListVersionsResult.DeleteMarker |
VersionId | 字串 | CAEQMxiBgMDNoP2D0BYiIDE3MWUxNzgxZDQxNTRiODI5OGYwZGMwNGY3MzZjN**** | Object的版本ID。 父節點:ListVersionsResult.Version、 ListVersionsResult.DeleteMarker |
IsLatest | 字串 | true | 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的解凍狀態。
|
此介面涉及的其他公用回應標頭,例如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> <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.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擁有者以及被授予 |
InvalidArgument | 400 |
|