Listar objetos

Para listar os objetos de um bucket, faça uma solicitação GET com escopo para o bucket. Também é possível usar parâmetros de string de consulta para ampliar o escopo da solicitação. A solicitação retorna a lista de objetos em um documento XML no corpo da resposta, e os objetos na lista são ordenados lexicograficamente por nome.

Você precisa ter a permissão READ do bucket para ver a lista de objetos que estão em um bucket e a permissão FULL_CONTROL do bucket para listar as ACLs ou o CORS de um bucket.

É possível restringir e organizar a lista de objetos retornados em uma solicitação GET Bucket usando os parâmetros de string de consulta delimiter, marker, max-keys e prefix.

A API XML não retorna listas com mais de 1.000 objetos.

Parâmetros de string de consulta

Parâmetro Descrição Obrigatório
delimiter Um caractere ou vários caracteres que podem ser usados para simplificar uma lista de objetos que usam um esquema de nomeação semelhante a um diretório. Pode ser usado em conjunto com um prefix. Não
encoding-type Quando definido como url, os nomes dos objetos são codificados por URL na resposta. Não
generation-marker A geração de objetos a que você quer iniciar a listagem de objetos. Se você usar o marcador de geração, também será necessário usá-lo. Não
marker O nome do objeto após o qual você deseja iniciar a listagem de objetos. Objetos com nomes lexicograficamente maiores que marker são retornados na lista de objetos. Não
max-keys O número máximo de objetos para retornar em uma solicitação de listagem de objetos. Não
prefix Uma string que pode ser usada para limitar o número de objetos retornados em uma solicitação GET Bucket somente às pessoas cujos nomes começam com o valor especificado. Pode ser usado em conjunto com um delimiter. Não
versions Se especificada em um bucket com controle de versão, retorna a lista de todas as versões de objeto. Se omitido, lista apenas as versões atuais. Não

Consulte parâmetros de string de consulta de URL assinado para informações sobre os parâmetros incluídos ao criar e usar URLs assinados.

Cabeçalhos de solicitação

Veja cabeçalhos de solicitação comuns.

Elementos do corpo da solicitação

Esta solicitação não inclui um documento XML no corpo da solicitação.

Sintaxe da solicitação

A sintaxe a seguir se aplica a solicitações GET Bucket que não usam parâmetros ou um ou mais dos parâmetros delimiter, generation-marker, marker, max-keys, prefix. e versions.

GET /?prefix=a_prefix&marker=a_marker&max-keys=max_number_of_keys&delimiter=a_delimiter HTTP/1.1
Host: BUCKET_NAME.storage.googleapis.com
Date: DATE
Content-Length: 0
Authorization: AUTHENTICATION_STRING

Cabeçalhos de resposta

A solicitação pode retornar diversos cabeçalhos de resposta, dependendo dos cabeçalhos de solicitação usados.

Elementos do corpo da resposta

Os elementos do corpo de resposta a seguir são aplicáveis somente se você não usar parâmetros ou um ou mais dosdelimiter ,generation-marker ,marker ,max-keys ,prefix ouversions parâmetros de string de consulta para listar objetos em um bucket.

Element Descrição
ListBucketResult Recipiente para as informações do objeto que você está solicitando.
Name O nome do bloco.
CommonPrefixes Contêiner para prefixos que atendem às suas restrições de prefix e delimiter. Esse contêiner será usado somente se você especificar um delimiter na solicitação e entradas duplicadas forem omitidas.
Delimiter O delimiter que você especificou na solicitação.
MaxKeys O max-keys que você especificou na solicitação.
Prefix O prefix que você especificou na solicitação.
GenerationMarker O generation-marker que você especificou na solicitação.
NextGenerationMarker Se a lista de objetos retornados estiver incompleta e o parâmetro versions tiver sido usado, NextGenerationMarker fornecerá a geração do último objeto retornado. Se a lista já estiver concluída, NextGenerationMarker não será retornado.
Marker O marker que você especificou na solicitação.
NextMarker NextMarker fornece o nome do último objeto retornado. O valor de NextMarker pode ser fornecido no parâmetro de string de consulta marker em uma chamada futura de GET Bucket para continuar listando o bucket após esse conjunto de resultados. Se não houver mais objetos no bucket que sigam o último objeto na lista, NextMarker não será retornado.
IsTruncated Indica se todos os objetos de um bloco aparecem na lista. Se max-keys for menor que o número de objetos em um bucket, esse elemento será True.
Contents Contêiner para informações de objeto se o parâmetro de consulta versions não for usado.
Version Contêiner para informações de objeto se o parâmetro de consulta versions for usado.
Key O nome de um objeto.
Generation A geração do objeto.
MetaGeneration Geração dos metadados do objeto.
IsLatest Se o parâmetro de consulta versions for especificado, isso será definido como verdadeiro se o objeto estiver ativo no momento. Operação ativa que, se esse objeto for solicitado sem geração, ele será retornado.
LastModified A data e a hora em que os metadados do objeto foram modificados pela última vez.
DeletedTime Se o parâmetro de consulta versions foi especificado, contém a data e o horário em que um objeto foi substituído ou excluído para objetos não atuais (se o controle de versão do bucket estiver ativado).
ETag Uma tag de entidade HTTP 1.1 para o objeto.
Size Tamanho do objeto em bytes.
KmsKeyName O nome da chave KMS usada para criptografar o objeto. Esse elemento só estará presente se o objeto estiver criptografado com chaves de criptografia gerenciadas pelo cliente.

Exemplos

O exemplo a seguir lista os objetos de um bloco chamado travel-maps.

Solicitação

GET / HTTP/1.1
Host: travel-maps.storage.googleapis.com
Date: Wed, 17 Feb 2010 15:31:56 GMT
Content-Length: 0
Content-Type: text/plain
Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg

Resposta

HTTP/1.1 200 OK
 Content-Length: 4061
 Content-Type: application/xml
 Date: Wed, 17 Feb 2010 23:31:57 GMT
 Expires: Wed, 17 Feb 2010 23:31:57 GMT

<?xml version='1.0' encoding='utf-8'?>
<ListBucketResult xmlns='http://doc.s3.amazonaws.com/2006-03-01'>
  <Name>travel-maps</Name>
  <Prefix></Prefix>
  <Marker></Marker>
  <IsTruncated>false</IsTruncated>
  <Contents>
    <Key>europe/france/cannes.pdf</Key>
    <Generation>1360887759327000</Generation>
    <MetaGeneration>1</MetaGeneration>
    <LastModified>2010-02-17T22:11:12.487Z</LastModified>
    <ETag>"53fc311c15eda0a031809982ccf92aac"</ETag>
    <Size>5061631</Size>
  </Contents>
  <Contents>
    <Key>europe/france/paris.pdf</Key>
    <Generation>1360887759329000</Generation>
    <MetaGeneration>1</MetaGeneration>
    <LastModified>2010-02-17T22:09:57.457Z</LastModified>
    <ETag>"53fc311c15eda0a031809982ccf92aac"</ETag>
    <Size>5061631</Size>
  </Contents>
</ListBucketResult>

A amostra a seguir lista os objetos em mapas de viagem, mas restringe a lista a 25 objetos que começam com a letra "t" e vem depois de "test".

Solicitação

GET /?prefix=t&marker=test&max-keys=25 HTTP/1.1
Host: travel-maps.storage.googleapis.com
Date: Mon, 16 Feb 2010 22:58:38 GMT
Content-Length: 0
Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg

Resposta

HTTP/1.1 200 OK
Date: Mon, 15 Feb 2010 12:30:40 GMT
Content-Length: 2705
Content-Type: application/xml

<?xml version='1.0' encoding='utf-8'?>
<ListBucketResult xmlns='http://doc.s3.amazonaws.com/2006-03-01'>
  <Name>travel-maps</Name>
  <Prefix>t</Prefix>
  <Marker>test</Marker>
  <MaxKeys>25</MaxKeys>
  <IsTruncated>false</IsTruncated>
  <Contents>
    <Key>test_a.jpg</Key>
    <Generation>1360887659329000</Generation>
    <MetaGeneration>1</MetaGeneration>
    <LastModified>2010-02-17T03:12:55.561Z</LastModified>
    <ETag>"2281880ef78388266ecd7d4c1b472a0e"</ETag>
    <Size>328</Size>
  </Contents>
  <Contents>
    <Key>test_b.jpg</Key>
    <Generation>1360887659323000</Generation>
    <MetaGeneration>1</MetaGeneration>
    <LastModified>2010-02-17T03:12:54.606Z</LastModified>
    <ETag>"2281880ef78388266ecd7d4c1b472a0e"</ETag>
    <Size>328</Size>
  </Contents>
  <Contents>
    <Key>test_c.jpg</Key>
    <LastModified>2010-02-17T03:12:53.734Z</LastModified>
    <ETag>"2281880ef78388266ecd7d4c1b472a0e"</ETag>
    <Size>328</Size>
  </Contents>
</ListBucketResult>

Exemplo de uso de prefixo e delimitador

O exemplo a seguir usa prefix e delimiter para retornar uma lista de objetos nomeados usando um esquema semelhante a diretório. Ao usar prefix=europe/ e delimiter=/, somente os objetos que estão no "diretório" europe/ são retornados. Objetos que estão em "subdiretórios" do diretório europe não são listados, mas têm a parte inicial dos nomes incluídos nos elementos CommonPrefixes da resposta. A amostra pressupõe que os seguintes objetos estão contidos em um bucket chamado travel-maps:

  • africa/ghana.jpg
  • africa/egypt/cairo.jpg
  • europe/finland.jpg
  • europe/norway.jpg
  • europe/france/paris.jpg
  • europe/italy/rome.jpg
  • europe/sweden/stockholm.jpg
  • europe/sweden/stockholm/nordic_museum.jpg

A solicitação de amostra retorna um documento XML que lista os dois objetos a seguir no elemento Contents:

  • europe/finland.jpg
  • europe/norway.jpg

Os subdiretórios de europe a seguir são listados no elemento CommonPrefixes:

  • europe/france/
  • europe/italy/
  • europe/sweden/

Solicitação

GET /travel-maps?delimiter=/&prefix=europe/ HTTP/1.1
Host: storage.googleapis.com
Date: Mon, 16 Feb 2010 22:58:38 GMT
Content-Length: 0
Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg

Resposta

HTTP/1.1 200 OK
Date: Mon, 15 Feb 2010 12:30:40 GMT
Content-Length: 1200
Content-Type: application/xml

<?xml version="1.0"?>
<ListBucketResult xmlns='http://doc.s3.amazonaws.com/2006-03-01'>
  <Name>mybucket</Name>
  <Prefix>europe/</Prefix>
  <Marker />
  <IsTruncated>false</IsTruncated>
  <Contents>
    <Key>europe/finland.jpg</Key>
    <Generation>1360887659323000</Generation>
    <MetaGeneration>1</MetaGeneration>
    <LastModified>2010-02-17T03:12:55.561Z</LastModified>
    <ETag>"781e5e245d69b566979b86e28d23f2c7"</ETag>
    <Size>10</Size>
  </Contents>
  <Contents>
    <Key>europe/norway.jpg</Key>
    <Generation>1360887659323000</Generation>
    <MetaGeneration>1</MetaGeneration>
    <LastModified>2010-02-17T03:12:55.561Z</LastModified>
    <ETag>"781e5e245d69b566979b86e28d23f2c7"</ETag>
    <Size>10</Size>
  </Contents>
  <CommonPrefixes>
    <Prefix>europe/france/</Prefix>
  </CommonPrefixes>
  <CommonPrefixes>
    <Prefix>europe/italy/</Prefix>
  </CommonPrefixes>
  <CommonPrefixes>
    <Prefix>europe/sweden/</Prefix>
  </CommonPrefixes>
</ListBucketResult>