Todos los productos
Search

Este producto

    Object Storage Service:list objects in a bucket using ListObjectsV2

    Centro de documentos

    Object Storage Service:list objects in a bucket using ListObjectsV2

    Última actualización: Sep 03, 2026

    La operación ListObjectsV2 (GetBucketV2) lista los objetos de un bucket y devuelve metadatos como la clave, el tamaño, el ETag y la hora de última modificación.

    Notas

    • Para listar todos los objetos de un bucket, debe contar con el permiso oss:ListObjects.

    • La operación ListObjectsV2 (GetBucketV2) no devuelve metadatos personalizados del objeto.

    • Si log storage o real-time log query está habilitado, esta operación se registra como GetBucket.

    • La operación ListObjectsV2 (GetBucketV2) se factura como una PUT API request.

    • De forma predeterminada, una sola respuesta devuelve hasta 100 objetos. Utilice NextContinuationToken y continuation-token para paginar todos los resultados.

    • Si el control de versiones está habilitado, sobrescribir o eliminar objetos puede acumular marcadores de eliminación y versiones anteriores. Configure lifecycle rules para limpiar periódicamente los marcadores de eliminación y las versiones anteriores innecesarias, con el fin de mantener el rendimiento de la lista.

    Sintaxis de la solicitud

    GET /?list-type=2 HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue

    Parámetros de la solicitud

    Nombre

    Tipo

    Obligatorio

    Ejemplo

    Descripción

    list-type

    Number

    Sí

    2

    Versión de la operación. Establézcala en 2.

    delimiter

    String

    No

    /

    Carácter que se utiliza para agrupar claves de objetos. Las claves que comparten un prefijo común hasta la primera aparición del delimitador se agrupan en una sola entrada CommonPrefixes.

    Valor predeterminado: Ninguna

    start-after

    String

    No

    b

    Clave del objeto a partir de la cual comienza el listado. Los resultados inician desde la primera clave en orden alfabético posterior a este valor.

    Se usa para la paginación. Longitud máxima: 1,024 bytes.

    Si el valor start-after especificado no existe, el listado comienza desde la siguiente clave en orden alfabético.

    Valor predeterminado: Ninguna

    continuation-token

    String

    No

    test1.txt

    Token desde el cual comienza el listado. Obtenga este valor de NextContinuationToken en una respuesta anterior de ListObjectsV2 (GetBucketV2).

    max-keys

    String

    No

    100

    Número máximo de objetos que se devolverán.

    Valores válidos: 1 a 1000

    Valor predeterminado: 100

    Nota

    • Si la respuesta se trunca debido a max-keys, utilice el NextContinuationToken devuelto como continuation-token para la siguiente solicitud.

    • El número real de objetos devueltos puede ser menor que max-keys. En ese caso, utilice NextContinuationToken de la respuesta como continuation-token para la siguiente solicitud.

    prefix

    String

    No

    a

    Prefijo que deben contener las claves de los objetos devueltos.

    Si se establece con el nombre de una carpeta, se listan recursivamente todos los archivos y subcarpetas con este prefijo.

    Si se define prefix y delimiter se establece en /, solo se listan los archivos de la carpeta. Los nombres de las subcarpetas aparecen en CommonPrefixes sin un listado recursivo.

    Ejemplo: un bucket contiene fun/test.jpg, fun/movie/001.avi y fun/movie/007.avi. Establecer prefix en fun/ devuelve los tres. Establecer prefix en fun/ con delimiter / devuelve fun/test.jpg y fun/movie/.

    Nota

    • Longitud máxima: 1,024 bytes.

    • El prefijo no puede comenzar con una barra diagonal (/). Si se deja vacío, se listan todos los objetos del bucket.

    • Las claves devueltas aún contienen el prefijo.

    Valor predeterminado: Ninguna

    encoding-type

    String

    No

    url

    Tipo de codificación para la respuesta.

    Valor predeterminado: Ninguna

    Valor válido: url

    Nota

    Si los valores de delimiter, start-after, prefix, NextContinuationToken o Key contienen caracteres de control no compatibles con XML 1.0, especifique encoding-type para codificarlos en la respuesta.

    fetch-owner

    Boolean

    No

    false

    Indica si se incluye la información del propietario en la respuesta.

    Valores válidos: true, false

    • true: La respuesta incluye la información del propietario.

    • false: La respuesta no incluye la información del propietario.

    Valor predeterminado: false

    Elementos de la respuesta

    Nombre

    Tipo

    Ejemplo

    Descripción

    Contents

    Container

    N/A

    Contenedor para los metadatos de cada objeto devuelto.

    Nodo padre: ListBucketResult

    CommonPrefixes

    Container

    N/A

    Si se especifica el parámetro Delimiter, la respuesta incluye CommonPrefixes, que lista los prefijos de nombres de objetos que comparten un prefijo común y terminan con el delimitador.

    Nodo padre: ListBucketResult

    Nodo hijo: Prefix

    Delimiter

    String

    /

    Carácter utilizado para agrupar claves de objetos. Las claves que comparten un prefijo común hasta la primera aparición del delimitador se agrupan en una sola entrada CommonPrefixes.

    Nodo padre: ListBucketResult

    EncodingType

    String

    N/A

    Tipo de codificación utilizado en la respuesta. Si se especifica Encoding-type en la solicitud, se codifican Delimiter, StartAfter, Prefix, NextContinuationToken y Key.

    Nodo padre: ListBucketResult

    DisplayName

    String

    user_example

    Nombre del propietario del objeto.

    Nodo padre: ListBucketResult.Contents.Owner

    ETag

    String

    5B3C1A2E053D763E1B002CC607C5A0FE1****

    El ETag identifica el contenido de un objeto y se genera cuando se crea el objeto.

    Nodo padre: ListBucketResult.Contents

    • Para objetos creados mediante una solicitud PutObject, el valor ETag es el hash MD5 del contenido del objeto.

    • Para objetos creados por otros métodos, el valor ETag es un valor único calculado según una regla específica, pero no es el hash MD5 del contenido del objeto.

    • El ETag permite comprobar si el contenido del objeto ha cambiado, pero no es adecuado para la verificación de integridad de datos. Utilice el hash MD5 en su lugar.

    ID

    String

    0022012****

    ID de usuario del propietario del bucket.

    Nodo padre: ListBucketResult.Contents.Owner

    IsTruncated

    Enumerated string

    false

    Indica si los resultados devueltos están truncados.

    Valores válidos: true, false

    • true: No se han devuelto todos los resultados en esta ocasión.

    • false: Se han devuelto todos los resultados en esta ocasión.

    Nodo padre: ListBucketResult

    Key

    String

    fun/test.jpg

    Clave del objeto.

    Nodo padre: ListBucketResult.Contents

    LastModified

    Time

    2012-02-24T08:42:32.000Z

    Hora de la última modificación del objeto.

    Nodo padre: ListBucketResult.Contents

    ListBucketResult

    Container

    N/A

    Contenedor para los resultados de una solicitud GetBucket.

    Nodos hijos: Name, Prefix, StartAfter, MaxKeys, Delimiter, IsTruncated, NextContinuationToken, Contents

    Nodo padre: Ninguna

    StartAfter

    String

    test1.txt

    Si especifica el parámetro StartAfter en la solicitud, la respuesta incluye el elemento StartAfter.

    MaxKeys

    String

    100

    Número máximo de resultados devueltos en la respuesta.

    Nodo padre: ListBucketResult

    Name

    String

    examplebucket

    Nombre del bucket.

    Nodo padre: ListBucketResult

    Owner

    Container

    N/A

    Contenedor con información sobre el propietario del bucket.

    Nodos hijos: DisplayName, ID

    Nodo padre: ListBucketResult.Contents

    Prefix

    String

    fun/

    Prefijo de los resultados de la consulta.

    Nodo padre: ListBucketResult

    Type

    String

    Normal

    Tipo de objeto.

    Valores válidos: Normal, Multipart, Appendable, Symlink.

    Nodo padre: ListBucketResult.Contents

    Size

    String

    344606

    Tamaño del objeto en bytes.

    Nodo padre: ListBucketResult.Contents

    StorageClass

    String

    Standard

    Clase de almacenamiento del objeto.

    Nodo padre: ListBucketResult.Contents

    SealedTime

    Time

    2020-05-21T12:07:15.000Z

    Hora en la que se selló el objeto. Solo se devuelve para objetos anexables sellados.

    Nodo padre: ListBucketResult.Contents

    ContinuationToken

    String

    test1.txt

    Si especifica el parámetro ContinuationToken en la solicitud, la respuesta incluye el elemento ContinuationToken.

    Nodo padre: ListBucketResult

    KeyCount

    Number

    6

    Número de claves devueltas. Si se especifica Delimiter, KeyCount es la suma de los elementos Key y CommonPrefixes.

    Nodo padre: ListBucketResult

    NextContinuationToken

    String

    CgJiYw--

    Token para recuperar la siguiente página de resultados. Utilice este valor como continuation-token en la siguiente solicitud de ListObjectsV2 (GetBucketV2).

    Nodo padre: ListBucketResult

    RestoreInfo

    String

    ongoing-request="true"

    Estado restaurado del objeto.

    • No se devuelve si no se envió ninguna solicitud RestoreObject, o si la solicitud RestoreObject caducó.

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

    Nodo padre: ListBucketResult.Contents

    Ejemplos

    • Solicitud simple

      GET /?list-type=2 HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Thu, 17 Apr 2025 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>
    <MaxKeys>100</MaxKeys>
    <EncodingType>url</EncodingType>
    <IsTruncated>false</IsTruncated>
    <Contents>
        <Key>a</Key>
        <LastModified>2020-05-18T05:45:43.000Z</LastModified>
        <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
        <Size>25</Size>
        <StorageClass>STANDARD</StorageClass>
    </Contents>
    <Contents>
        <Key>a/b</Key>
        <LastModified>2020-05-18T05:45:47.000Z</LastModified>
        <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
        <Size>25</Size>
        <StorageClass>STANDARD</StorageClass>
    </Contents>
    <Contents>
        <Key>b</Key>
        <LastModified>2020-05-18T05:45:50.000Z</LastModified>
        <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
        <Size>25</Size>
        <StorageClass>STANDARD</StorageClass>
    </Contents>
    <Contents>
        <Key>b/c</Key>
        <LastModified>2020-05-18T05:45:54.000Z</LastModified>
        <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
        <Size>25</Size>
        <StorageClass>STANDARD</StorageClass>
    </Contents>
    <Contents>
        <Key>bc</Key>
        <LastModified>2020-05-18T05:45:59.000Z</LastModified>
        <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
        <Size>25</Size>
        <StorageClass>STANDARD</StorageClass>
    </Contents>
    <Contents>
        <Key>c</Key>
        <LastModified>2020-05-18T05:45:57.000Z</LastModified>
        <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
        <Size>25</Size>
        <StorageClass>STANDARD</StorageClass>
    </Contents>
    <KeyCount>6</KeyCount>
</ListBucketResult>

    • Solicitud con el parámetro prefix

      GET /?list-type=2&prefix=a HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Thu, 17 Apr 2025 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>a</Prefix>
    <MaxKeys>100</MaxKeys>
    <EncodingType>url</EncodingType>
    <IsTruncated>false</IsTruncated>
    <Contents>
        <Key>a</Key>
        <LastModified>2020-05-18T05:45:43.000Z</LastModified>
        <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
        <Size>25</Size>
        <StorageClass>STANDARD</StorageClass>
    </Contents>
    <Contents>
        <Key>a/b</Key>
        <LastModified>2020-05-18T05:45:47.000Z</LastModified>
        <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
        <Size>25</Size>
        <StorageClass>STANDARD</StorageClass>
    </Contents>
    <KeyCount>2</KeyCount>
</ListBucketResult>

    • Solicitud con los parámetros prefix y delimiter

      GET /?list-type=2&prefix=a/&delimiter=/ HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Thu, 17 Apr 2025 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>a/</Prefix>
    <MaxKeys>100</MaxKeys>
    <Delimiter>/</Delimiter>
    <EncodingType>url</EncodingType>
    <IsTruncated>false</IsTruncated>
    <Contents>
        <Key>a/b</Key>
        <LastModified>2020-05-18T05:45:47.000Z</LastModified>
        <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
        <Size>25</Size>
        <StorageClass>STANDARD</StorageClass>
    </Contents>
    <CommonPrefixes>
        <Prefix>a/b/</Prefix>
    </CommonPrefixes>
    <KeyCount>2</KeyCount>
</ListBucketResult>

    • Envío de una solicitud con los parámetros start-after, max-keys y fetch-owner

      GET /?list-type=2&start-after=b&max-keys=3&fetch-owner=true HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Thu, 17 Apr 2025 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></Prefix>
    <StartAfter>b</StartAfter>
    <MaxKeys>3</MaxKeys>
    <EncodingType>url</EncodingType>
    <IsTruncated>true</IsTruncated>
    <NextContinuationToken>CgJiYw--</NextContinuationToken>
    <Contents>
        <Key>b/c</Key>
        <LastModified>2020-05-18T05:45:54.000Z</LastModified>
        <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
        <Size>25</Size>
        <StorageClass>STANDARD</StorageClass>
        <Owner>
            <ID>1686240967192623</ID>
            <DisplayName>1686240967192623</DisplayName>
        </Owner>
    </Contents>
    <Contents>
        <Key>ba</Key>
        <LastModified>2020-05-18T11:17:58.000Z</LastModified>
        <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
        <Size>25</Size>
        <StorageClass>STANDARD</StorageClass>
        <Owner>
            <ID>1686240967192623</ID>
            <DisplayName>1686240967192623</DisplayName>
        </Owner>
    </Contents>
    <Contents>
        <Key>bc</Key>
        <LastModified>2020-05-18T05:45:59.000Z</LastModified>
        <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
        <Size>25</Size>
        <StorageClass>STANDARD</StorageClass>
        <Owner>
            <ID>1686240967192623</ID>
            <DisplayName>1686240967192623</DisplayName>
        </Owner>
    </Contents>
    <KeyCount>3</KeyCount>
</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

    SDK para esta operación:

    Herramienta de línea de comandos ossutil

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

    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 necesarios. Solo el propietario del bucket o los usuarios a los que se les concedió 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.