ListObjectVersions - List all object versions and delete markers in an OSS bucket - Object Storage Service

Lista todas las versiones de objetos en un bucket, incluidos los marcadores de eliminación.

Notas de uso

ListObjectVersions (GetBucketVersions) devuelve todas las versiones de objetos, incluidos los marcadores de eliminación. ListObjects (GetBucket) solo devuelve las versiones actuales sin incluir los marcadores de eliminación.
Al llamar a ListObjectVersions (GetBucketVersions), los objetos se devuelven en orden alfabético por nombre. Las versiones del mismo objeto se listan desde la más reciente hasta la más antigua, independientemente del orden alfabético de los ID de versión.
Si logging y real-time log query están habilitados para el bucket, el campo de operación en el registro generado es GetBucket.
Las llamadas a ListObjectVersions (GetBucketVersions) se facturan según el número de solicitudes PUT, como se describe en API operation calling fees.

Sintaxis de la solicitud

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

Encabezados de solicitud

DescribeRegions utiliza únicamente encabezados de solicitud comunes. Para obtener más información, consulte Common request headers.

Parámetros de solicitud

Utilice estos parámetros para filtrar resultados: prefix, key-marker, version-id-marker, delimiter y max-keys.

Parámetro	Tipo	Obligatorio	Ejemplo	Descripción
delimiter	String	No	/	Carácter utilizado para agrupar objetos por nombre. Si se especifican tanto prefix como delimiter, la respuesta contiene CommonPrefixes. Los objetos cuyos nombres comparten la misma cadena desde el prefijo hasta la siguiente aparición del delimitador se agrupan en una sola entrada de CommonPrefixes. Si prefix es un nombre de directorio y delimiter es una barra diagonal (/), solo se devuelven los objetos de ese directorio. Los nombres de subdirectorios aparecen en CommonPrefixes, pero no se listan los objetos ni los directorios dentro de los subdirectorios. Valor predeterminado: vacío.
key-marker	String	Obligatorio si se especifica version-id-marker.	example	Devuelve objetos en orden alfabético posterior a este valor. Se puede usar junto con version-id-marker. Longitud máxima: 1,024 bytes. Valor predeterminado: vacío.
version-id-marker	String	No	CAEQMxiBgICbof2D0BYiIGRhZjgwMzJiMjA3MjQ0ODE5MWYxZDYwMzJlZjU1****	Devuelve versiones creadas antes de este marcador para el objeto especificado por key-marker, en orden descendente por hora de creación. Si se omite, los resultados comienzan desde la versión más reciente del objeto que sigue alfabéticamente a key-marker. Valor predeterminado: vacío. Valores válidos: ID de versión.
max-keys	String	No	100	Número máximo de objetos a devolver. Si los resultados superan max-keys, la respuesta incluye `NextKeyMarker` y `NextVersionIdMarker` como marcadores de paginación para la siguiente solicitud. Valores válidos: 1 a 999. Valor predeterminado: 100.
prefix	String	No	fun	Prefijo que deben contener los nombres de los objetos devueltos. El valor debe tener una longitud menor a 1,024 bytes. Cuando se usa prefix para filtrar resultados, los valores Key en la respuesta aún incluyen el prefijo. Si prefix se establece como un nombre de directorio, se listan todos los objetos y subdirectorios dentro de ese directorio. Valor predeterminado: vacío.
encoding-type	String	No	URL	Tipo de codificación del contenido de la respuesta. Valor predeterminado: vacío. Valores válidos: URL. Importante Los valores de delimiter, marker, prefix, NextMarker y Key tienen codificación UTF-8. Si alguno de estos valores contiene caracteres de control no admitidos por XML 1.0, establezca encoding-type para codificar los valores Delimiter, Marker, Prefix, NextMarker y Key en la respuesta.

Parámetros de respuesta

Parámetro	Tipo	Ejemplo	Descripción
ListVersionsResult	Container	N/A	Contenedor para los resultados de ListObjectVersions (GetBucketVersions). Nodos secundarios: Name, Prefix, Marker, MaxKeys, Delimiter, IsTruncated, NextMarker, Version y DeleteMarker Nodos principales: ninguno
CommonPrefixes	Container	N/A	Si se especifica delimiter, los objetos cuyos nombres comparten la misma cadena desde el prefijo hasta la siguiente aparición del delimitador se agrupan en una sola entrada de CommonPrefixes. Nodos principales: ListVersionsResult
Delimiter	String	/	Carácter utilizado para agrupar objetos por nombre. Los objetos que comparten la misma cadena desde el prefijo hasta la siguiente aparición del delimitador se agrupan en una sola entrada de CommonPrefixes. Nodos principales: ListVersionsResult
EncodingType	String	URL	Tipo de codificación del contenido de la respuesta. Si se especifica encoding-type en la solicitud, se codifican los valores de Delimiter, Marker, Prefix, NextMarker y Key. Nodos principales: ListVersionsResult
IsTruncated	String	true	Indica si los resultados están truncados. true: no se devolvieron todos los resultados. false: se devolvieron todos los resultados. Valores válidos: true y false. Nodos principales: ListVersionsResult
KeyMarker	String	example	Objeto a partir del cual comienza el listado. Nodos principales: ListVersionsResult
VersionIdMarker	String	CAEQMxiBgICbof2D0BYiIGRhZjgwMzJiMjA3MjQ0ODE5MWYxZDYwMzJlZjU1****	Versión desde la cual comienza la operación ListObjectVersions (GetBucketVersions). Se usa junto con KeyMarker. Nodos principales: ListVersionsResult
NextKeyMarker	String	test	Se incluye cuando los resultados están truncados. Úselo como key-marker en la siguiente solicitud para continuar el listado. Nodos principales: ListVersionsResult
NextVersionIdMarker	String	CAEQGBiBgIC_jq7P9xYiIDRiZWJkNjY2Y2Q4NDQ5ZTI5ZGE5ODIxMTIyZThl****	Se incluye cuando los resultados están truncados. Úselo como version-id-marker en la siguiente solicitud para continuar el listado. Nodos principales: ListVersionsResult
MaxKeys	String	1000	Número máximo de objetos devueltos en la respuesta. Nodos principales: ListVersionsResult
Name	String	examplebucket-1250000000	Nombre del bucket. Nodos principales: ListVersionsResult
Prefix	String	fun	Prefijo que debe incluirse en los nombres de los objetos listados. Nodos principales: ListVersionsResult
Version	Container	N/A	Contenedor para versiones de objetos, excluyendo marcadores de eliminación. Nodos principales: ListVersionsResult
DeleteMarker	Container	N/A	Contenedor para marcadores de eliminación. Nodos principales: ListVersionsResult
ETag	String	250F8A0AE989679A22926A875F0A2****	ETag del objeto, utilizado para identificar su contenido. Para objetos creados mediante PutObject, el ETag es el hash MD5 del contenido. Para objetos creados por otros métodos, el ETag es un valor único calculado con una regla diferente, no es el hash MD5. Nota El valor ETag solo indica si el contenido del objeto ha cambiado. No utilice el valor ETag como hash MD5 del contenido del objeto para verificar la integridad de los datos. Nodos principales: ListVersionsResult.Version
Key	String	example	Nombre del objeto. Nodos principales: ListVersionsResult.Version y ListVersionsResult.DeleteMarker
LastModified	Time	2019-04-09T07:27:28.000Z	Hora de la última modificación del objeto. La duración mínima de almacenamiento para objetos en la clase de almacenamiento Infrequent Access es de 30 días. Esta duración se calcula a partir de la hora Last-Modified del objeto. Si elimina un objeto después de 30 días de su hora Last-Modified, no se cobra ninguna tarifa por eliminación anticipada. La duración mínima de almacenamiento para objetos en la clase de almacenamiento Archive es de 60 días. Esta duración se calcula a partir de la hora Last-Modified del objeto. Si elimina un objeto después de 60 días de su hora Last-Modified, no se cobra ninguna tarifa por eliminación anticipada. Nodos principales: ListVersionsResult.Version y ListVersionsResult.DeleteMarker
TransitionTime	Time	2024-04-23T07:21:42.000Z	Hora en que la clase de almacenamiento del objeto cambia a Cold Archive o Deep Cold Archive según las reglas de ciclo de vida. Si elimina un objeto Cold Archive o Deep Cold Archive más de 180 días después de su conversión, no se cobra tarifa por eliminación anticipada. Si lo elimina dentro de los 180 días posteriores a la conversión, se aplica una tarifa por eliminación anticipada. Este campo no sirve para determinar cuándo una regla de ciclo de vida convierte un objeto a la clase IA o Archive. El cumplimiento del requisito de duración mínima de almacenamiento para objetos IA o Archive depende de la hora `Last-Modified`. Nodos principales: ListVersionsResult.Version y ListVersionsResult.DeleteMarker
VersionId	String	CAEQMxiBgMDNoP2D0BYiIDE3MWUxNzgxZDQxNTRiODI5OGYwZGMwNGY3MzZjN****	ID de versión del objeto. Nodos principales: ListVersionsResult.Version y ListVersionsResult.DeleteMarker
IsLatest	String	true	Indica si esta versión es la versión actual. Valores válidos: true: La versión del objeto es la versión actual. false: La versión del objeto no es la versión actual. Nodos principales: ListVersionsResult.Version y ListVersionsResult.DeleteMarker
Size	String	93731	Tamaño del objeto en bytes. Nodos principales: ListVersionsResult.Version y ListVersionsResult.DeleteMarker
StorageClass	String	Standard	Clase de almacenamiento del objeto. Nodos principales: ListVersionsResult.Version y ListVersionsResult.DeleteMarker
Owner	Container	N/A	Contenedor para la información del propietario del bucket. Nodos principales: ListVersionsResult.Version y ListVersionsResult.DeleteMarker
DisplayName	String	12345125285864390	Nombre del propietario del objeto. Nodos principales: ListVersionsResult.Version.Owner y ListVersionsResult.DeleteMarker.Owner
ID	String	1234512528586****	ID de usuario del propietario del bucket. Nodos principales: ListVersionsResult.Version.Owner y ListVersionsResult.DeleteMarker.Owner
RestoreInfo	String	ongoing-request="true"	Estado de restauración del objeto. No se incluye si no se han enviado solicitudes RestoreObject o si estas han caducado. Mientras el objeto se está restaurando, el valor es `ongoing-request="true"`. Una vez restaurado el objeto, el valor tiene el formato `ongoing-request="false", expiry-date="Thu, 24 Sep 2020 12:40:33 GMT"`, donde `expiry-date` indica la fecha límite hasta la cual se puede leer el objeto restaurado.

Para obtener más información sobre los encabezados de respuesta comunes, como x-oss-request-id y Content-Type en la respuesta a una solicitud ListObjectVersions (GetBucketVersions), consulte Common response headers.

Ejemplos

Listar las versiones de objetos en un bucket sin control de versiones

Solicitudes de ejemplo

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****************

Respuesta exitosa de ejemplo

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>

Listar las versiones de objetos en un bucket con control de versiones habilitado

El bucket oss-example contiene dos objetos: example con tres versiones (111222, 000123 como marcador de eliminación y 222333, en orden descendente por hora de creación), y pic.jpg con una versión (232323).

Si establece key-marker en example y version-id-marker en 111222, se devuelven secuencialmente las siguientes tres versiones: 000123 de example, 222333 de example y 232323 de pic.jpg.

Solicitudes de ejemplo

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****************

Respuestas exitosas de ejemplo

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>

Objetos Archive y objetos Cold Archive almacenados en el bucket solicitado

Suponga que el bucket examplebucket contiene los objetos exampleobject1.txt, exampleobject2.txt y exampleobject3.txt. Los tres objetos pertenecen a la clase de almacenamiento Cold Archive. Los estados de los tres objetos son los siguientes:

Para exampleobject1.txt, no se ha enviado ninguna solicitud RestoreObject o la solicitud enviada ha caducado.
Para exampleobject2.txt, se ha enviado una solicitud RestoreObject y la operación de restauración está en curso.
Para exampleobject3.txt, se ha enviado una solicitud RestoreObject y la operación de restauración se completó.

Solicitud de ejemplo

GET / HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 24 Feb 2012 08:43:27 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Respuesta de ejemplo

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 de OSS

Ejecute esta operación con los siguientes SDK de OSS:

Interfaz de línea de comandos ossutil

Para obtener información sobre el comando de ossutil correspondiente a la operación ListObjectVersions, consulte list-object-versions.

Códigos de error

Código de error	Código de estado HTTP	Descripción
NoSuchBucket	404	El bucket no existe. Compruebe que el nombre del bucket cumpla con las convenciones de nomenclatura.
AccessDenied	403	Solo el propietario del bucket o los usuarios de RAM con el permiso `oss:ListObjectVersions` pueden ejecutar esta operación.
InvalidArgument	400	The value of max-keys is less than 0 or greater than 1,000. The length of the prefix, marker, or delimiter parameter is invalid.