Listar objetos em um bucket com versionamento habilitado

Esta seção fornece exemplos de como listar versões de objetos de um bucket com versionamento habilitado. O Amazon S3 armazena as informações de versão do objeto no sub-recurso versões associado ao bucket. Para obter mais informações, consulte Opções de configuração do bucket. Para listar os objetos em um bucket do com versionamento habilitado, a permissão ListBucketVersions é necessária.

Siga estas etapas para usar o console do Amazon S3 para ver as diferentes versões de um objeto.

Para ver várias versões de um objeto

Faça login no AWS Management Console e abra o console do Amazon S3 em https://console.aws.amazon.com/s3/.
Na lista Buckets, escolha o nome do bucket que contém o objeto.
Para ver uma lista das versões dos objetos no bucket, escolha a opção Show versions (Mostrar versões).

Para cada versão do objeto, o console exibe um ID de versão exclusivo, a data e a hora em que a versão do objeto foi criada e outras propriedades. (Os objetos armazenados em seu bucket antes da habilitação do versionamento têm um ID de versão null [nulo].)

Para listar os objetos sem as versões, escolha a opção List versions (Listar versões) .

Você também pode visualizar, fazer download e excluir versões do objeto no painel de visão geral do objeto no console. Para obter mais informações, consulte Exibir uma visão geral do objeto no console do Amazon S3.

nota

Para acessar versões de objetos anteriores a 300 versões, use a AWS CLI ou o URL do objeto.

Importante

Você pode cancelar a exclusão de um objeto somente se ele foi excluído como a versão mais recente (atual). Não é possível cancelar a exclusão de uma versão anterior de um objeto que foi excluído. Para obter mais informações, consulte Usando o versionamento em buckets do S3.

Os exemplos nesta seção mostram como recuperar uma listagem de objetos de um bucket com versionamento ativado. Cada solicitação retorna até 1.000 versões, a menos que você especifique um número menor. Se o bucket contiver mais versões que esse limite, envie uma série de solicitações para recuperar a lista de todas as versões. Esse processo de retornar resultados em “páginas” é chamado paginação.

Para mostrar como a paginação funciona, os exemplos limitam cada resposta a duas versões de objeto. Depois de recuperar a primeira página de resultados, cada exemplo verifica se a lista de versões foi truncada. Em caso afirmativo, o exemplo continua a recuperar páginas até que todas as versões tenham sido recuperadas.

nota

Os exemplos a seguir também funcionam com bucket sem versionamento, ou para objetos sem versões individuais. Nesses casos, o Amazon S3 retorna a listagem de objetos com um ID de versão null.

Para obter informações sobre o uso de outros AWS SDKs, consulte o Centro do Desenvolvedor da AWS.

Java

Consulte instruções sobre como criar e testar uma amostra funcional em Getting Started no Guia do desenvolvedor do AWS SDK for Java.



import com.amazonaws.AmazonServiceException;
import com.amazonaws.SdkClientException;
import com.amazonaws.auth.profile.ProfileCredentialsProvider;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.s3.AmazonS3;
import com.amazonaws.services.s3.AmazonS3ClientBuilder;
import com.amazonaws.services.s3.model.ListVersionsRequest;
import com.amazonaws.services.s3.model.S3VersionSummary;
import com.amazonaws.services.s3.model.VersionListing;

public class ListKeysVersioningEnabledBucket {

    public static void main(String[] args) {
        Regions clientRegion = Regions.DEFAULT_REGION;
        String bucketName = "*** Bucket name ***";

        try {
            AmazonS3 s3Client = AmazonS3ClientBuilder.standard()
                    .withCredentials(new ProfileCredentialsProvider())
                    .withRegion(clientRegion)
                    .build();

            // Retrieve the list of versions. If the bucket contains more versions
            // than the specified maximum number of results, Amazon S3 returns
            // one page of results per request.
            ListVersionsRequest request = new ListVersionsRequest()
                    .withBucketName(bucketName)
                    .withMaxResults(2);
            VersionListing versionListing = s3Client.listVersions(request);
            int numVersions = 0, numPages = 0;
            while (true) {
                numPages++;
                for (S3VersionSummary objectSummary : versionListing.getVersionSummaries()) {
                    System.out.printf("Retrieved object %s, version %s\n",
                            objectSummary.getKey(),
                            objectSummary.getVersionId());
                    numVersions++;
                }
                // Check whether there are more pages of versions to retrieve. If
                // there are, retrieve them. Otherwise, exit the loop.
                if (versionListing.isTruncated()) {
                    versionListing = s3Client.listNextBatchOfVersions(versionListing);
                } else {
                    break;
                }
            }
            System.out.println(numVersions + " object versions retrieved in " + numPages + " pages");
        } catch (AmazonServiceException e) {
            // The call was transmitted successfully, but Amazon S3 couldn't process
            // it, so it returned an error response.
            e.printStackTrace();
        } catch (SdkClientException e) {
            // Amazon S3 couldn't be contacted for a response, or the client
            // couldn't parse the response from Amazon S3.
            e.printStackTrace();
        }
    }
}

.NET

Para obter informações sobre como configurar e executar exemplos de código, consulte Conceitos básicos do AWS SDK for .NET no Guia do desenvolvedor do AWS SDK for .NET.


using Amazon;
using Amazon.S3;
using Amazon.S3.Model;
using System;
using System.Threading.Tasks;

namespace Amazon.DocSamples.S3
{
    class ListObjectsVersioningEnabledBucketTest
    {
        static string bucketName = "*** bucket name ***";
        // Specify your bucket region (an example region is shown).
        private static readonly RegionEndpoint bucketRegion = RegionEndpoint.USWest2;
        private static IAmazonS3 s3Client;

        public static void Main(string[] args)
        {
            s3Client = new AmazonS3Client(bucketRegion);
            GetObjectListWithAllVersionsAsync().Wait();
        }

        static async Task GetObjectListWithAllVersionsAsync()
        {
            try
            {
                ListVersionsRequest request = new ListVersionsRequest()
                {
                    BucketName = bucketName,
                    // You can optionally specify key name prefix in the request
                    // if you want list of object versions of a specific object.

                    // For this example we limit response to return list of 2 versions.
                    MaxKeys = 2
                };
                do
                {
                    ListVersionsResponse response = await s3Client.ListVersionsAsync(request); 
                    // Process response.
                    foreach (S3ObjectVersion entry in response.Versions)
                    {
                        Console.WriteLine("key = {0} size = {1}",
                            entry.Key, entry.Size);
                    }

                    // If response is truncated, set the marker to get the next 
                    // set of keys.
                    if (response.IsTruncated)
                    {
                        request.KeyMarker = response.NextKeyMarker;
                        request.VersionIdMarker = response.NextVersionIdMarker;
                    }
                    else
                    {
                        request = null;
                    }
                } while (request != null);
            }
            catch (AmazonS3Exception e)
            {
                Console.WriteLine("Error encountered on server. Message:'{0}' when writing an object", e.Message);
            }
            catch (Exception e)
            {
                Console.WriteLine("Unknown encountered on server. Message:'{0}' when writing an object", e.Message);
            }
        }
    }
}

exemplo — Listar todas as versões de objeto em um bucket

Para listar todas as versões de todos os objetos em um bucket, você usa o sub-recurso versions em uma solicitação GET Bucket. O Amazon S3 pode recuperar no máximo 1.000 objetos, e cada versão de objeto conta como um objeto completo. Portanto, se um bucket contiver duas chaves (por exemplo, photo.gif e picture.jpg) e a primeira chave tiver 990 versões e a segunda chave tiver 400 versões, uma solicitação única recuperará as 990 versões de photo.gif e apenas as 10 versões mais recentes de picture.jpg.

O Amazon S3 retorna as versões de objetos na ordem em que foram armazenadas, com as armazenadas mais recentemente sendo retornadas primeiro.

Em uma solicitação GET Bucket, inclua o sub-recurso versions.


GET /?versions HTTP/1.1
Host: bucketName.s3.amazonaws.com
Date: Wed, 28 Oct 2009 22:32:00 +0000
Authorization: AWS AKIAIOSFODNN7EXAMPLE:0RQf4/cRonhpaBX5sCYVf1bNRuU=

exemplo — Recuperar todas as versões de uma chave

Para recuperar um subconjunto de versões de objeto, use os parâmetros de solicitação para GET Bucket. Para ter mais informações, consulte GET Bucket.

Defina o parâmetro prefix como a chave do objeto que você deseja recuperar.
Envie uma solicitação GET Bucket usando o sub-recurso versions e prefix.

GET /?versions&prefix=objectName HTTP/1.1

exemplo — Recuperar objetos usando um prefixo

O exemplo a seguir recupera objetos cuja chave é ou começa com myObject.


GET /?versions&prefix=myObject HTTP/1.1
Host: bucket.s3.amazonaws.com
Date: Wed, 28 Oct 2009 22:32:00 GMT
Authorization: AWS AKIAIOSFODNN7EXAMPLE:0RQf4/cRonhpaBX5sCYVf1bNRuU=

Você pode usar os outros parâmetros de solicitação para recuperar um subconjunto de todas as versões do objeto. Para obter mais informações, consulte GET Bucket na Referência da API do Amazon Simple Storage Service.

exemplo — Recuperar uma listagem de objetos adicionais se a resposta estiver truncada

Se o número de objetos que podem ser retornados em uma solicitação GET exceder o valor de max-keys, a resposta conterá <isTruncated>true</isTruncated> e incluirá a primeira chave (em NextKeyMarker) e o primeiro ID de versão (em NextVersionIdMarker) que satisfazem a solicitação, mas que não foram retornados. Você usa esses valores retornados como a posição de início em uma solicitação subsequente para recuperar os objetos adicionais que satisfazem a solicitação GET.

Use o seguinte processo para recuperar os objetos adicionais que satisfazem a solicitação GET Bucket versions original de um bucket. Para obter mais informações sobre key-marker, version-id-marker, NextKeyMarker e NextVersionIdMarker, consulte GET Bucket na Referência da API do Amazon Simple Storage Service.

A seguir estão as respostas adicionais que atendem à solicitação GET original:

Defina o valor de key-marker como a chave retornada em NextKeyMarker na resposta anterior.
Defina o valor de version-id-marker como o ID de versão retornado em NextVersionIdMarker na resposta anterior.
Envie uma solicitação GET Bucket versions usando key-marker e version-id-marker.

exemplo — Recuperar objetos que começam com a chave e o ID de versão especificados


GET /?versions&key-marker=myObject&version-id-marker=298459348571 HTTP/1.1
Host: bucket.s3.amazonaws.com
Date: Wed, 28 Oct 2009 22:32:00 GMT
Authorization: AWS AKIAIOSFODNN7EXAMPLE:0RQf4/cRonhpaBX5sCYVf1bNRuU=

O comando a seguir retorna os metadados de todas as versões dos objetos em um bucket.


aws s3api list-object-versions --bucket amzn-s3-demo-bucket1

Para obter mais informações sobre list-object-versions, consulte list-object-versions na Referência de comandos de AWS CLI.

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Adicionando objetos

Recuperar versões de objeto