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

**nota**  
 Las API de SOAP para Amazon S3 no están disponibles para nuevos clientes y se acercan al fin de la vida útil (EOL) el 31 de agosto de 2025. Le recomendamos que utilice la API de REST o los SDK de AWS. 

 La operación `ListBucket` devuelve información sobre alguno de los elementos en el bucket. 

 Para obtener una introducción general a la operación de muestra, consulte [Listado de claves de objetos](https://docs.aws.amazon.com/AmazonS3/latest/userguide/ListingKeysUsingAPIs.html).

## Solicitudes
<a name="SOAPBucketGET_Request"></a>

En este ejemplo, se muestran hasta 1000 claves del bucket “quotes” que tienen el prefijo “notas”.

### Sintaxis
<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>


|  Nombre  |  Descripción  |  Obligatorio  | 
| --- | --- | --- | 
|  prefix  | Limita la respuesta a las claves que comienzan con el prefijo indicado. Puede usar prefijos para separar un bucket en diferentes conjuntos de claves de forma similar a como un sistema de archivos usa las carpetas.<br />Tipo: cadena<br />Valor predeterminado: None |  No  | 
|  marker  | Indica en qué parte del bucket se debe empezar a mostrar. La lista solo incluirá las claves que aparecen lexicográficamente después del marcador. Esto resulta práctico para la paginación: para pasar a la siguiente página de resultados, utilice la última clave de la página actual como marcador.<br />Tipo: cadena<br />Valor predeterminado: None |  No  | 
|  max-keys  | El número máximo de claves que le gustaría ver en el cuerpo de la respuesta. Es posible que el servidor devuelva menos claves que esta cantidad, pero no devolverá más.<br />Tipo: cadena<br />Valor predeterminado: None |  No  | 
|  delimiter  | Hace que las claves que contienen la misma cadena entre el prefijo y la primera aparición del delimitador se agrupen en un único elemento de resultado de la colección CommonPrefixes. Estas claves acumuladas no se devuelven en ninguna otra parte de la respuesta.<br />Tipo: cadena<br />Valor predeterminado: None |  No  | 

## Respuesta de éxito
<a name="SOAPBucketGET_ResponseSuccess"></a>

Esta respuesta asume que el bucket contiene las siguientes claves:

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

### Sintaxis
<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 puede ver, muchos de los campos de la respuesta reflejan los parámetros de solicitud. `IsTruncated`, `Contents` y `CommonPrefixes` son los únicos elementos de respuesta que pueden contener información nueva.

### Elementos de respuesta
<a name="SOAPBucketGET_ResponseSuccess-response-elements"></a>


|  Nombre  |  Descripción  | 
| --- | --- | 
|  Contents  | Metadatos sobre cada objeto devuelto.<br />Tipo: Metadatos XML<br />Antecesor: ListBucketResult | 
|  CommonPrefixes  |  Una respuesta puede contener `CommonPrefixes` solo si se especifica un `delimiter`. Si lo hace, `CommonPrefixes` contiene todas las claves (si las hay) situadas entre `Prefix` y la siguiente aparición de la cadena especificada por `delimiter`. En efecto, `CommonPrefixes` muestra las claves que actúan como subdirectorios en el directorio especificado por `Prefix`. Por ejemplo, si `prefix` es `notes/` y `delimiter` es una barra diagonal (/), en `notes/summer/july`, el prefijo común es `notes/summer/`. <br />Tipo: cadena<br />Antecesor: ListBucketResult | 
|  Delimiter  | Hace que las claves que contienen la misma cadena entre el prefijo y la primera aparición del delimitador se agrupen en un único elemento de resultado de la colección CommonPrefixes. Estas claves acumuladas no se devuelven en ninguna otra parte de la respuesta.<br />Tipo: cadena<br />Antecesor: ListBucketResult | 
|  IsTruncated  | Especifica si se devolvieron todos los resultados (verdadero) o no (falso). Es posible que no se devuelvan todos los resultados si el número de resultados supera el especificado por `MaxKeys`.<br />Tipo: cadena<br />Antecesor: boolean | 
|  Marker  | Indica en qué parte del bucket se debe empezar a mostrar.<br />Tipo: cadena<br />Antecesor: ListBucketResult | 
|  MaxKeys  | El número máximo de claves devueltas en el cuerpo de respuesta.<br />Tipo: cadena<br />Antecesor: ListBucketResult | 
|  Name  | Nombre del bucket.<br />Tipo: cadena<br />Antecesor: ListBucketResult | 
|  Prefix  | Claves que comienzan con el prefijo indicado.<br />Tipo: cadena<br />Antecesor: ListBucketResult | 

## Cuerpo de respuesta
<a name="SOAPListBucketResponseBody"></a>

 Para obtener información sobre la respuesta de la lista, consulte [Lista de respuesta de claves](https://docs.aws.amazon.com/AmazonS3/latest/userguide/ListingKeysUsingAPIs.html). 

## Control de acceso
<a name="SOAPListBucketAccessControl"></a>

Para mostrar las claves de un bucket, es necesario que se haya concedido acceso de `READ` al bucket.