ListObjectsV2 GetBucketV2 - list bucket objects OSS API - Object Storage Service

Notes

Pour répertorier tous les objets d'un bucket, vous devez disposer de l'autorisation oss:ListObjects.
L'opération ListObjectsV2 (GetBucketV2) ne renvoie pas les métadonnées personnalisées des objets.
Si le stockage des journaux ou la requête de journaux en temps réel est activé, cette opération est enregistrée sous le nom GetBucket.
L'opération ListObjectsV2 (GetBucketV2) est facturée comme une requête API PUT.
Par défaut, une réponse unique renvoie jusqu'à 100 objets. Utilisez NextContinuationToken et continuation-token pour parcourir tous les résultats via la pagination.
Si le versioning est activé, le remplacement ou la suppression d'objets peut entraîner l'accumulation de marqueurs de suppression et de versions précédentes. Configurez des règles de cycle de vie pour nettoyer périodiquement les marqueurs de suppression et les versions précédentes inutiles afin de maintenir les performances de liste.

Syntaxe de la requête

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

Paramètres de requête

Nom	Type	Obligatoire	Exemple	Description
list-type	Number	Oui	2	La version de l'opération. Définissez la valeur sur 2.
delimiter	String	Non	/	Le caractère utilisé pour regrouper les clés d'objet. Les clés partageant un préfixe commun jusqu'à la première occurrence du délimiteur sont regroupées dans une seule entrée CommonPrefixes. Valeur par défaut : Aucune
start-after	String	Non	b	La clé d'objet après laquelle la liste commence. Les résultats débutent à partir de la première clé alphabétiquement supérieure à cette valeur. Utilisé pour la pagination. Longueur maximale : 1 024 octets. Si la valeur start-after spécifiée n'existe pas, la liste commence à partir de la clé suivante dans l'ordre alphabétique. Valeur par défaut : Aucune
continuation-token	String	Non	test1.txt	Le jeton à partir duquel la liste commence. Récupérez cette valeur depuis NextContinuationToken dans une réponse précédente de ListObjectsV2 (GetBucketV2).
max-keys	String	Non	100	Le nombre maximal d'objets à renvoyer. Valeurs valides : 1 à 1000 Valeur par défaut : 100 Remarque Si la réponse est tronquée en raison de max-keys, utilisez le `NextContinuationToken` renvoyé comme `continuation-token` pour la requête suivante. Le nombre réel d'objets renvoyés peut être inférieur à max-keys. Dans ce cas, utilisez le `NextContinuationToken` de la réponse comme `continuation-token` pour la requête suivante.
prefix	String	Non	a	Le préfixe que les clés d'objet renvoyées doivent contenir. S'il est défini sur un nom de dossier, tous les fichiers et sous-dossiers avec ce préfixe sont répertoriés de manière récursive. Si prefix est défini et delimiter est défini sur /, seuls les fichiers du dossier sont répertoriés. Les noms des sous-dossiers apparaissent dans CommonPrefixes sans liste récursive. Exemple : un bucket contient fun/test.jpg, fun/movie/001.avi et fun/movie/007.avi. La définition de prefix sur fun/ renvoie les trois éléments. La définition de prefix sur fun/ avec delimiter / renvoie fun/test.jpg et fun/movie/. Remarque Longueur maximale : 1 024 octets. Le préfixe ne peut pas commencer par une barre oblique (/). S'il est laissé vide, tous les objets du bucket sont répertoriés. Les clés renvoyées contiennent toujours le préfixe. Valeur par défaut : Aucune
encoding-type	String	Non	url	Le type d'encodage pour la réponse. Valeur par défaut : Aucune Valeur valide : url Remarque Si delimiter, start-after, prefix, NextContinuationToken ou Key contiennent des caractères de contrôle non pris en charge par XML 1.0, spécifiez encoding-type pour les encoder dans la réponse.
fetch-owner	Boolean	Non	false	Indique si les informations sur le propriétaire doivent être incluses dans la réponse. Valeurs valides : true, false true : La réponse inclut les informations sur le propriétaire. false : La réponse n'inclut pas les informations sur le propriétaire. Valeur par défaut : false

Éléments de réponse

Nom	Type	Exemple	Description
Contents	Container	N/A	Un conteneur pour les métadonnées de chaque objet renvoyé. Nœud parent : ListBucketResult
CommonPrefixes	Container	N/A	Si le paramètre Delimiter est spécifié, la réponse inclut CommonPrefixes, qui répertorie les préfixes de noms d'objet partageant un préfixe commun et se terminant par le délimiteur. Nœud parent : ListBucketResult Nœud enfant : Prefix
Delimiter	String	/	Le caractère utilisé pour regrouper les clés d'objet. Les clés partageant un préfixe commun jusqu'à la première occurrence du délimiteur sont regroupées dans une seule entrée CommonPrefixes. Nœud parent : ListBucketResult
EncodingType	String	N/A	Le type d'encodage utilisé dans la réponse. Si Encoding-type est spécifié dans la requête, Delimiter, StartAfter, Prefix, NextContinuationToken et Key sont encodés. Nœud parent : ListBucketResult
DisplayName	String	user_example	Le nom du propriétaire de l'objet. Nœud parent : ListBucketResult.Contents.Owner
ETag	String	5B3C1A2E053D763E1B002CC607C5A0FE1****	L'ETag identifie le contenu d'un objet et est généré lors de la création de l'objet. Nœud parent : ListBucketResult.Contents Pour les objets créés par une requête PutObject, la valeur ETag est le hachage MD5 du contenu de l'objet. Pour les objets créés par d'autres méthodes, la valeur ETag est une valeur unique calculée selon une règle spécifique, mais il ne s'agit pas du hachage MD5 du contenu de l'objet. L'ETag permet de vérifier si le contenu de l'objet a changé, mais ne convient pas à la vérification de l'intégrité des données. Utilisez plutôt le hachage MD5.
ID	String	0022012****	L'ID utilisateur du propriétaire du bucket. Nœud parent : ListBucketResult.Contents.Owner
IsTruncated	Enumerated string	false	Indique si les résultats renvoyés sont tronqués. Valeurs valides : true, false true : Tous les résultats ne sont pas renvoyés cette fois-ci. false : Tous les résultats sont renvoyés cette fois-ci. Nœud parent : ListBucketResult
Key	String	fun/test.jpg	La clé de l'objet. Nœud parent : ListBucketResult.Contents
LastModified	Time	2012-02-24T08:42:32.000Z	La date de dernière modification de l'objet. Nœud parent : ListBucketResult.Contents
ListBucketResult	Container	N/A	Le conteneur pour les résultats d'une requête GetBucket. Nœuds enfants : Name, Prefix, StartAfter, MaxKeys, Delimiter, IsTruncated, NextContinuationToken, Contents Nœud parent : Aucun
StartAfter	String	test1.txt	Si vous spécifiez le paramètre StartAfter dans la requête, la réponse inclut l'élément StartAfter.
MaxKeys	String	100	Le nombre maximal de résultats renvoyés dans la réponse. Nœud parent : ListBucketResult
Name	String	examplebucket	Le nom du bucket. Nœud parent : ListBucketResult
Owner	Container	N/A	Un conteneur pour les informations sur le propriétaire du bucket. Nœuds enfants : DisplayName, ID Nœud parent : ListBucketResult.Contents
Prefix	String	fun/	Le préfixe des résultats de la requête. Nœud parent : ListBucketResult
Type	String	Normal	Le type d'objet. Valeurs valides : Normal, Multipart, Appendable, Symlink. Nœud parent : ListBucketResult.Contents
Size	String	344606	La taille de l'objet en octets. Nœud parent : ListBucketResult.Contents
StorageClass	String	Standard	La classe de stockage de l'objet. Nœud parent : ListBucketResult.Contents
SealedTime	Time	2020-05-21T12:07:15.000Z	L'heure à laquelle l'objet a été scellé. Renvoyé uniquement pour les objets appendables scellés. Nœud parent : ListBucketResult.Contents
ContinuationToken	String	test1.txt	Si vous spécifiez le paramètre ContinuationToken dans la requête, la réponse inclut l'élément ContinuationToken. Nœud parent : ListBucketResult
KeyCount	Number	6	Le nombre de clés renvoyées. Si Delimiter est spécifié, KeyCount est la somme des éléments Key et CommonPrefixes. Nœud parent : ListBucketResult
NextContinuationToken	String	CgJiYw--	Le jeton pour récupérer la page de résultats suivante. Utilisez cette valeur comme continuation-token dans la prochaine requête ListObjectsV2 (GetBucketV2). Nœud parent : ListBucketResult
RestoreInfo	String	ongoing-request="true"	L'état de restauration de l'objet. Nœud parent : ListBucketResult.Contents

Exemples

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

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

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

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

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

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

Envoyer une requête avec les paramètres start-after, max-keys et 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

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

SDK pour cette opération :

Outil de ligne de commande ossutil

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