List objects in a bucket - GetBucket ListObjects API - Object Storage Service

Enumera la información de todos los objetos en un bucket, incluido el nombre del objeto, el tamaño y la hora de la última modificación.

Notas de uso

La operación GetBucket (ListObjects) ha sido reemplazada por GetBucketV2 (ListObjectsV2). Utilice GetBucketV2 (ListObjectsV2) para nuevas aplicaciones. OSS aún admite GetBucket (ListObjects). GetBucketV2 (ListObjectsV2) se documenta en ListObjectsV2 (GetBucketV2).
Los metadatos personalizados de los objetos no se devuelven en la respuesta a una solicitud GetBucket (ListObjects).
GetBucket (ListObjects) es una operación a nivel de bucket. Cada llamada se factura como una solicitud PUT según la clase de almacenamiento del bucket (PUT API requests).
Si el control de versiones está habilitado, sobrescribir o eliminar objetos genera marcadores de eliminación y versiones anteriores. Para evitar la degradación del rendimiento al enumerar objetos, configure lifecycle rules para quitar periódicamente los marcadores de eliminación y las versiones anteriores que ya no sean necesarios.

Sintaxis de la solicitud

GET / HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue

Encabezados de solicitud

Esta operación utiliza únicamente encabezados de solicitud comunes, como Authorization y Host. Common request headers.

Parámetros de solicitud

Nombre	Tipo	Obligatorio	Ejemplo	Descripción
delimiter	String	No	/	Agrupa los nombres de los objetos. Los objetos que comparten la misma cadena desde el prefijo hasta la primera aparición del delimitador se agrupan en un elemento CommonPrefixes. Valor predeterminado: ninguno.
marker	String	No	test1.txt	El objeto a partir del cual comienza la operación de listado. Los objetos se devuelven en orden alfabético después del marcador especificado. Se utiliza para la paginación. Debe ser menor a 1,024 bytes. Incluso si el marcador no existe, el listado comienza desde el siguiente objeto en orden alfabético. Valor predeterminado: ninguno.
max-keys	String	No	200	Número máximo de objetos a devolver. Si los resultados se truncan, la respuesta incluye un valor NextMarker para la paginación. Valores válidos: de 1 a 1000. Valor predeterminado: 100.
prefix	String	No	fun	Enumera únicamente los objetos cuyos nombres contienen este prefijo. Debe ser menor a 1,024 bytes. Las claves devueltas incluyen el prefijo. Establecer prefix con el nombre de un directorio enumera todos los objetos y subdirectorios de forma recursiva. Si también establece delimiter como una barra diagonal (/), solo se enumeran los objetos dentro del directorio. Los nombres de los subdirectorios se devuelven en CommonPrefixes y su contenido no se enumera. Por ejemplo, un bucket contiene tres objetos: fun/test.jpg, fun/movie/001.avi y fun/movie/007.avi. Si establece prefix como fun/, se devuelven los tres objetos. Si establece prefix como fun/ y delimiter como una barra diagonal (/), se devuelven fun/test.jpg y fun/movie/. Valor predeterminado: ninguno.
encoding-type	String	No	url	El tipo de codificación del contenido en la respuesta. Valor predeterminado: ninguno. Valor válido: url Importante Los valores de delimiter, marker, prefix, NextMarker y Key están codificados en UTF-8. Especifique encoding-type para codificar valores que contengan caracteres de control no admitidos por XML 1.0.

Elementos de respuesta

Nombre	Tipo	Ejemplo	Descripción
ListBucketResult	Container	N/A	El contenedor para los resultados de una solicitud GetBucket. Nodos secundarios: Name, Prefix, Marker, MaxKeys, Delimiter, IsTruncated, Nextmarker y Contents Nodo principal: Ninguna
Name	String	oss-example	El nombre del bucket. Nodo principal: ListBucketResult
Prefix	String	fun/	El prefijo de los resultados de la consulta. Nodos principales: ListBucketResult o CommonPrefixes
Marker	String	test1.txt	La posición inicial de esta operación GetBucket (ListObjects). Nodo principal: ListBucketResult
MaxKeys	String	100	El número máximo de resultados devueltos en la respuesta. Nodo principal: ListBucketResult
Delimiter	String	/	El carácter utilizado para agrupar los nombres de los objetos. Los objetos que comparten la misma cadena desde el prefijo hasta la primera aparición de Delimiter se agrupan en un elemento CommonPrefixes. Nodo principal: ListBucketResult
EncodingType	String	url	El tipo de codificación utilizado para los resultados devueltos. Si especifica el parámetro encoding-type en la solicitud, los elementos Delimiter, Marker, Prefix, NextMarker y Key en la respuesta se codifican. Nodo principal: ListBucketResult
IsTruncated	Enumerated string	false	Indica si los resultados devueltos están truncados. Valores válidos: true y false true: No se devolvieron todos los resultados. false: Se devolvieron todos los resultados. Nodo principal: ListBucketResult
NextMarker	String	test100.txt	La posición inicial del siguiente listado. Nodo principal: ListBucketResult
Contents	Container	N/A	El contenedor para los metadatos de cada objeto devuelto. Nodo principal: ListBucketResult
Key	String	fun/test.jpg	La clave del objeto. Nodo principal: ListBucketResult.Contents
TransitionTime	Time	2024-04-23T07:21:42.000Z	La hora en que el objeto pasó a la clase de almacenamiento Cold Archive o Deep Cold Archive según una regla de ciclo de vida. Nota Si elimina un objeto Cold Archive o Deep Cold Archive más de 180 días después de su conversión, no se cobra ninguna tarifa por eliminación anticipada. Si elimina el objeto dentro de los 180 días posteriores a su conversión, se aplica una tarifa por eliminación anticipada. Este campo no se puede utilizar para determinar la hora en que un objeto se convierte a la clase de almacenamiento IA o Archive mediante una regla de ciclo de vida. El cumplimiento del requisito de duración mínima de almacenamiento para un objeto IA o Archive depende de la hora `Last-Modified`. Nodo principal: ListBucketResult.Contents
SealedTime	Time	2020-05-21T12:07:15.000Z	La hora en que se realizó la operación de sellado en el objeto. Nota Este campo se devuelve únicamente para objetos anexables creados mediante AppendObject que han sido sellados. Nodo principal: ListBucketResult.Contents
LastModified	Time	2012-02-24T08:42:32.000Z	La hora de la última modificación del objeto. Nota La duración mínima de almacenamiento para objetos en la clase de almacenamiento Infrequent Access es de 30 días. La duración se calcula a partir de la hora Last-Modified del objeto. Si elimina un objeto más de 30 días después de su hora Last-Modified, no se cobra ninguna tarifa por eliminación anticipada. La duración mínima de almacenamiento para objetos en la clase de almacenamiento Archive Storage es de 60 días. La duración se calcula a partir de la hora Last-Modified del objeto. Si elimina un objeto más de 60 días después de su hora Last-Modified, no se cobra ninguna tarifa por eliminación anticipada. Nodo principal: ListBucketResult.Contents
ETag	String	5B3C1A2E053D763E1B002CC607C5A0FE1****	La etiqueta de entidad (ETag), generada durante la creación del objeto para identificar su contenido. Para un objeto creado mediante una solicitud PutObject, el valor ETag es el hash MD5 del contenido del objeto. Para un objeto creado por otros métodos, el ETag es un valor único calculado mediante una regla específica, no el hash MD5 del contenido del objeto. Utilice los ETags para detectar cambios en el contenido, no para verificar la integridad de los datos. Nodo principal: ListBucketResult.Contents
Type	String	Normal	El tipo de objeto. Valores válidos: Normal: El objeto se crea mediante una carga simple. Multipart: El objeto se crea mediante una carga multiparte. Appendable: El objeto se crea mediante una carga por anexión. Symlink: El enlace simbólico se crea mediante la operación PutSymlink.
Size	String	344606	El tamaño del objeto devuelto en bytes. Nodo principal: ListBucketResult.Contents
StorageClass	String	Standard	La clase de almacenamiento del objeto. Nodo principal: ListBucketResult.Contents
RestoreInfo	String	ongoing-request="true”	El estado de restauración del objeto. No se devuelve si no se envió ninguna solicitud RestoreObject, o si la solicitud RestoreObject ha caducado. Si se envió una solicitud RestoreObject pero la operación de restauración no ha finalizado, el valor de RestoreInfo es `ongoing-request="true"`. Si se envió una solicitud RestoreObject y la operación de restauración finalizó, el valor de RestoreInfo es `ongoing-request="false", expiry-date="Thu, 24 Sep 2020 12:40:33 GMT"`. El campo `expiry-date` indica la hora de caducidad del objeto restaurado.
Owner	Container	N/A	Contenedor para la información del propietario del bucket. Nodos secundarios: DisplayName e ID Nodo principal: ListBucketResult.Contents
ID	String	0022012****	El ID de usuario del propietario del bucket. Nodo principal: ListBucketResult.Contents.Owner
DisplayName	String	user_example	El nombre del propietario del objeto. Nodo principal: ListBucketResult.Contents.Owner
CommonPrefixes	Container	N/A	Se devuelve cuando se especifica Delimiter. Contiene un conjunto de prefijos de nombres de objetos que comparten un prefijo común y terminan con el delimitador. Nodo principal: ListBucketResult

Otros encabezados de respuesta comunes, como x-oss-request-id y Content-Type, se describen en Common response headers.

Ejemplos

Solicitud simple

GET / HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 24 Feb 2012 08:43:27 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Respuesta de ejemplo

HTTP/1.1 200 OK
x-oss-request-id: 534B371674E88A4D8906****
Date: Fri, 24 Feb 2012 08:43:27 GMT
Content-Type: application/xml
Content-Length: 1866
Connection: keep-alive
Server: AliyunOSS
<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult xmlns=”http://doc.oss-cn-hangzhou.aliyuncs.com”>
<Name>examplebucket</Name>
<Prefix></Prefix>
<Marker></Marker>
<MaxKeys>100</MaxKeys>
<Delimiter></Delimiter>
<IsTruncated>false</IsTruncated>
<Contents>
      <Key>fun/movie/001.avi</Key>
      <TransitionTime>2024-04-23T07:21:42.000Z</TransitionTime>
      <LastModified>2012-02-24T08:43:07.000Z</LastModified>
      <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag>
      <Type>Normal</Type>
      <Size>344606</Size>
      <StorageClass>Standard</StorageClass>
      <Owner>
          <ID>0022012****</ID>
          <DisplayName>user-example</DisplayName>
      </Owner>
</Contents>
<Contents>
      <Key>fun/movie/007.avi</Key>
      <LastModified>2012-02-24T08:43:27.000Z</LastModified>
      <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag>
      <Type>Normal</Type>
      <Size>344606</Size>
      <StorageClass>Standard</StorageClass>
      <Owner>
          <ID>0022012****</ID>
          <DisplayName>user-example</DisplayName>
      </Owner>
</Contents>
<Contents>
      <Key>fun/test.jpg</Key>
      <LastModified>2012-02-24T08:42:32.000Z</LastModified>
      <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag>
      <Type>Normal</Type>
      <Size>344606</Size>
      <StorageClass>Standard</StorageClass>
      <Owner>
          <ID>0022012****</ID>
          <DisplayName>user-example</DisplayName>
      </Owner>
</Contents>
<Contents>
      <Key>oss.jpg</Key>
      <LastModified>2012-02-24T06:07:48.000Z</LastModified>
      <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag>
      <Type>Normal</Type>
      <Size>344606</Size>
      <StorageClass>Standard</StorageClass>
      <Owner>
          <ID>0022012****</ID>
          <DisplayName>user-example</DisplayName>
      </Owner>
</Contents>
</ListBucketResult>

Solicitud con el parámetro prefix

GET /?prefix=fun HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 24 Feb 2012 08:43:27 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Respuesta de ejemplo

HTTP/1.1 200 OK
x-oss-request-id: 534B371674E88A4D8906****
Date: Fri, 24 Feb 2012 08:43:27 GMT
Content-Type: application/xml
Content-Length: 1464
Connection: keep-alive
Server: AliyunOSS
<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult xmlns=”http://doc.oss-cn-hangzhou.aliyuncs.com”>
<Name>examplebucket</Name>
<Prefix>fun</Prefix>
<Marker></Marker>
<MaxKeys>100</MaxKeys>
<Delimiter></Delimiter>
<IsTruncated>false</IsTruncated>
<Contents>
      <Key>fun/movie/001.avi</Key>
      <LastModified>2012-02-24T08:43:07.000Z</LastModified>
      <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag>
      <Type>Normal</Type>
      <Size>344606</Size>
      <StorageClass>Standard</StorageClass>
      <Owner>
          <ID>0022012****</ID>
          <DisplayName>user_example</DisplayName>
      </Owner>
</Contents>
<Contents>
      <Key>fun/movie/007.avi</Key>
      <LastModified>2012-02-24T08:43:27.000Z</LastModified>
      <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag>
      <Type>Normal</Type>
      <Size>344606</Size>
      <StorageClass>Standard</StorageClass>
      <Owner>
          <ID>0022012****</ID>
          <DisplayName>user_example</DisplayName>
      </Owner>
</Contents>
<Contents>
      <Key>fun/test.jpg</Key>
      <LastModified>2012-02-24T08:42:32.000Z</LastModified>
      <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag>
      <Type>Normal</Type>
      <Size>344606</Size>
      <StorageClass>Standard</StorageClass>
      <Owner>
          <ID>0022012****</ID>
          <DisplayName>user_example</DisplayName>
      </Owner>
</Contents>
</ListBucketResult>

Solicitud con los parámetros prefix y delimiter

GET /?prefix=fun/&delimiter=/ HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 24 Feb 2012 08:43:27 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Respuesta de ejemplo

HTTP/1.1 200 OK
x-oss-request-id: 534B371674E88A4D8906****
Date: Fri, 24 Feb 2012 08:43:27 GMT
Content-Type: application/xml
Content-Length: 712
Connection: keep-alive
Server: AliyunOSS
<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult xmlns=”http://doc.oss-cn-hangzhou.aliyuncs.com”>
<Name>examplebucket</Name>
<Prefix>fun/</Prefix>
<Marker></Marker>
<MaxKeys>100</MaxKeys>
<Delimiter>/</Delimiter>
<IsTruncated>false</IsTruncated>
<Contents>
      <Key>fun/test.jpg</Key>
      <LastModified>2012-02-24T08:42:32.000Z</LastModified>
      <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag>
      <Type>Normal</Type>
      <Size>344606</Size>
      <StorageClass>Standard</StorageClass>
      <Owner>
          <ID>0022012****</ID>
          <DisplayName>user_example</DisplayName>
      </Owner>
</Contents>
<CommonPrefixes>
      <Prefix>fun/movie/</Prefix>
</CommonPrefixes>
</ListBucketResult>

Solicitud paginada que especifica el parámetro marker

En este ejemplo, max-keys se establece en 2 para devolver un máximo de dos objetos.

GET /?max-keys=2&marker=test1.txt HTTP/1.1
Host: examplebucket.oss-cn-shenzhen.aliyuncs.com
Accept-Encoding: identity
Accept: */*
Connection: keep-alive
User-Agent: aliyun-sdk-python/2.11.0(Darwin/18.2.0/x86_64;3.4.1)
date: Tue, 26 May 2020 08:39:48 GMT
authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Respuesta de ejemplo

Utilice el valor NextMarker de la respuesta como marcador para la siguiente solicitud.

HTTP/1.1 200 OK
Server: AliyunOSS
Date: Tue, 26 May 2020 08:39:48 GMT
Content-Type: application/xml
Content-Length: 1032
Connection: keep-alive
x-oss-request-id: 5ECCD5D4881816373582xxx
x-oss-server-time: 3

<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult>
  <Name>examplebucket</Name>
  <Prefix></Prefix>
  <Marker>test1.txt</Marker>
  <MaxKeys>2</MaxKeys>
  <Delimiter></Delimiter>
  <EncodingType>url</EncodingType>
  <IsTruncated>true</IsTruncated>
  <NextMarker>test100.txt</NextMarker>
  <Contents>
    <Key>test10.txt</Key>
    <LastModified>2020-05-26T07:50:18.000Z</LastModified>
    <ETag>"C4CA4238A0B923820DCC509A6F75****"</ETag>
    <Type>Normal</Type>
    <Size>1</Size>
    <StorageClass>Standard</StorageClass>
    <Owner>
      <ID>1305433xxx</ID>
      <DisplayName>1305433xxx</DisplayName>
    </Owner>
  </Contents>
  <Contents>
    <Key>test100.txt</Key>
    <LastModified>2020-05-26T07:50:20.000Z</LastModified>
    <ETag>"C4CA4238A0B923820DCC509A6F75****"</ETag>
    <Type>Normal</Type>
    <Size>1</Size>
    <StorageClass>Standard</StorageClass>
    <Owner>
      <ID>1305433xxx</ID>
      <DisplayName>1305433xxx</DisplayName>
    </Owner>
  </Contents>
</ListBucketResult>

Solicitud para un bucket que contiene objetos Archive o Cold Archive

Suponga que el bucket examplebucket contiene los objetos exampleobject1.txt, exampleobject2.txt y exampleobject3.txt. Los tres objetos pertenecen a la clase de almacenamiento Cold Archive. Los estados de los tres objetos son los siguientes:

Para exampleobject1.txt, no se ha enviado ninguna solicitud RestoreObject, o la solicitud RestoreObject enviada ha caducado.
Para exampleobject2.txt, se ha enviado una solicitud RestoreObject y la operación de restauración está en curso.
Para exampleobject3.txt, se ha enviado una solicitud RestoreObject y la operación de restauración ha finalizado.

Solicitud de ejemplo

GET / HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 24 Feb 2012 08:43:27 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Respuesta de ejemplo

HTTP/1.1 200 OK
x-oss-request-id: 534B371674E88A4D8906****
Date: Date: Fri, 24 Feb 2012 08:43:27 GMT
Content-Type: application/xml
Content-Length: 1866
Connection: keep-alive
Server: AliyunOSS
<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult xmlns=”http://doc.oss-cn-hangzhou.aliyuncs.com”>
  <Name>examplebucket</Name>
  <Prefix></Prefix>
  <Marker></Marker>
  <MaxKeys></MaxKeys>
  <Delimiter></Delimiter>
  <IsTruncated>false</IsTruncated>
  <Contents>
        <Key>exampleobject1.txt</Key>
        <LastModified>2020-06-22T11:42:32.000Z</LastModified>
        <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag>
        <Type>Normal</Type>
        <Size>344606</Size>
        <StorageClass>ColdArchive</StorageClass>
        <Owner>
            <ID>0022012****</ID>
            <DisplayName>user-example</DisplayName>
        </Owner>
  </Contents>
  <Contents>
        <Key>exampleobject2.txt</Key>
        <LastModified>2020-06-22T11:42:32.000Z</LastModified>
        <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag>
        <Type>Normal</Type>
        <Size>344606</Size>
        <StorageClass>Standard</StorageClass>
        <RestoreInfo>ongoing-request="true"</RestoreInfo>
        <Owner>
            <ID>0022012****</ID>
            <DisplayName>user-example</DisplayName>
        </Owner>
  </Contents>
  <Contents>
        <Key>exampleobject3.txt</Key>
        <LastModified>2020-06-22T11:42:32.000Z</LastModified>
        <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag>
        <Type>Normal</Type>
        <Size>344606</Size>
        <StorageClass>Standard</StorageClass>
        <RestoreInfo>ongoing-request="false", expiry-date="Thu, 24 Sep 2020 12:40:33 GMT"</RestoreInfo>
        <Owner>
            <ID>0022012****</ID>
            <DisplayName>user-example</DisplayName>
        </Owner>
  </Contents>
</ListBucketResult>

SDK

SDKs para invocar esta operación:

Herramienta de línea de comandos ossutil

El comando correspondiente de ossutil es list-objects (get-bucket).

Códigos de error

Código de error	Código de estado HTTP	Descripción
NoSuchBucket	404	El bucket especificado no existe. Compruebe si el nombre del bucket es válido.
AccessDenied	403	No cuenta con los permisos obligatorios. Solo el propietario del bucket o los usuarios a los que se les otorgó el permiso `oss:ListObjects` pueden realizar esta operación.
InvalidArgument	400	El valor de max-keys es menor que 0 o mayor que 1,000. La longitud del parámetro prefix, marker o delimiter no es válida.