Liste des clés d'objet par programme - Amazon Simple Storage Service

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Liste des clés d'objet par programme

Dans Amazon S3, les clés peuvent être répertoriées par préfixe. Vous pouvez choisir un préfixe commun pour les noms des clés associées et marquer ces clés avec un caractère spécial délimitant la hiérarchie. Vous pouvez ensuite utiliser l'opération de liste pour sélectionner et parcourir les clés de manière hiérarchique. Cette méthode ressemble au stockage des fichiers dans les répertoires d'un système de fichiers.

Amazon S3 expose une opération de liste qui vous permet d'énumérer les clés contenues dans un compartiment. Les clés sont sélectionnées par compartiment et préfixe. Par exemple, prenez un compartiment appelé « dictionary » qui contient une clé pour chaque mot anglais. Vous devez faire un appel pour lister toutes les clés dans le compartiment qui commencent par la lettre « q ». Les résultats de la liste sont toujours renvoyés dans un ordre binaire UTF-8.

Les opérations de la liste SOAP et REST renvoient un document XML qui contient les noms des clés correspondantes et les informations sur l'objet identifié par chaque clé.

Note

La prise en charge de SOAP sur HTTP est obsolète, mais SOAP continue d'être disponible sur HTTP. Les nouvelles fonctions Amazon S3 ne sont pas prises en charge pour SOAP. Au lieu d'utiliser SOAP, nous vous recommandons d'utiliser l'API REST ou les AWS SDK.

Les groupes de clés qui partagent un préfixe se terminant par un délimiteur spécial peuvent être regroupés par ce préfixe commun pour les besoins de la liste. Cela permet aux applications d'organiser et de parcourir hiérarchiquement les clés, comme vous organiseriez des fichiers dans les répertoires d'un système de fichiers.

Par exemple, pour que le compartiment dictionnaire contienne plus que des mots anglais, vous devez former des clés en ajoutant un préfixe à chaque mot avec sa langue et un délimiteur, comme « French/logical ». Grâce à cette dénomination et à la fonction de liste hiérarchique, vous pouvez récupérer une liste de mots français. Vous pouvez également parcourir la liste de niveau supérieur des langues disponibles sans avoir à itérer sur toutes les clés d'intervention de manière lexicographique. Pour en savoir plus sur cet aspect de la liste, veuillez consulter Organisation des objets à l'aide de préfixes.

API REST

Si l'application l'exige, vous pouvez envoyer les demandes REST directement. Vous pouvez envoyer une demande GET pour renvoyer tout ou partie des objets d'un compartiment. Vous pouvez aussi utiliser des critères de sélection pour renvoyer un sous-ensemble d'objets d'un compartiment. Pour plus d’informations, consultez GET Bucket (List Objects) version 2 dans la Référence d’API Amazon Simple Storage Service..

Efficacité de l'implémentation d'une liste

Les performances de la liste ne sont pas significativement affectées par le nombre total de clés dans votre compartiment. Elles ne sont pas non plus affectées par la présence ou l'absence des arguments prefix, marker, maxkeys, ou delimiter.

Itération sur des résultats de plusieurs pages

Etant donné que les compartiments peuvent contenir un nombre presque illimité de clés, les résultats complets d'une requête de liste peuvent être très importants. Pour gérer d'importants ensembles de résultats, l'API Amazon S3 prend en charge la pagination afin de les scinder en plusieurs réponses. Chaque réponse de clés de liste renvoie une page de 1 000 clés maximum avec un indicateur spécifiant si la réponse est tronquée. Vous envoyez une série de demandes de clés de liste jusqu'à ce que vous ayez reçu toutes les clés. AWS Les bibliothèques wrapper du SDK fournissent la même pagination.

Exemples

Les exemples de code suivants montrent comment lister les objets dans un compartiment S3.

.NET
AWS SDK for .NET
Note

Il y en a plus sur GitHub. Trouvez l’exemple complet et découvrez comment le configurer et l’exécuter dans le référentiel d’exemples de code AWS.

/// <summary> /// Shows how to list the objects in an Amazon S3 bucket. /// </summary> /// <param name="client">An initialized Amazon S3 client object.</param> /// <param name="bucketName">The name of the bucket for which to list /// the contents.</param> /// <returns>A boolean value indicating the success or failure of the /// copy operation.</returns> public static async Task<bool> ListBucketContentsAsync(IAmazonS3 client, string bucketName) { try { var request = new ListObjectsV2Request { BucketName = bucketName, MaxKeys = 5, }; Console.WriteLine("--------------------------------------"); Console.WriteLine($"Listing the contents of {bucketName}:"); Console.WriteLine("--------------------------------------"); ListObjectsV2Response response; do { response = await client.ListObjectsV2Async(request); response.S3Objects .ForEach(obj => Console.WriteLine($"{obj.Key,-35}{obj.LastModified.ToShortDateString(),10}{obj.Size,10}")); // If the response is truncated, set the request ContinuationToken // from the NextContinuationToken property of the response. request.ContinuationToken = response.NextContinuationToken; } while (response.IsTruncated); return true; } catch (AmazonS3Exception ex) { Console.WriteLine($"Error encountered on server. Message:'{ex.Message}' getting list of objects."); return false; } }

Listez les objets avec un paginateur.

using System; using System.Threading.Tasks; using Amazon.S3; using Amazon.S3.Model; /// <summary> /// The following example lists objects in an Amazon Simple Storage /// Service (Amazon S3) bucket. /// </summary> public class ListObjectsPaginator { private const string BucketName = "doc-example-bucket"; public static async Task Main() { IAmazonS3 s3Client = new AmazonS3Client(); Console.WriteLine($"Listing the objects contained in {BucketName}:\n"); await ListingObjectsAsync(s3Client, BucketName); } /// <summary> /// This method uses a paginator to retrieve the list of objects in an /// an Amazon S3 bucket. /// </summary> /// <param name="client">An Amazon S3 client object.</param> /// <param name="bucketName">The name of the S3 bucket whose objects /// you want to list.</param> public static async Task ListingObjectsAsync(IAmazonS3 client, string bucketName) { var listObjectsV2Paginator = client.Paginators.ListObjectsV2(new ListObjectsV2Request { BucketName = bucketName, }); await foreach (var response in listObjectsV2Paginator.Responses) { Console.WriteLine($"HttpStatusCode: {response.HttpStatusCode}"); Console.WriteLine($"Number of Keys: {response.KeyCount}"); foreach (var entry in response.S3Objects) { Console.WriteLine($"Key = {entry.Key} Size = {entry.Size}"); } } } }
  • Pour plus de détails sur l'API, voir ListObjectsV2 dans le manuel de référence des AWS SDK for .NET API.

Bash
AWS CLI avec le script Bash
Note

Il y en a plus sur GitHub. Trouvez l’exemple complet et découvrez comment le configurer et l’exécuter dans le référentiel d’exemples de code AWS.

############################################################################### # function errecho # # This function outputs everything sent to it to STDERR (standard error output). ############################################################################### function errecho() { printf "%s\n" "$*" 1>&2 } ############################################################################### # function list_items_in_bucket # # This function displays a list of the files in the bucket with each file's # size. The function uses the --query parameter to retrieve only the key and # size fields from the Contents collection. # # Parameters: # $1 - The name of the bucket. # # Returns: # The list of files in text format. # And: # 0 - If successful. # 1 - If it fails. ############################################################################### function list_items_in_bucket() { local bucket_name=$1 local response response=$(aws s3api list-objects \ --bucket "$bucket_name" \ --output text \ --query 'Contents[].{Key: Key, Size: Size}') # shellcheck disable=SC2181 if [[ ${?} -eq 0 ]]; then echo "$response" else errecho "ERROR: AWS reports s3api list-objects operation failed.\n$response" return 1 fi }
  • Pour plus de détails sur l'API, voir ListObjectsV2 dans AWS CLI Command Reference.

C++
Kit SDK pour C++
Note

Il y en a plus sur GitHub. Trouvez l’exemple complet et découvrez comment le configurer et l’exécuter dans le référentiel d’exemples de code AWS.

bool AwsDoc::S3::ListObjects(const Aws::String &bucketName, const Aws::Client::ClientConfiguration &clientConfig) { Aws::S3::S3Client s3_client(clientConfig); Aws::S3::Model::ListObjectsRequest request; request.WithBucket(bucketName); auto outcome = s3_client.ListObjects(request); if (!outcome.IsSuccess()) { std::cerr << "Error: ListObjects: " << outcome.GetError().GetMessage() << std::endl; } else { Aws::Vector<Aws::S3::Model::Object> objects = outcome.GetResult().GetContents(); for (Aws::S3::Model::Object &object: objects) { std::cout << object.GetKey() << std::endl; } } return outcome.IsSuccess(); }
  • Pour plus de détails sur l'API, voir ListObjectsV2 dans le manuel de référence des AWS SDK for C++ API.

CLI
AWS CLI

L'exemple suivant utilise la list-objects commande pour afficher les noms de tous les objets du compartiment spécifié :

aws s3api list-objects --bucket text-content --query 'Contents[].{Key: Key, Size: Size}'

L'exemple utilise l'--queryargument pour filtrer la sortie list-objects jusqu'à la valeur clé et à la taille de chaque objet.

Pour plus d'informations sur les objets, consultez la section Travailler avec des objets Amazon S3 dans le manuel du développeur Amazon S3.

  • Pour plus de détails sur l'API, voir ListObjectsV2 dans AWS CLI Command Reference.

Go
Kit SDK for Go V2
Note

Il y en a plus sur GitHub. Trouvez l’exemple complet et découvrez comment le configurer et l’exécuter dans le référentiel d’exemples de code AWS.

// BucketBasics encapsulates the Amazon Simple Storage Service (Amazon S3) actions // used in the examples. // It contains S3Client, an Amazon S3 service client that is used to perform bucket // and object actions. type BucketBasics struct { S3Client *s3.Client } // ListObjects lists the objects in a bucket. func (basics BucketBasics) ListObjects(bucketName string) ([]types.Object, error) { result, err := basics.S3Client.ListObjectsV2(context.TODO(), &s3.ListObjectsV2Input{ Bucket: aws.String(bucketName), }) var contents []types.Object if err != nil { log.Printf("Couldn't list objects in bucket %v. Here's why: %v\n", bucketName, err) } else { contents = result.Contents } return contents, err }
  • Pour plus de détails sur l'API, voir ListObjectsV2 dans le manuel de référence des AWS SDK for Go API.

Java
Kit SDK pour Java 2.x
Note

Il y en a plus sur GitHub. Trouvez l’exemple complet et découvrez comment le configurer et l’exécuter dans le référentiel d’exemples de code AWS.

import software.amazon.awssdk.regions.Region; import software.amazon.awssdk.services.s3.S3Client; import software.amazon.awssdk.services.s3.model.ListObjectsRequest; import software.amazon.awssdk.services.s3.model.ListObjectsResponse; import software.amazon.awssdk.services.s3.model.S3Exception; import software.amazon.awssdk.services.s3.model.S3Object; import java.util.List; /** * Before running this Java V2 code example, set up your development * environment, including your credentials. * * For more information, see the following documentation topic: * * https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/get-started.html */ public class ListObjects { public static void main(String[] args) { final String usage = """ Usage: <bucketName>\s Where: bucketName - The Amazon S3 bucket from which objects are read.\s """; if (args.length != 1) { System.out.println(usage); System.exit(1); } String bucketName = args[0]; Region region = Region.US_EAST_1; S3Client s3 = S3Client.builder() .region(region) .build(); listBucketObjects(s3, bucketName); s3.close(); } public static void listBucketObjects(S3Client s3, String bucketName) { try { ListObjectsRequest listObjects = ListObjectsRequest .builder() .bucket(bucketName) .build(); ListObjectsResponse res = s3.listObjects(listObjects); List<S3Object> objects = res.contents(); for (S3Object myValue : objects) { System.out.print("\n The name of the key is " + myValue.key()); System.out.print("\n The object is " + calKb(myValue.size()) + " KBs"); System.out.print("\n The owner is " + myValue.owner()); } } catch (S3Exception e) { System.err.println(e.awsErrorDetails().errorMessage()); System.exit(1); } } // convert bytes to kbs. private static long calKb(Long val) { return val / 1024; } }

Lister les objets en utilisant la pagination.

import software.amazon.awssdk.regions.Region; import software.amazon.awssdk.services.s3.S3Client; import software.amazon.awssdk.services.s3.model.ListObjectsV2Request; import software.amazon.awssdk.services.s3.model.S3Exception; import software.amazon.awssdk.services.s3.paginators.ListObjectsV2Iterable; public class ListObjectsPaginated { public static void main(String[] args) { final String usage = """ Usage: <bucketName>\s Where: bucketName - The Amazon S3 bucket from which objects are read.\s """; if (args.length != 1) { System.out.println(usage); System.exit(1); } String bucketName = args[0]; Region region = Region.US_EAST_1; S3Client s3 = S3Client.builder() .region(region) .build(); listBucketObjects(s3, bucketName); s3.close(); } public static void listBucketObjects(S3Client s3, String bucketName) { try { ListObjectsV2Request listReq = ListObjectsV2Request.builder() .bucket(bucketName) .maxKeys(1) .build(); ListObjectsV2Iterable listRes = s3.listObjectsV2Paginator(listReq); listRes.stream() .flatMap(r -> r.contents().stream()) .forEach(content -> System.out.println(" Key: " + content.key() + " size = " + content.size())); } catch (S3Exception e) { System.err.println(e.awsErrorDetails().errorMessage()); System.exit(1); } } }
  • Pour plus de détails sur l'API, voir ListObjectsV2 dans le manuel de référence des AWS SDK for Java 2.x API.

JavaScript
SDK pour JavaScript (v3)
Note

Il y en a plus sur GitHub. Trouvez l’exemple complet et découvrez comment le configurer et l’exécuter dans le référentiel d’exemples de code AWS.

Répertoriez tous les objets dans votre compartiment. S'il existe plusieurs objets, IsTruncated ils NextContinuationToken seront utilisés pour parcourir la liste complète.

import { S3Client, // This command supersedes the ListObjectsCommand and is the recommended way to list objects. ListObjectsV2Command, } from "@aws-sdk/client-s3"; const client = new S3Client({}); export const main = async () => { const command = new ListObjectsV2Command({ Bucket: "my-bucket", // The default and maximum number of keys returned is 1000. This limits it to // one for demonstration purposes. MaxKeys: 1, }); try { let isTruncated = true; console.log("Your bucket contains the following objects:\n"); let contents = ""; while (isTruncated) { const { Contents, IsTruncated, NextContinuationToken } = await client.send(command); const contentsList = Contents.map((c) => ` • ${c.Key}`).join("\n"); contents += contentsList + "\n"; isTruncated = IsTruncated; command.input.ContinuationToken = NextContinuationToken; } console.log(contents); } catch (err) { console.error(err); } };
  • Pour plus de détails sur l'API, voir ListObjectsV2 dans le manuel de référence des AWS SDK for JavaScript API.

Kotlin
Kits SDK pour Kotlin
Note

Il y en a plus sur GitHub. Trouvez l’exemple complet et découvrez comment le configurer et l’exécuter dans le référentiel d’exemples de code AWS.

suspend fun listBucketObjects(bucketName: String) { val request = ListObjectsRequest { bucket = bucketName } S3Client { region = "us-east-1" }.use { s3 -> val response = s3.listObjects(request) response.contents?.forEach { myObject -> println("The name of the key is ${myObject.key}") println("The object is ${myObject.size?.let { calKb(it) }} KBs") println("The owner is ${myObject.owner}") } } } private fun calKb(intValue: Long): Long { return intValue / 1024 }
  • Pour plus de détails sur l'API, voir ListObjectsV2 dans le AWS SDK pour la référence de l'API Kotlin.

PHP
Kit SDK pour PHP
Note

Il y en a plus sur GitHub. Trouvez l’exemple complet et découvrez comment le configurer et l’exécuter dans le référentiel d’exemples de code AWS.

Listez les objets dans un compartiment.

$s3client = new Aws\S3\S3Client(['region' => 'us-west-2']); try { $contents = $this->s3client->listObjectsV2([ 'Bucket' => $this->bucketName, ]); echo "The contents of your bucket are: \n"; foreach ($contents['Contents'] as $content) { echo $content['Key'] . "\n"; } } catch (Exception $exception) { echo "Failed to list objects in $this->bucketName with error: " . $exception->getMessage(); exit("Please fix error with listing objects before continuing."); }
  • Pour plus de détails sur l'API, voir ListObjectsV2 dans le manuel de référence des AWS SDK for PHP API.

Python
Kit SDK pour Python (Boto3)
Note

Il y en a plus sur GitHub. Trouvez l’exemple complet et découvrez comment le configurer et l’exécuter dans le référentiel d’exemples de code AWS.

class ObjectWrapper: """Encapsulates S3 object actions.""" def __init__(self, s3_object): """ :param s3_object: A Boto3 Object resource. This is a high-level resource in Boto3 that wraps object actions in a class-like structure. """ self.object = s3_object self.key = self.object.key @staticmethod def list(bucket, prefix=None): """ Lists the objects in a bucket, optionally filtered by a prefix. :param bucket: The bucket to query. This is a Boto3 Bucket resource. :param prefix: When specified, only objects that start with this prefix are listed. :return: The list of objects. """ try: if not prefix: objects = list(bucket.objects.all()) else: objects = list(bucket.objects.filter(Prefix=prefix)) logger.info( "Got objects %s from bucket '%s'", [o.key for o in objects], bucket.name ) except ClientError: logger.exception("Couldn't get objects for bucket '%s'.", bucket.name) raise else: return objects
  • Pour plus de détails sur l'API, reportez-vous à la section ListObjectsV2 dans le manuel de référence de l'API AWS SDK for Python (Boto3).

Ruby
Kit SDK pour Ruby
Note

Il y en a plus sur GitHub. Trouvez l’exemple complet et découvrez comment le configurer et l’exécuter dans le référentiel d’exemples de code AWS.

require "aws-sdk-s3" # Wraps Amazon S3 bucket actions. class BucketListObjectsWrapper attr_reader :bucket # @param bucket [Aws::S3::Bucket] An existing Amazon S3 bucket. def initialize(bucket) @bucket = bucket end # Lists object in a bucket. # # @param max_objects [Integer] The maximum number of objects to list. # @return [Integer] The number of objects listed. def list_objects(max_objects) count = 0 puts "The objects in #{@bucket.name} are:" @bucket.objects.each do |obj| puts "\t#{obj.key}" count += 1 break if count == max_objects end count rescue Aws::Errors::ServiceError => e puts "Couldn't list objects in bucket #{bucket.name}. Here's why: #{e.message}" 0 end end # Example usage: def run_demo bucket_name = "doc-example-bucket" wrapper = BucketListObjectsWrapper.new(Aws::S3::Bucket.new(bucket_name)) count = wrapper.list_objects(25) puts "Listed #{count} objects." end run_demo if $PROGRAM_NAME == __FILE__
  • Pour plus de détails sur l'API, voir ListObjectsV2 dans le manuel de référence des AWS SDK for Ruby API.

Rust
Kit SDK pour Rust
Note

Il y en a plus sur GitHub. Trouvez l’exemple complet et découvrez comment le configurer et l’exécuter dans le référentiel d’exemples de code AWS.

pub async fn list_objects(client: &Client, bucket: &str) -> Result<(), Error> { let mut response = client .list_objects_v2() .bucket(bucket.to_owned()) .max_keys(10) // In this example, go 10 at a time. .into_paginator() .send(); while let Some(result) = response.next().await { match result { Ok(output) => { for object in output.contents() { println!(" - {}", object.key().unwrap_or("Unknown")); } } Err(err) => { eprintln!("{err:?}") } } } Ok(()) }
  • Pour plus de détails sur l'API, voir la ListObjectsversion V2 dans le AWS SDK pour la référence de l'API Rust.

SAP ABAP
Kit SDK pour SAP ABAP
Note

Il y en a plus sur GitHub. Trouvez l’exemple complet et découvrez comment le configurer et l’exécuter dans le référentiel d’exemples de code AWS.

TRY. oo_result = lo_s3->listobjectsv2( " oo_result is returned for testing purposes. " iv_bucket = iv_bucket_name ). MESSAGE 'Retrieved list of objects in S3 bucket.' TYPE 'I'. CATCH /aws1/cx_s3_nosuchbucket. MESSAGE 'Bucket does not exist.' TYPE 'E'. ENDTRY.
  • Pour plus de détails sur l'API, reportez-vous à la section ListObjectsV2 du AWS SDK pour la référence de l'API SAP ABAP.

Swift
Kit SDK pour Swift
Note

Ceci est une documentation préliminaire pour une fonctionnalité en version de prévisualisation. Elle est susceptible d’être modifiée.

Note

Il y en a plus sur GitHub. Trouvez l’exemple complet et découvrez comment le configurer et l’exécuter dans le référentiel d’exemples de code AWS.

public func listBucketFiles(bucket: String) async throws -> [String] { let input = ListObjectsV2Input( bucket: bucket ) let output = try await client.listObjectsV2(input: input) var names: [String] = [] guard let objList = output.contents else { return [] } for obj in objList { if let objName = obj.key { names.append(objName) } } return names }
  • Pour plus de détails sur l'API, consultez la section ListObjectsV2 dans le AWS SDK pour la référence de l'API Swift.