ListObjects

Documentación: ListObjects

Descripción

La operación ListObjects retorna una lista de algunos o todos los objetos en un bucket. Puedes usar los parámetros de la solicitud para refinar la lista de objetos retornados. Para obtener una lista de todos los objetos, es posible que tengas que hacer varias peticiones, paginando los resultados.

Solicitud

Método: GET

URI:

  • Estilo virtual-host: https://{bucket-name}.s3.latam-scl-x.datageneral.cl/

  • Estilo path: https://s3.latam-scl-x.datageneral.cl/{bucket-name}/

Encabezados:

  • Host: Requerido. Especifica el nombre del bucket (para virtual-host) o el host del servicio (para path-style).

  • Date: Requerido. Fecha y hora de la solicitud.

  • Authorization: Requerido. Contiene la firma de la solicitud para la autenticación.

Parámetros de la URI:

  • delimiter: Opcional. Un carácter delimitador usado para agrupar objetos. Común para simular una jerarquía de directorios.

  • encoding-type: Opcional. Especifica la codificación de caracteres para las claves de los objetos en la respuesta. Los valores válidos son url.

  • marker: Opcional. Especifica el objeto desde el cual comenzar el listado.

  • max-keys: Opcional. El número máximo de claves que se retornarán en la respuesta. El valor predeterminado y el máximo es 1000.

  • prefix: Opcional. Filtra los objetos que comienzan con el prefijo especificado.

  • requestPayer: Opcional. Si se establece en requester, indica que el solicitante pagará por la solicitud y la transferencia de datos.

  • start-after: Opcional. Especifica el objeto después del cual comenzar el listado.

Cuerpo de la solicitud:

  • Vacío. No se requiere un cuerpo de solicitud para listar objetos.

Respuesta

Códigos de estado:

  • 200 OK: La solicitud fue exitosa.

Encabezados de la respuesta:

  • Date: Fecha y hora de la respuesta.

  • x-amz-request-id: Un identificador único para la solicitud.

  • x-amz-id-2: Un identificador único extendido para la solicitud.

  • Server: Información sobre el servidor que procesó la solicitud.

  • Content-Type: El tipo de contenido de la respuesta, que será application/xml.

Cuerpo de la respuesta:

Contiene un documento XML con la lista de objetos.

<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01">
  <Name>nombre-del-bucket</Name>
  <Prefix>prefijo-opcional</Prefix>
  <Marker>marcador-opcional</Marker>
  <MaxKeys>1000</MaxKeys>
  <IsTruncated>true|false</IsTruncated>
  <Contents>
    <Key>nombre-del-objeto-1</Key>
    <LastModified>2024-07-28T18:00:00.000Z</LastModified>
    <ETag>"xxxxxxxxxxxxxxxxxxxxxxxxxxxx"</ETag>
    <Size>1024</Size>
    <StorageClass>STANDARD</StorageClass>
  </Contents>
  <Contents>
    <Key>nombre-del-objeto-2</Key>
    <LastModified>2024-07-27T18:00:00.000Z</LastModified>
    <ETag>"yyyyyyyyyyyyyyyyyyyyyyyyyyyy"</ETag>
    <Size>2048</Size>
    <StorageClass>STANDARD</StorageClass>
  </Contents>
  <CommonPrefixes>
    <Prefix>prefijo-comun/</Prefix>
  </CommonPrefixes>
</ListBucketResult>

Donde:

  • Name: El nombre del bucket.

  • Prefix: El prefijo usado para filtrar los resultados (si se especificó).

  • Marker: El marcador usado para la paginación (si se especificó).

  • MaxKeys: El número máximo de claves solicitadas.

  • IsTruncated: Un valor booleano que indica si la lista está truncada. Si es true, se necesitan peticiones adicionales para obtener la lista completa.

  • Contents: Una lista de objetos.

    • Key: El nombre del objeto.

    • LastModified: La fecha y hora en que se modificó por última vez el objeto.

    • ETag: El ETag del objeto.

    • Size: El tamaño del objeto en bytes.

    • StorageClass: La clase de almacenamiento del objeto.

  • CommonPrefixes: Una lista de prefijos comunes (si se usó un delimitador).

Ejemplos

Ejemplo de solicitud (sin parámetros):

GET / HTTP/1.1
Host: my-bucket.s3.latam-scl-x.datageneral.cl
Date: Thu, 29 Jul 2024 19:00:00 GMT
Authorization: AWS AKIAIOSFODNN7EXAMPLE:QWxhZGVpbjEgXA==

Ejemplo de respuesta:

HTTP/1.1 200 OK
Date: Thu, 29 Jul 2024 19:00:01 GMT
Content-Type: application/xml
x-amz-request-id: 65423A7B884B82F1
Server: MyS3Server

<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01">
  <Name>my-bucket</Name>
  <IsTruncated>false</IsTruncated>
  <Contents>
    <Key>objeto1.txt</Key>
    <LastModified>2024-07-29T18:00:00.000Z</LastModified>
    <ETag>"xxxxxxxxxxxxxxxxxxxxxxxxxxxx"</ETag>
    <Size>1024</Size>
    <StorageClass>STANDARD</StorageClass>
  </Contents>
  <Contents>
    <Key>objeto2.jpg</Key>
    <LastModified>2024-07-28T18:00:00.000Z</LastModified>
    <ETag>"yyyyyyyyyyyyyyyyyyyyyyyyyyyy"</ETag>
    <Size>2048</Size>
    <StorageClass>STANDARD</StorageClass>
  </Contents>
</ListBucketResult>

Ejemplo de solicitud (con prefijo y delimitador):

GET /?prefix=fotos/&delimiter=/ HTTP/1.1
Host: my-bucket.s3.latam-scl-x.datageneral.cl
Date: Thu, 29 Jul 2024 19:00:00 GMT
Authorization: AWS AKIAIOSFODNN7EXAMPLE:QWxhZGVpbjEgXA==

Ejemplo de respuesta:

HTTP/1.1 200 OK
Date: Thu, 29 Jul 2024 19:00:01 GMT
Content-Type: application/xml
x-amz-request-id: 65423A7B884B82F1
Server: MyS3Server

<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01">
  <Name>my-bucket</Name>
  <Prefix>fotos/</Prefix>
  <Delimiter>/</Delimiter>
  <IsTruncated>false</IsTruncated>
  <Contents>
    <Key>fotos/vacaciones.jpg</Key>
    <LastModified>2024-07-29T10:00:00.000Z</LastModified>
    <ETag>"zzzzzzzzzzzzzzzzzzzzzzzz"</ETag>
    <Size>4096</Size>
    <StorageClass>STANDARD</StorageClass>
  </Contents>
  <CommonPrefixes>
    <Prefix>fotos/familia/</Prefix>
  </CommonPrefixes>
</ListBucketResult>
AnteriorGetBucketPolicySiguienteListObjectsV2

Última actualización