# ListBucket (API SOAP)
<a name="SOAPListBucket"></a>

**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](https://docs.aws.amazon.com/AmazonS3/latest/userguide/ListingKeysUsingAPIs.html).

## Solicitações
<a name="SOAPBucketGET_Request"></a>

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

### Sintaxe
<a name="SOAPBucketGET_RequestSyntax"></a>

```
1. <ListBucket xmlns="https://doc.s3.amazonaws.com/2006-03-01">
2.   <Bucket>quotes</Bucket>
3.   <Prefix>notes/</Prefix>
4.   <Delimiter>/</Delimiter>
5.   <MaxKeys>1000</MaxKeys>
6.   <AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
7.   <Timestamp>2006-03-01T12:00:00.183Z</Timestamp>
8.   <Signature>Iuyz3d3P0aTou39dzbqaEXAMPLE=</Signature>
9. </ListBucket>
```

### Parâmetros
<a name="SOAPBucketGET_RequestHeaders"></a>


|  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.<br />Tipo: string<br />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.<br />Tipo: string<br />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.<br />Tipo: string<br />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.<br />Tipo: string<br />Padrão: nenhum |  Não  | 

## Resposta de êxito
<a name="SOAPBucketGET_ResponseSuccess"></a>

Essa resposta presume que o bucket contenha as seguintes chaves:

```
1. notes/todos.txt
2. notes/2005-05-23/customer_mtg_notes.txt
3. notes/2005-05-23/phone_notes.txt
4. notes/2005-05-28/sales_notes.txt
```

### Sintaxe
<a name="SOAPBucketGET_ResponseSuccess-syntax"></a>

```
 1. <?xml version="1.0" encoding="UTF-8"?>
 2. <ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
 3.   <Name>backups</Name>
 4.   <Prefix>notes/</Prefix>
 5.   <MaxKeys>1000</MaxKeys>
 6.   <Delimiter>/</Delimiter>
 7.   <IsTruncated>false</IsTruncated>
 8.   <Contents>
 9.     <Key>notes/todos.txt</Key>
10.     <LastModified>2006-01-01T12:00:00.000Z</LastModified>
11.     <ETag>&quot;828ef3fdfa96f00ad9f27c383fc9ac7f&quot;</ETag>
12.     <Size>5126</Size>
13.     <StorageClass>STANDARD</StorageClass>
14.     <Owner>
15.       <ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
16.       <DisplayName>webfile</DisplayName>
17.     </Owner>
18.     <StorageClass>STANDARD</StorageClass>
19.   </Contents>
20.   <CommonPrefixes>
21.     <Prefix>notes/2005-05-23/</Prefix>
22.   </CommonPrefixes>
23.   <CommonPrefixes>
24.     <Prefix>notes/2005-05-28/</Prefix>
25.   </CommonPrefixes>
26.   </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
<a name="SOAPBucketGET_ResponseSuccess-response-elements"></a>


|  Name (Nome)  |  Descrição  | 
| --- | --- | 
|  Contents  | Metadados sobre cada objeto retornado.<br />Tipo: metadados XML<br />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/`. <br />Tipo: string<br />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.<br />Tipo: string<br />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`.<br />Tipo: string<br />Antepassado: booleano | 
|  Marker  | Indica onde começar a listar no bucket.<br />Tipo: string<br />Antepassado: ListBucketResult | 
|  MaxKeys  | O número máximo de chaves retornadas no corpo da resposta.<br />Tipo: string<br />Antepassado: ListBucketResult | 
|  Name  | Nome do bucket.<br />Tipo: string<br />Antepassado: ListBucketResult | 
|  Prefix  | Chaves que começam com o prefixo indicado.<br />Tipo: string<br />Antepassado: ListBucketResult | 

## Corpo da resposta
<a name="SOAPListBucketResponseBody"></a>

 Para obter informações sobre a resposta da lista, consulte [Listagem de resposta de chaves](https://docs.aws.amazon.com/AmazonS3/latest/userguide/ListingKeysUsingAPIs.html). 

## Controle de acesso
<a name="SOAPListBucketAccessControl"></a>

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