Todos os produtos
Search

Este produto

    Object Storage Service:list objects in a bucket using ListObjectsV2

    Central de documentação

    Object Storage Service:list objects in a bucket using ListObjectsV2

    Última atualização: Jul 03, 2026

    A operação ListObjectsV2 (GetBucketV2) lista objetos em um bucket e retorna metadados como chave, tamanho, ETag e data da última modificação.

    Observações

    • Para listar todos os objetos de um bucket, é necessária a permissão oss:ListObjects.

    • A operação ListObjectsV2 (GetBucketV2) não retorna metadados personalizados do objeto.

    • Se o armazenamento de logs ou a consulta de logs em tempo real estiverem ativados, esta operação será registrada como GetBucket.

    • O faturamento da operação ListObjectsV2 (GetBucketV2) segue o modelo de solicitação de API PUT.

    • Por padrão, uma única resposta retorna até 100 objetos. Use NextContinuationToken e continuation-token para paginar todos os resultados.

    • Com o versionamento ativado, sobrescrever ou excluir objetos pode acumular marcadores de exclusão e versões anteriores. Configure regras de ciclo de vida para limpar periodicamente esses marcadores e versões anteriores desnecessárias, mantendo o desempenho da listagem.

    Sintaxe da solicitação

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

    Parâmetros da solicitação

    Nome

    Tipo

    Obrigatório

    Exemplo

    Descrição

    list-type

    Número

    Sim

    2

    Versão da operação. Defina como 2.

    delimiter

    String

    Não

    /

    Caractere usado para agrupar chaves de objetos. Chaves que compartilham um prefixo comum até a primeira ocorrência do delimitador são agrupadas em uma única entrada CommonPrefixes.

    Valor padrão: Nenhum

    start-after

    String

    Não

    b

    Chave do objeto a partir da qual a listagem começa. Os resultados iniciam na primeira chave alfabeticamente posterior a este valor.

    Usado para paginação. Comprimento máximo: 1.024 bytes.

    Caso o valor start-after especificado não exista, a listagem começará pela próxima chave em ordem alfabética.

    Valor padrão: Nenhum

    continuation-token

    String

    Não

    test1.txt

    Token que indica onde a listagem deve começar. Obtenha este valor no campo NextContinuationToken de uma resposta anterior da operação ListObjectsV2 (GetBucketV2).

    max-keys

    String

    Não

    100

    Quantidade máxima de objetos a retornar.

    Valores válidos: 1 a 1000

    Valor padrão: 100

    Nota

    • Se a resposta for truncada devido ao max-keys, use o NextContinuationToken retornado como continuation-token na próxima solicitação.

    • O número real de objetos retornados pode ser inferior ao max-keys. Nesse caso, use o NextContinuationToken da resposta como continuation-token para a próxima solicitação.

    prefix

    String

    Não

    a

    Prefixo que as chaves dos objetos retornados devem conter.

    Se definido como o nome de uma pasta, todos os arquivos e subpastas com esse prefixo serão listados recursivamente.

    Quando o prefixo é definido e o delimiter é configurado como /, apenas os arquivos da pasta são listados. Os nomes das subpastas aparecem em CommonPrefixes sem listagem recursiva.

    Exemplo: um bucket contém fun/test.jpg, fun/movie/001.avi e fun/movie/007.avi. Definir o prefixo como fun/ retorna os três itens. Definir o prefixo como fun/ com o delimiter / retorna fun/test.jpg e fun/movie/.

    Nota

    • Comprimento máximo: 1.024 bytes.

    • O prefixo não pode começar com barra (/). Se deixado em branco, todos os objetos do bucket serão listados.

    • As chaves retornadas ainda contêm o prefixo.

    Valor padrão: Nenhum

    encoding-type

    String

    Não

    url

    Tipo de codificação para a resposta.

    Valor padrão: Nenhum

    Valor válido: url

    Nota

    Se os valores de delimiter, start-after, prefix, NextContinuationToken ou Key contiverem caracteres de controle não suportados pelo XML 1.0, especifique o encoding-type para codificá-los na resposta.

    fetch-owner

    Booleano

    Não

    false

    Define se as informações do proprietário devem ser incluídas na resposta.

    Valores válidos: true, false

    • true: A resposta inclui informações do proprietário.

    • false: A resposta não inclui informações do proprietário.

    Valor padrão: false

    Elementos da resposta

    Nome

    Tipo

    Exemplo

    Descrição

    Contents

    Contêiner

    N/A

    Contêiner para os metadados de cada objeto retornado.

    Nó pai: ListBucketResult

    CommonPrefixes

    Contêiner

    N/A

    Se o parâmetro Delimiter for especificado, a resposta incluirá CommonPrefixes, listando prefixos de nomes de objetos que compartilham um prefixo comum e terminam com o delimitador.

    Nó pai: ListBucketResult

    Nó filho: Prefix

    Delimiter

    String

    /

    Caractere usado para agrupar chaves de objetos. Chaves que compartilham um prefixo comum até a primeira ocorrência do delimitador são agrupadas em uma única entrada CommonPrefixes.

    Nó pai: ListBucketResult

    EncodingType

    String

    N/A

    Tipo de codificação usado na resposta. Se Encoding-type for especificado na solicitação, Delimiter, StartAfter, Prefix, NextContinuationToken e Key serão codificados.

    Nó pai: ListBucketResult

    DisplayName

    String

    user_example

    Nome do proprietário do objeto.

    Nó pai: ListBucketResult.Contents.Owner

    ETag

    String

    5B3C1A2E053D763E1B002CC607C5A0FE1****

    O ETag identifica o conteúdo de um objeto e é gerado durante sua criação.

    Nó pai: ListBucketResult.Contents

    • Para objetos criados por uma solicitação PutObject, o valor do ETag corresponde ao hash MD5 do conteúdo do objeto.

    • Para objetos criados por outros métodos, o valor do ETag é um identificador único calculado com base em uma regra específica, mas não representa o hash MD5 do conteúdo.

    • O ETag permite verificar se o conteúdo do objeto foi alterado, porém não é adequado para verificação de integridade de dados. Use o hash MD5 para essa finalidade.

    ID

    String

    0022012****

    ID de usuário do proprietário do bucket.

    Nó pai: ListBucketResult.Contents.Owner

    IsTruncated

    String enumerada

    false

    Indica se os resultados retornados foram truncados.

    Valores válidos: true, false

    • true: Nem todos os resultados foram retornados nesta chamada.

    • false: Todos os resultados foram retornados nesta chamada.

    Nó pai: ListBucketResult

    Key

    String

    fun/test.jpg

    Chave do objeto.

    Nó pai: ListBucketResult.Contents

    LastModified

    Data e hora

    2012-02-24T08:42:32.000Z

    Data e hora da última modificação do objeto.

    Nó pai: ListBucketResult.Contents

    ListBucketResult

    Contêiner

    N/A

    Contêiner para os resultados de uma solicitação GetBucket.

    Nós filhos: Name, Prefix, StartAfter, MaxKeys, Delimiter, IsTruncated, NextContinuationToken, Contents

    Nó pai: Nenhum

    StartAfter

    String

    test1.txt

    Se você especificar o parâmetro StartAfter na solicitação, a resposta incluirá o elemento StartAfter.

    MaxKeys

    String

    100

    Número máximo de resultados retornados na resposta.

    Nó pai: ListBucketResult

    Name

    String

    examplebucket

    Nome do bucket.

    Nó pai: ListBucketResult

    Owner

    Contêiner

    N/A

    Contêiner com informações sobre o proprietário do bucket.

    Nós filhos: DisplayName, ID

    Nó pai: ListBucketResult.Contents

    Prefix

    String

    fun/

    Prefixo dos resultados da consulta.

    Nó pai: ListBucketResult

    Type

    String

    Normal

    Tipo do objeto.

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

    Nó pai: ListBucketResult.Contents

    Size

    String

    344606

    Tamanho do objeto em bytes.

    Nó pai: ListBucketResult.Contents

    StorageClass

    String

    Standard

    Classe de armazenamento do objeto.

    Nó pai: ListBucketResult.Contents

    SealedTime

    Data e hora

    2020-05-21T12:07:15.000Z

    Momento em que o objeto foi selado. Retornado apenas para objetos anexáveis selados.

    Nó pai: ListBucketResult.Contents

    ContinuationToken

    String

    test1.txt

    Se você especificar o parâmetro ContinuationToken na solicitação, a resposta incluirá o elemento ContinuationToken.

    Nó pai: ListBucketResult

    KeyCount

    Número

    6

    Quantidade de chaves retornadas. Se Delimiter for especificado, KeyCount representa a soma dos elementos Key e CommonPrefixes.

    Nó pai: ListBucketResult

    NextContinuationToken

    String

    CgJiYw--

    Token para recuperar a próxima página de resultados. Use este valor como continuation-token na próxima solicitação ListObjectsV2 (GetBucketV2).

    Nó pai: ListBucketResult

    RestoreInfo

    String

    ongoing-request="true"

    Estado de restauração do objeto.

      Nó pai: ListBucketResult.Contents

      Exemplos

      • Solicitação simples

        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

        Resposta de exemplo

        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>

      • Solicitação com o 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

        Resposta de exemplo

        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>

      • Solicitação com os parâmetros prefix e 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

        Resposta de exemplo

        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>

      • Envie uma solicitação com os parâmetros start-after, max-keys e 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

        Resposta de exemplo

        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>

      SDK

      SDKs disponíveis para esta operação:

      Ferramenta de linha de comando ossutil

      O comando correspondente no ossutil é list-objects-v2 (get-bucket-v2).