Répertorier les objets d'un compartiment - API GetBucket ListObjects - Object Storage Service

Notes d'utilisation

L'opération GetBucket (ListObjects) est remplacée par GetBucketV2 (ListObjectsV2). Utilisez GetBucketV2 (ListObjectsV2) pour les nouvelles applications. OSS prend toujours en charge GetBucket (ListObjects). La documentation relative à GetBucketV2 (ListObjectsV2) est disponible dans la rubrique ListObjectsV2 (GetBucketV2).
Les métadonnées personnalisées des objets ne sont pas renvoyées dans la réponse d'une requête GetBucket (ListObjects).
GetBucket (ListObjects) est une opération au niveau du compartiment. Chaque appel est facturé comme une requête PUT, selon la classe de stockage du compartiment (voir la section Requêtes API PUT).
Si le versioning est activé, le remplacement ou la suppression d'objets crée des marqueurs de suppression et conserve les versions précédentes. Pour éviter une dégradation des performances lors du listage des objets, configurez des règles de cycle de vie afin de supprimer périodiquement les marqueurs de suppression et les versions précédentes inutiles.

Syntaxe de la requête

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

En-têtes de requête

Cette opération utilise uniquement les en-têtes de requête courants, tels que Authorization et Host. Pour plus d'informations, consultez la section En-têtes de requête courants.

Paramètres de requête

Nom	Type	Obligatoire	Exemple	Description
delimiter	String	Non	/	Regroupe les noms d'objets. Les objets partageant la même chaîne de caractères entre le préfixe et la première occurrence du délimiteur sont regroupés dans un élément CommonPrefixes. Valeur par défaut : aucune.
marker	String	Non	test1.txt	Objet à partir duquel commence l'opération de listage. Les objets sont renvoyés par ordre alphabétique après le marqueur spécifié. Utilisé pour la pagination. Doit être inférieur à 1 024 octets. Même si le marqueur n'existe pas, le listage commence à partir de l'objet suivant dans l'ordre alphabétique. Valeur par défaut : aucune.
max-keys	String	Non	200	Nombre maximal d'objets à renvoyer. Si les résultats sont tronqués, la réponse inclut une valeur NextMarker pour la pagination. Valeurs valides : 1 à 1 000. Valeur par défaut : 100.
prefix	String	Non	fun	Répertorie uniquement les objets dont le nom contient ce préfixe. Doit être inférieur à 1 024 octets. Les clés renvoyées incluent le préfixe. La définition du préfixe sur un nom de répertoire permet de lister récursivement tous les objets et sous-répertoires. Si vous définissez également le délimiteur sur une barre oblique (/), seuls les objets du répertoire sont répertoriés. Les noms des sous-répertoires sont renvoyés dans CommonPrefixes et leur contenu n'est pas listé. Par exemple, un compartiment contient trois objets : fun/test.jpg, fun/movie/001.avi et fun/movie/007.avi. Si vous définissez le préfixe sur fun/, les trois objets sont renvoyés. Si vous définissez le préfixe sur fun/ et le délimiteur sur une barre oblique (/), fun/test.jpg et fun/movie/ sont renvoyés. Valeur par défaut : aucune.
encoding-type	String	Non	url	Type d'encodage du contenu dans la réponse. Valeur par défaut : aucune. Valeur valide : url Important Les valeurs de delimiter, marker, prefix, NextMarker et Key sont encodées en UTF-8. Spécifiez encoding-type pour encoder les valeurs contenant des caractères de contrôle non pris en charge par XML 1.0.

Éléments de réponse

Nom	Type	Exemple	Description
ListBucketResult	Container	S.O.	Conteneur pour les résultats d'une requête GetBucket. Nœuds enfants : Name, Prefix, Marker, MaxKeys, Delimiter, IsTruncated, Nextmarker et Contents Nœud parent : Aucun
Name	String	oss-example	Nom du compartiment. Nœud parent : ListBucketResult
Prefix	String	fun/	Préfixe des résultats de la requête. Nœuds parents : ListBucketResult ou CommonPrefixes
Marker	String	test1.txt	Position de départ de cette opération GetBucket (ListObjects). Nœud parent : ListBucketResult
MaxKeys	String	100	Nombre maximal de résultats renvoyés dans la réponse. Nœud parent : ListBucketResult
Delimiter	String	/	Caractère utilisé pour regrouper les noms d'objets. Les objets partageant la même chaîne de caractères entre le préfixe et la première occurrence du délimiteur sont regroupés dans un élément CommonPrefixes. Nœud parent : ListBucketResult
EncodingType	String	url	Type d'encodage utilisé pour les résultats renvoyés. Si vous spécifiez le paramètre encoding-type dans la requête, les éléments Delimiter, Marker, Prefix, NextMarker et Key de la réponse sont encodés. Nœud parent : ListBucketResult
IsTruncated	Enumerated string	false	Indique si les résultats renvoyés sont tronqués. Valeurs valides : true et false true : Tous les résultats ne sont pas renvoyés. false : Tous les résultats sont renvoyés. Nœud parent : ListBucketResult
NextMarker	String	test100.txt	Position de départ du listage suivant. Nœud parent : ListBucketResult
Contents	Container	S.O.	Conteneur pour les métadonnées de chaque objet renvoyé. Nœud parent : ListBucketResult
Key	String	fun/test.jpg	Clé de l'objet. Nœud parent : ListBucketResult.Contents
TransitionTime	Time	2024-04-23T07:21:42.000Z	Date à laquelle l'objet a été transféré vers la classe de stockage Cold Archive ou Deep Cold Archive en fonction d'une règle de cycle de vie. Remarque Si vous supprimez un objet Cold Archive ou Deep Cold Archive plus de 180 jours après sa conversion, aucun frais de suppression anticipée n'est facturé. Si vous supprimez l'objet dans les 180 jours suivant sa conversion, des frais de suppression anticipée sont appliqués. Ce champ ne peut pas être utilisé pour déterminer la date à laquelle un objet a été converti vers la classe de stockage IA ou Archive par une règle de cycle de vie. Le respect de la durée minimale de stockage pour un objet IA ou Archive dépend de la date `Last-Modified`. Nœud parent : ListBucketResult.Contents
SealedTime	Time	2020-05-21T12:07:15.000Z	Date à laquelle l'opération de scellement a été effectuée sur l'objet. Remarque Ce champ est renvoyé uniquement pour les objets ajoutables créés par AppendObject qui ont été scellés. Nœud parent : ListBucketResult.Contents
LastModified	Time	2012-02-24T08:42:32.000Z	Date de dernière modification de l'objet. Remarque La durée minimale de stockage pour les objets de la classe de stockage Infrequent Access est de 30 jours. Cette durée est calculée à partir de la date Last-Modified de l'objet. Si vous supprimez un objet plus de 30 jours après sa date Last-Modified, aucun frais de suppression anticipée n'est facturé. La durée minimale de stockage pour les objets de la classe de stockage Archive est de 60 jours. Cette durée est calculée à partir de la date Last-Modified de l'objet. Si vous supprimez un objet plus de 60 jours après sa date Last-Modified, aucun frais de suppression anticipée n'est facturé. Nœud parent : ListBucketResult.Contents
ETag	String	5B3C1A2E053D763E1B002CC607C5A0FE1****	Tag d'entité (ETag), généré lors de la création de l'objet pour identifier son contenu. Pour un objet créé par une requête PutObject, la valeur ETag correspond au hachage MD5 du contenu de l'objet. Pour un objet créé par d'autres méthodes, l'ETag est une valeur unique calculée selon une règle spécifique, et non le hachage MD5 du contenu de l'objet. Utilisez les ETags pour détecter les modifications de contenu, et non pour vérifier l'intégrité des données. Nœud parent : ListBucketResult.Contents
Type	String	Normal	Type d'objet. Valeurs valides : Normal : L'objet est créé par un chargement simple. Multipart : L'objet est créé par un chargement multipartie. Appendable : L'objet est créé par un chargement par ajout. Symlink : Le lien symbolique est créé par l'opération PutSymlink.
Size	String	344606	Taille de l'objet renvoyé, en octets. Nœud parent : ListBucketResult.Contents
StorageClass	String	Standard	Classe de stockage de l'objet. Nœud parent : ListBucketResult.Contents
RestoreInfo	String	ongoing-request="true”	État de restauration de l'objet. Non renvoyé si aucune requête RestoreObject n'a été envoyée, ou si la requête RestoreObject a expiré. Si une requête RestoreObject a été envoyée mais que l'opération de restauration n'est pas terminée, la valeur de RestoreInfo est `ongoing-request="true"`. Si une requête RestoreObject a été envoyée et que l'opération de restauration est terminée, la valeur de RestoreInfo est `ongoing-request="false", expiry-date="Thu, 24 Sep 2020 12:40:33 GMT"`. Le champ `expiry-date` indique la date d'expiration de l'objet restauré.
Owner	Container	S.O.	Conteneur pour les informations relatives au propriétaire du compartiment. Nœuds enfants : DisplayName et ID Nœud parent : ListBucketResult.Contents
ID	String	0022012****	ID utilisateur du propriétaire du compartiment. Nœud parent : ListBucketResult.Contents.Owner
DisplayName	String	user_example	Nom du propriétaire de l'objet. Nœud parent : ListBucketResult.Contents.Owner
CommonPrefixes	Container	S.O.	Renvoyé lorsque Delimiter est spécifié. Contient un ensemble de préfixes de noms d'objets partageant un préfixe commun et se terminant par le délimiteur. Nœud parent : ListBucketResult

Les autres en-têtes de réponse courants, tels que x-oss-request-id et Content-Type, sont décrits dans la section En-têtes de réponse courants.

Exemples

Requête 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

Exemple de réponse

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>

Requête avec le paramètre 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

Exemple de réponse

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>

Requête avec les paramètres prefix et 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

Exemple de réponse

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>

Requête paginée spécifiant le paramètre marker

Dans cet exemple, max-keys est défini sur 2 afin de renvoyer un maximum de deux objets.

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

Exemple de réponse

Utilisez la valeur NextMarker de la réponse comme marqueur pour la requête suivante.

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>

Requête pour un compartiment contenant des objets Archive ou Cold Archive

Supposons que le compartiment examplebucket contienne les objets exampleobject1.txt, exampleobject2.txt et exampleobject3.txt. Ces trois objets appartiennent à la classe de stockage Cold Archive. Leur état est le suivant :

Pour exampleobject1.txt, aucune requête RestoreObject n'a été envoyée, ou la requête RestoreObject envoyée a expiré.
Pour exampleobject2.txt, une requête RestoreObject a été envoyée et l'opération de restauration est en cours.
Pour exampleobject3.txt, une requête RestoreObject a été envoyée et l'opération de restauration est terminée.

Exemple de requête

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

Exemple de réponse

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 disponibles pour appeler cette opération :

Outil de ligne de commande ossutil

La commande ossutil correspondante est list-objects (get-bucket).

Codes d'erreur

Code d'erreur	Code d'état HTTP	Description
NoSuchBucket	404	Le compartiment spécifié n'existe pas. Vérifiez la validité du nom du compartiment.
AccessDenied	403	Vous ne disposez pas des autorisations requises. Seul le propriétaire du compartiment ou les utilisateurs ayant reçu l'autorisation `oss:ListObjects` peuvent effectuer cette opération.
InvalidArgument	400	La valeur de max-keys est inférieure à 0 ou supérieure à 1 000. La longueur du paramètre prefix, marker ou delimiter n'est pas valide.