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

Última actualización