ListObjectsV2

Documentación: ListObjectsV2

Descripción

La operación ListObjectsV2 retorna una lista de algunos o todos los objetos en un bucket. Esta es la versión 2 de la operación ListObjects y se recomienda su uso sobre la versión anterior. ListObjectsV2 admite todos los parámetros de ListObjects y agrega algunos parámetros nuevos. 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.

• 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.

• fetch-owner: Opcional. Si se establece en true, el elemento Owner se incluirá en la respuesta para cada objeto.

• list-type: Opcional. Predeterminado a 2.

• continuation-token: Opcional. Token para la paginación.

• start-after: Opcional. Comienza a listar después de este key.

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>
  <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>
    <Owner>
        <ID>xxxxxxxxxxxxxxxxxxxxx</ID>
        <DisplayName>Nombre del Propietario</DisplayName>
    </Owner>
  </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>
     <Owner>
        <ID>xxxxxxxxxxxxxxxxxxxxx</ID>
        <DisplayName>Nombre del Propietario</DisplayName>
    </Owner>
  </Contents>
  <CommonPrefixes>
    <Prefix>prefijo-comun/</Prefix>
  </CommonPrefixes>
  <NextContinuationToken>...</NextContinuationToken>
  <ContinuationToken>...</ContinuationToken>
  <KeyCount>2</KeyCount>
</ListBucketResult>

Donde:

• Name: El nombre del bucket.

• Prefix: El prefijo usado para filtrar los resultados (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.

  • Owner: El propietario del objeto (si fetch-owner es true).

    • ID: El ID del propietario.

    • DisplayName: El nombre para mostrar del propietario.

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

• NextContinuationToken: El token que se usará en la siguiente solicitud para obtener la siguiente página de resultados.

• ContinuationToken: El token de continuación que se usó en la solicitud.

• KeyCount: La cantidad de objetos devueltos en esta respuesta. Puede ser menor que MaxKeys incluso si no está truncado.

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>
  <KeyCount>2</KeyCount>
</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>
  <KeyCount>1</KeyCount>
</ListBucketResult>