Listar objetos em um bucket - API GetBucket ListObjects - Object Storage Service: Central de Documentação do Alibaba Cloud

Observações de uso

A operação GetBucket (ListObjects) foi substituída pela GetBucketV2 (ListObjectsV2). Use a GetBucketV2 (ListObjectsV2) em novas aplicações. O OSS ainda oferece suporte à GetBucket (ListObjects). A documentação da GetBucketV2 (ListObjectsV2) está disponível em ListObjectsV2 (GetBucketV2).
Metadados personalizados do objeto não são retornados na resposta a uma solicitação GetBucket (ListObjects).
A GetBucket (ListObjects) é uma operação no nível do bucket. Cada chamada é faturada como uma solicitação PUT com base na classe de armazenamento do bucket (Solicitações de API PUT).
Se o versionamento estiver ativado, sobrescrever ou excluir objetos cria marcadores de exclusão e versões anteriores. Para evitar degradação de desempenho ao listar objetos, configure regras de ciclo de vida para remover periodicamente marcadores de exclusão e versões anteriores desnecessários.

Sintaxe da solicitação

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

Cabeçalhos da solicitação

Esta operação utiliza apenas cabeçalhos de solicitação comuns, como Authorization e Host. Consulte Cabeçalhos de solicitação comuns.

Parâmetros da solicitação

Nome	Tipo	Obrigatório	Exemplo	Descrição
delimiter	String	Não	/	Agrupa nomes de objetos. Objetos com a mesma string entre o prefixo e a primeira ocorrência do delimitador são agrupados em um elemento CommonPrefixes. Valor padrão: nenhum.
marker	String	Não	test1.txt	Objeto a partir do qual a operação de listagem começa. Os objetos são retornados em ordem alfabética após o marker especificado. Usado para paginação. Deve ter menos de 1.024 bytes. Mesmo que o marker não exista, a listagem inicia a partir do próximo objeto em ordem alfabética. Valor padrão: nenhum.
max-keys	String	Não	200	Número máximo de objetos a serem retornados. Se os resultados forem truncados, a resposta incluirá um valor NextMarker para paginação. Valores válidos: 1 a 1000. Valor padrão: 100.
prefix	String	Não	fun	Lista apenas objetos cujos nomes contenham este prefixo. Deve ter menos de 1.024 bytes. As chaves retornadas incluem o prefixo. Defina o prefix como um nome de diretório lista todos os objetos e subdiretórios recursivamente. Se você também definir o delimiter como uma barra (/), apenas os objetos no diretório serão listados. Os nomes dos subdiretórios são retornados em CommonPrefixes, e seu conteúdo não é listado. Por exemplo, suponha que um bucket contenha três objetos: fun/test.jpg, fun/movie/001.avi e fun/movie/007.avi. Se você definir o prefix como fun/, os três objetos serão retornados. Se definir o prefix como fun/ e o delimiter como uma barra (/), fun/test.jpg e fun/movie/ serão retornados. Valor padrão: nenhum.
encoding-type	String	Não	url	Tipo de codificação do conteúdo na resposta. Valor padrão: nenhum. Valor válido: url Importante Os valores de delimiter, marker, prefix, NextMarker e Key são codificados em UTF-8. Especifique o encoding-type para codificar valores que contenham caracteres de controle não suportados pelo XML 1.0.

Elementos da resposta

Nome	Tipo	Exemplo	Descrição
ListBucketResult	Container	N/A	Contêiner para os resultados de uma solicitação GetBucket. Nós filhos: Name, Prefix, Marker, MaxKeys, Delimiter, IsTruncated, Nextmarker e Contents Nó pai: Nenhum
Name	String	oss-example	Nome do bucket. Nó pai: ListBucketResult
Prefix	String	fun/	Prefixo dos resultados da consulta. Nós pais: ListBucketResult ou CommonPrefixes
Marker	String	test1.txt	Posição inicial desta operação GetBucket (ListObjects). Nó pai: ListBucketResult
MaxKeys	String	100	Número máximo de resultados retornados na resposta. Nó pai: ListBucketResult
Delimiter	String	/	Caractere usado para agrupar nomes de objetos. Objetos com a mesma string entre o prefixo e a primeira ocorrência do Delimiter são agrupados em um elemento CommonPrefixes. Nó pai: ListBucketResult
EncodingType	String	url	Tipo de codificação usado para os resultados retornados. Se você especificar o parâmetro encoding-type na solicitação, os elementos Delimiter, Marker, Prefix, NextMarker e Key na resposta serão codificados. Nó pai: ListBucketResult
IsTruncated	String enumerada	false	Indica se os resultados retornados foram truncados. Valores válidos: true e false true: Nem todos os resultados foram retornados. false: Todos os resultados foram retornados. Nó pai: ListBucketResult
NextMarker	String	test100.txt	Posição inicial da próxima listagem. Nó pai: ListBucketResult
Contents	Container	N/A	Contêiner para os metadados de cada objeto retornado. Nó pai: ListBucketResult
Key	String	fun/test.jpg	Chave do objeto. Nó pai: ListBucketResult.Contents
TransitionTime	Time	2024-04-23T07:21:42.000Z	Momento em que o objeto foi transferido para a classe de armazenamento Cold Archive ou Deep Cold Archive com base em uma regra de ciclo de vida. Nota Se você excluir um objeto Cold Archive ou Deep Cold Archive mais de 180 dias após a conversão, nenhuma taxa de exclusão antecipada será cobrada. Se excluir o objeto dentro de 180 dias após a conversão, uma taxa de exclusão antecipada será aplicada. Este campo não pode ser usado para determinar o momento em que um objeto é convertido para a classe de armazenamento IA ou Archive por uma regra de ciclo de vida. O cumprimento do requisito de duração mínima de armazenamento para objetos IA ou Archive depende da hora `Last-Modified`. Nó pai: ListBucketResult.Contents
SealedTime	Time	2020-05-21T12:07:15.000Z	Momento em que a operação de selagem foi executada no objeto. Nota Este campo é retornado apenas para objetos anexáveis criados por AppendObject que foram selados. Nó pai: ListBucketResult.Contents
LastModified	Time	2012-02-24T08:42:32.000Z	Data da última modificação do objeto. Nota A duração mínima de armazenamento para objetos na classe Infrequent Access é de 30 dias. A duração é calculada a partir da hora Last-Modified do objeto. Se você excluir um objeto mais de 30 dias após sua hora Last-Modified, nenhuma taxa de exclusão antecipada será cobrada. A duração mínima de armazenamento para objetos na classe Archive Storage é de 60 dias. A duração é calculada a partir da hora Last-Modified do objeto. Se você excluir um objeto mais de 60 dias após sua hora Last-Modified, nenhuma taxa de exclusão antecipada será cobrada. Nó pai: ListBucketResult.Contents
ETag	String	5B3C1A2E053D763E1B002CC607C5A0FE1****	Entity tag (ETag), gerada na criação do objeto para identificar seu conteúdo. Para um objeto criado por uma solicitação PutObject, o valor ETag é o hash MD5 do conteúdo do objeto. Para um objeto criado por outros métodos, o ETag é um valor único calculado por uma regra específica, não sendo o hash MD5 do conteúdo do objeto. Use ETags para detectar alterações de conteúdo, não para verificar integridade de dados. Nó pai: ListBucketResult.Contents
Type	String	Normal	Tipo do objeto. Valores válidos: Normal: Objeto criado por um upload simples. Multipart: Objeto criado por um upload multipart. Appendable: Objeto criado por um upload de anexo. Symlink: Link simbólico criado pela operação PutSymlink.
Size	String	344606	Tamanho do objeto retornado em bytes. Nó pai: ListBucketResult.Contents
StorageClass	String	Standard	Classe de armazenamento do objeto. Nó pai: ListBucketResult.Contents
RestoreInfo	String	ongoing-request="true”	Estado de restauração do objeto. Não retornado se nenhuma solicitação RestoreObject for enviada ou se a solicitação RestoreObject tiver expirado. Se uma solicitação RestoreObject for enviada, mas a operação de restauração não estiver concluída, o valor de RestoreInfo será `ongoing-request="true"`. Se uma solicitação RestoreObject for enviada e a operação de restauração estiver concluída, o valor de RestoreInfo será `ongoing-request="false", expiry-date="Thu, 24 Sep 2020 12:40:33 GMT"`. O campo `expiry-date` indica a hora de expiração do objeto restaurado.
Owner	Container	N/A	Contêiner para as informações do proprietário do bucket. Nós filhos: DisplayName e ID Nó pai: ListBucketResult.Contents
ID	String	0022012****	ID de usuário do proprietário do bucket. Nó pai: ListBucketResult.Contents.Owner
DisplayName	String	user_example	Nome do proprietário do objeto. Nó pai: ListBucketResult.Contents.Owner
CommonPrefixes	Container	N/A	Retornado quando o Delimiter é especificado. Contém um conjunto de prefixos de nomes de objetos que compartilham um prefixo comum e terminam com o delimitador. Nó pai: ListBucketResult

Outros cabeçalhos de resposta comuns, como x-oss-request-id e Content-Type, estão descritos em Cabeçalhos de resposta comuns.

Exemplos

Solicitação simples

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

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

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

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

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

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

Solicitação paginada que especifica o parâmetro marker

Neste exemplo, max-keys está definido como 2 para retornar no máximo dois 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

Resposta de exemplo

Use o valor NextMarker da resposta como marker para a próxima solicitação.

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>

Solicitação para um bucket que contém objetos Archive ou Cold Archive

Considere que o bucket examplebucket contenha os objetos exampleobject1.txt, exampleobject2.txt e exampleobject3.txt. Todos os três objetos pertencem à classe de armazenamento Cold Archive. Os estados dos três objetos são os seguintes:

Para exampleobject1.txt, nenhuma solicitação RestoreObject foi enviada ou a solicitação RestoreObject enviada expirou.
Para exampleobject2.txt, uma solicitação RestoreObject foi enviada e a operação de restauração está em andamento.
Para exampleobject3.txt, uma solicitação RestoreObject foi enviada e a operação de restauração foi concluída.

Solicitação de exemplo

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

Resposta de exemplo

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 chamar esta operação:

Ferramenta de linha de comando ossutil

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

Códigos de erro

Código de erro	Código de status HTTP	Descrição
NoSuchBucket	404	O bucket especificado não existe. Verifique se o nome do bucket é válido.
AccessDenied	403	Você não possui as permissões necessárias. Apenas o proprietário do bucket ou usuários com a permissão `oss:ListObjects` concedida podem executar esta operação.
InvalidArgument	400	O valor de max-keys é menor que 0 ou maior que 1.000. O comprimento do parâmetro prefix, marker ou delimiter é inválido.