ListObjectVersions - List all object versions and delete markers in an OSS bucket - Object Storage Service: Central de Documentação do Alibaba Cloud

Lista todas as versões de objetos em um bucket, incluindo marcadores de exclusão.

Observações de uso

A operação ListObjectVersions (GetBucketVersions) retorna todas as versões de objetos, incluindo marcadores de exclusão. Já a operação ListObjects (GetBucket) retorna apenas as versões atuais, sem incluir marcadores de exclusão.
Ao chamar ListObjectVersions (GetBucketVersions), os objetos são retornados em ordem alfabética por nome. As versões do mesmo objeto aparecem da mais recente para a mais antiga, independentemente da ordem alfabética dos IDs de versão.
Se logging e real-time log query estiverem habilitados para o bucket, o campo de operação no log gerado será GetBucket.
As chamadas para ListObjectVersions (GetBucketVersions) são cobradas com base no número de solicitações PUT, conforme descrito em API operation calling fees.

Sintaxe da solicitação

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

Cabeçalhos da solicitação

DescribeRegions utiliza apenas cabeçalhos de solicitação comuns. Para obter mais informações, consulte Common request headers.

Parâmetros da solicitação

Utilize estes parâmetros para filtrar resultados: prefix, key-marker, version-id-marker, delimiter e max-keys.

Parâmetro	Tipo	Obrigatório	Exemplo	Descrição
delimiter	String	Não	/	Caractere usado para agrupar objetos por nome. Se prefix e delimiter forem especificados, a resposta conterá CommonPrefixes. Objetos cujos nomes compartilham a mesma string entre o prefixo e a próxima ocorrência do delimitador são agrupados como uma única entrada CommonPrefixes. Caso o prefix seja um nome de diretório e o delimiter seja uma barra (/), apenas os objetos desse diretório serão retornados. Os nomes dos subdiretórios aparecem em CommonPrefixes, mas objetos e diretórios dentro desses subdiretórios não são listados. Valor padrão: vazio.
key-marker	String	Obrigatório se version-id-marker for especificado.	example	Retorna objetos em ordem alfabética após este valor. Pode ser usado em conjunto com version-id-marker. Comprimento máximo: 1.024 bytes. Valor padrão: vazio.
version-id-marker	String	Não	CAEQMxiBgICbof2D0BYiIGRhZjgwMzJiMjA3MjQ0ODE5MWYxZDYwMzJlZjU1****	Retorna versões criadas antes deste marcador para o objeto especificado por key-marker, em ordem decrescente de tempo de criação. Se omitido, os resultados começam a partir da versão mais recente do objeto seguinte em ordem alfabética após key-marker. Valor padrão: vazio. Valores válidos: IDs de versão.
max-keys	String	Não	100	Número máximo de objetos a serem retornados. Se os resultados excederem max-keys, a resposta incluirá `NextKeyMarker` e `NextVersionIdMarker` como marcadores de paginação para a próxima solicitação. Valores válidos: 1 a 999. Valor padrão: 100.
prefix	String	Não	fun	Prefixo que os nomes dos objetos retornados devem conter. O valor deve ter menos de 1.024 bytes de comprimento. Ao usar prefix para filtrar resultados, os valores de Key na resposta ainda incluem o prefixo. Se prefix for definido como um nome de diretório, todos os objetos e subdiretórios nesse diretório serão listados. Valor padrão: vazio.
encoding-type	String	Não	URL	Tipo de codificação do conteúdo da resposta. Valor padrão: vazio. Valores válidos: URL. Importante Os valores de delimiter, marker, prefix, NextMarker e Key são codificados em UTF-8. Se algum desses valores contiver caracteres de controle não suportados pelo XML 1.0, defina encoding-type para codificar os valores de Delimiter, Marker, Prefix, NextMarker e Key na resposta.

Parâmetros da resposta

Parâmetro	Tipo	Exemplo	Descrição
ListVersionsResult	Container	N/A	Contêiner para os resultados de ListObjectVersions (GetBucketVersions). Nós filhos: Name, Prefix, Marker, MaxKeys, Delimiter, IsTruncated, NextMarker, Version e DeleteMarker Nós pais: nenhum
CommonPrefixes	Container	N/A	Se delimiter for especificado, objetos cujos nomes compartilham a mesma string entre o prefixo e a próxima ocorrência do delimitador são agrupados como uma única entrada CommonPrefixes. Nós pais: ListVersionsResult
Delimiter	String	/	Caractere usado para agrupar objetos por nome. Objetos que compartilham a mesma string entre o prefixo e a próxima ocorrência do delimitador são agrupados como uma única entrada CommonPrefixes. Nós pais: ListVersionsResult
EncodingType	String	URL	Tipo de codificação do conteúdo da resposta. Se encoding-type for especificado na solicitação, os valores de Delimiter, Marker, Prefix, NextMarker e Key serão codificados. Nós pais: ListVersionsResult
IsTruncated	String	true	Indica se os resultados foram truncados. true: nem todos os resultados foram retornados. false: todos os resultados foram retornados. Valores válidos: true e false. Nós pais: ListVersionsResult
KeyMarker	String	example	Objeto a partir do qual a listagem começa. Nós pais: ListVersionsResult
VersionIdMarker	String	CAEQMxiBgICbof2D0BYiIGRhZjgwMzJiMjA3MjQ0ODE5MWYxZDYwMzJlZjU1****	Versão a partir da qual a operação ListObjectVersions (GetBucketVersions) começa. Usado em conjunto com KeyMarker. Nós pais: ListVersionsResult
NextKeyMarker	String	test	Incluído quando os resultados são truncados. Use como key-marker na próxima solicitação para continuar a listagem. Nós pais: ListVersionsResult
NextVersionIdMarker	String	CAEQGBiBgIC_jq7P9xYiIDRiZWJkNjY2Y2Q4NDQ5ZTI5ZGE5ODIxMTIyZThl****	Incluído quando os resultados são truncados. Use como version-id-marker na próxima solicitação para continuar a listagem. Nós pais: ListVersionsResult
MaxKeys	String	1000	Número máximo de objetos retornados na resposta. Nós pais: ListVersionsResult
Name	String	examplebucket-1250000000	Nome do bucket. Nós pais: ListVersionsResult
Prefix	String	fun	Prefixo que deve estar incluído nos nomes dos objetos listados. Nós pais: ListVersionsResult
Version	Container	N/A	Contêiner para versões de objetos, excluindo marcadores de exclusão. Nós pais: ListVersionsResult
DeleteMarker	Container	N/A	Contêiner para marcadores de exclusão. Nós pais: ListVersionsResult
ETag	String	250F8A0AE989679A22926A875F0A2****	ETag do objeto, usado para identificar o conteúdo do objeto. Para objetos criados por PutObject, o ETag é o hash MD5 do conteúdo. Para objetos criados por outros métodos, o ETag é um valor único calculado por uma regra diferente, não sendo o hash MD5. Nota O valor ETag indica apenas se o conteúdo do objeto foi alterado. Não utilize o valor ETag como hash MD5 do conteúdo do objeto para verificar a integridade dos dados. Nós pais: ListVersionsResult.Version
Key	String	example	Nome do objeto. Nós pais: ListVersionsResult.Version e ListVersionsResult.DeleteMarker
LastModified	Time	2019-04-09T07:27:28.000Z	Hora da última modificação do objeto. A duração mínima de armazenamento para objetos na classe de armazenamento Infrequent Access é de 30 dias. A duração é calculada a partir do horário Last-Modified do objeto. Se você excluir um objeto mais de 30 dias após seu horário Last-Modified, nenhuma taxa de exclusão antecipada será cobrada. A duração mínima de armazenamento para objetos na classe de armazenamento Archive é de 60 dias. A duração é calculada a partir do horário Last-Modified do objeto. Se você excluir um objeto mais de 60 dias após seu horário Last-Modified, nenhuma taxa de exclusão antecipada será cobrada. Nós pais: ListVersionsResult.Version e ListVersionsResult.DeleteMarker
TransitionTime	Time	2024-04-23T07:21:42.000Z	Momento em que a classe de armazenamento do objeto é alterada para Cold Archive ou Deep Cold Archive com base nas regras de ciclo de vida. Se você excluir um objeto Cold Archive ou Deep Cold Archive mais de 180 dias após a conversão, nenhuma taxa de exclusão antecipada será cobrada. Caso a exclusão ocorra dentro de 180 dias após a conversão, uma taxa de exclusão antecipada será aplicada. Este campo não pode ser usado para determinar o momento em que um objeto é convertido para a classe de armazenamento IA ou Archive por uma regra de ciclo de vida. O cumprimento do requisito de duração mínima de armazenamento para objetos IA ou Archive depende do horário `Last-Modified`. Nós pais: ListVersionsResult.Version e ListVersionsResult.DeleteMarker
VersionId	String	CAEQMxiBgMDNoP2D0BYiIDE3MWUxNzgxZDQxNTRiODI5OGYwZGMwNGY3MzZjN****	ID da versão do objeto. Nós pais: ListVersionsResult.Version e ListVersionsResult.DeleteMarker
IsLatest	String	true	Indica se esta versão é a versão atual. Valores válidos: true: A versão do objeto é a versão atual. false: A versão do objeto não é a versão atual. Nós pais: ListVersionsResult.Version e ListVersionsResult.DeleteMarker
Size	String	93731	Tamanho do objeto em bytes. Nós pais: ListVersionsResult.Version e ListVersionsResult.DeleteMarker
StorageClass	String	Standard	Classe de armazenamento do objeto. Nós pais: ListVersionsResult.Version e ListVersionsResult.DeleteMarker
Owner	Container	N/A	Contêiner para informações do proprietário do bucket. Nós pais: ListVersionsResult.Version e ListVersionsResult.DeleteMarker
DisplayName	String	12345125285864390	Nome do proprietário do objeto. Nós pais: ListVersionsResult.Version.Owner e ListVersionsResult.DeleteMarker.Owner
ID	String	1234512528586****	ID de usuário do proprietário do bucket. Nós pais: ListVersionsResult.Version.Owner e ListVersionsResult.DeleteMarker.Owner
RestoreInfo	String	ongoing-request="true"	Estado de restauração do objeto. Não incluído se nenhuma solicitação RestoreObject for enviada ou se as solicitações expirarem. Enquanto o objeto está sendo restaurado, o valor é `ongoing-request="true"`. Após a restauração do objeto, o valor segue o formato `ongoing-request="false", expiry-date="Thu, 24 Sep 2020 12:40:33 GMT"`, onde `expiry-date` indica o prazo até o qual o objeto restaurado pode ser lido.

Para obter mais informações sobre os cabeçalhos de resposta comuns, como x-oss-request-id e Content-Type na resposta a uma solicitação ListObjectVersions (GetBucketVersions), consulte Common response headers.

Exemplos

Listar as versões de objetos em um bucket sem versionamento

Exemplos de solicitações

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

Exemplo de resposta de sucesso

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 as versões de objetos em um bucket com versionamento habilitado

O bucket oss-example contém dois objetos: example com três versões (111222, 000123 como marcador de exclusão e 222333, em ordem decrescente de tempo de criação), e pic.jpg com uma versão (232323).

Se você definir key-marker como example e version-id-marker como 111222, as seguintes três versões serão retornadas em sequência: 000123 de example, 222333 de example e 232323 de pic.jpg.

Exemplos de solicitações

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

Exemplos de respostas de sucesso

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 e objetos Cold Archive armazenados no bucket solicitado

Considere que o bucket examplebucket contenha os objetos exampleobject1.txt, exampleobject2.txt e exampleobject3.txt. Todos os três objetos estão na classe de armazenamento Cold Archive. Os estados dos três objetos são os seguintes:

Para exampleobject1.txt, nenhuma solicitação RestoreObject foi enviada ou a solicitação enviada expirou.
Para exampleobject2.txt, uma solicitação RestoreObject foi enviada e a operação de restauração está em andamento.
Para exampleobject3.txt, uma solicitação RestoreObject foi enviada e a operação de restauração foi concluída.

Exemplo de solicitação

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

Exemplo de resposta

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>

SDKs do OSS

Execute esta operação com os seguintes SDKs do OSS:

Interface de linha de comando ossutil

Para obter informações sobre o comando ossutil correspondente à operação ListObjectVersions, consulte list-object-versions.

Códigos de erro

Código de erro	Código de status HTTP	Descrição
NoSuchBucket	404	O bucket não existe. Verifique se o nome do bucket segue as convenções de nomenclatura.
AccessDenied	403	Somente o proprietário do bucket ou usuários RAM com a permissão `oss:ListObjectVersions` podem chamar esta operação.
InvalidArgument	400	O valor de max-keys é menor que 0 ou maior que 1.000. O comprimento do parâmetro prefix, marker ou delimiter é inválido.