View a markdown version of this page

ListBucket (API SOAP) - Amazon Simple Storage Service
SolicitaçõesResposta de êxitoCorpo da respostaControle de acesso

ListBucket (API SOAP)

nota

As APIs SOAP para o Amazon S3 não estão disponíveis para novos clientes e chegam ao fim da vida útil (EOL) em 31 de agosto de 2025. Recomendamos usar a API REST ou os AWS SDKs.

A operação ListBucket retorna informações sobre alguns dos itens no bucket.

Para uma introdução geral à operação de lista, consulte Listagem de chaves de objeto.

Solicitações

Este exemplo lista até 1000 chaves no bucket “quotes” que têm o prefixo “notes”.

Sintaxe

<ListBucket xmlns="https://doc.s3.amazonaws.com/2006-03-01">
  <Bucket>quotes</Bucket>
  <Prefix>notes/</Prefix>
  <Delimiter>/</Delimiter>
  <MaxKeys>1000</MaxKeys>
  <AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
  <Timestamp>2006-03-01T12:00:00.183Z</Timestamp>
  <Signature>Iuyz3d3P0aTou39dzbqaEXAMPLE=</Signature>
</ListBucket>

Parâmetros

Name (Nome) Descrição Obrigatório
prefix

Limita a resposta às chaves que começam com o prefixo indicado. Você pode usar prefixos para separar um bucket em diferentes conjuntos de chaves de modo semelhante à forma como um sistema de arquivos usa pastas.

Tipo: string

Padrão: nenhum

 Não
marker

Indica onde começar a listar no bucket. A lista incluirá apenas as chaves que ocorrem lexicograficamente após o marcador. Isso é útil para paginação: para obter a próxima página de resultados, use a última chave da página atual como marcador.

Tipo: string

Padrão: nenhum

 Não
max-keys

O número máximo de chaves que você quer ver no corpo da resposta. O servidor pode retornar menos do que essa quantidade de chaves, mas não retornará mais.

Tipo: string

Padrão: nenhum

 Não
delimiter

Faz com que as chaves com a mesma string entre o prefixo e a primeira ocorrência do delimitador sejam agrupadas em um único elemento de resultado na coleção CommonPrefixes. Essas chaves agrupadas não são retornadas em nenhum outro lugar na resposta.

Tipo: string

Padrão: nenhum

 Não

Resposta de êxito

Essa resposta presume que o bucket contenha as seguintes chaves:

notes/todos.txt
notes/2005-05-23/customer_mtg_notes.txt
notes/2005-05-23/phone_notes.txt
notes/2005-05-28/sales_notes.txt

Sintaxe

<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Name>backups</Name>
  <Prefix>notes/</Prefix>
  <MaxKeys>1000</MaxKeys>
  <Delimiter>/</Delimiter>
  <IsTruncated>false</IsTruncated>
  <Contents>
    <Key>notes/todos.txt</Key>
    <LastModified>2006-01-01T12:00:00.000Z</LastModified>
    <ETag>&quot;828ef3fdfa96f00ad9f27c383fc9ac7f&quot;</ETag>
    <Size>5126</Size>
    <StorageClass>STANDARD</StorageClass>
    <Owner>
      <ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
      <DisplayName>webfile</DisplayName>
    </Owner>
    <StorageClass>STANDARD</StorageClass>
  </Contents>
  <CommonPrefixes>
    <Prefix>notes/2005-05-23/</Prefix>
  </CommonPrefixes>
  <CommonPrefixes>
    <Prefix>notes/2005-05-28/</Prefix>
  </CommonPrefixes>
  </ListBucketResult>

Como você pode ver, muitos campos na resposta refletem os parâmetros da solicitação. IsTruncated, Contents e CommonPrefixes são os únicos elementos de resposta que podem conter novas informações.

Elementos de resposta

Name (Nome) Descrição
Contents

Metadados sobre cada objeto retornado.

Tipo: metadados XML

Antepassado: ListBucketResult
CommonPrefixes

Uma resposta poderá conter CommonPrefixes somente se você especificar um delimiter. Ao fazer isso, CommonPrefixes contém todas as chaves (se houver) entre Prefix e a próxima ocorrência da string especificada pelo delimiter. Na verdade, CommonPrefixes lista as chaves que agem como subdiretórios no diretório especificado pelo Prefix. Por exemplo, se prefix for notes/ e delimiter for uma barra (/), em notes/summer/july, o prefixo comum será notes/summer/.

Tipo: string

Antepassado: ListBucketResult
Delimiter

Faz com que as chaves com a mesma string entre o prefixo e a primeira ocorrência do delimitador sejam agrupadas em um único elemento de resultado na coleção CommonPrefixes. Essas chaves agrupadas não são retornadas em nenhum outro lugar na resposta.

Tipo: string

Antepassado: ListBucketResult
IsTruncated

Especifica se todos os resultados foram retornados (verdadeiro) ou não (falso). Todos os resultados podem não ser retornados se o número de resultados exceder o especificado por MaxKeys.

Tipo: string

Antepassado: booleano
Marker

Indica onde começar a listar no bucket.

Tipo: string

Antepassado: ListBucketResult
MaxKeys

O número máximo de chaves retornadas no corpo da resposta.

Tipo: string

Antepassado: ListBucketResult
Name

Nome do bucket.

Tipo: string

Antepassado: ListBucketResult
Prefix

Chaves que começam com o prefixo indicado.

Tipo: string

Antepassado: ListBucketResult

Corpo da resposta

Para obter informações sobre a resposta da lista, consulte Listagem de resposta de chaves.

Controle de acesso

Para listar as chaves de um bucket, você precisa ter acesso READ ao bucket.