Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.
Programmgesteuertes Auflisten von Objektschlüsseln
In Amazon S3 können Schlüssel nach Präfix aufgelistet werden. Sie können ein allgemeines Präfix für die Namen verwandter Schlüssel wählen und diese Schlüssel mit einem Sonderzeichen markieren, das die Hierarchie begrenzt. Sie können dann die Listenoperation verwenden, um Schlüssel hierarchisch auszuwählen und zu durchsuchen. In ähnlicher Weise werden Dateien in einem Dateisystem in Ordnern gespeichert.
Amazon S3 stellt eine Listenoperation bereit, die Ihnen ermöglicht, die in einem Bucket enthaltenen Schlüssel aufzulisten. Schlüssel werden nach Bucket und Präfix für die Auflistung ausgewählt. Angenommen, wir haben einen Bucket namens "dictionary
", der einen Schlüssel für jedes englische Wort enthält. Sie können einen Aufruf ausführen, um alle Schlüssel in dem Bucket aufzulisten, die mit dem Buchstaben "q" beginnen. Listenergebnisse werden immer in binärer UTF-8-Reihenfolge zurückgegeben.
Sowohl SOAP- als auch REST-Listenvorgänge geben ein XML-Dokument zurück, das die Namen übereinstimmender Schlüssel sowie Informationen über das von jedem Schlüssel identifizierte Objekt enthält.
Die SOAP-Unterstützung über HTTP ist veraltet, SOAP steht über HTTPS aber noch zur Verfügung. Neue Amazon-S3-Funktionen werden unter SOAP nicht unterstützt. Anstatt SOAP zu verwenden, empfehlen wir, entweder die REST-API oder die AWS SDKs zu verwenden.
Gruppen von Schlüsseln, die ein gemeinsames Präfix haben, abgeschlossen mit einem speziellen Trennzeichen, können in einer Auflistung nach diesem gemeinsamen Präfix ausgegeben werden. Auf diese Weise können Anwendungen ihre Schlüssel hierarchisch organisieren und durchsuchen, ähnlich wie bei der Organisation Ihrer Dateien in Verzeichnissen in einem Dateisystem.
Um beispielsweise den dictionary-Bucket zu erweitern, um mehr als nur englische Wörter aufzunehmen, könnten Sie Schlüssel bilden, indem Sie jedem Wort ein Präfix für seine Sprache und ein Trennzeichen voranstellen, wie beispielsweise "French/logical
". Mit Hilfe dieses Namensschemas und der Funktion zur hierarchischen Auflistung könnten Sie eine Liste nur mit französischen Wörtern abrufen. Sie könnten auch auf oberster Ebene eine Liste verfügbarer Sprachen durchsuchen, ohne alle lexikographischen Schlüssel durchlaufen zu müssen. Weitere Informationen über diesen Aspekt der Auflistung finden Sie unter Organisieren von Objekten mit Präfixen.
REST-API
Falls in Ihrer Anwendung erforderlich, können Sie REST-Anforderungen auch direkt senden. Sie können eine GET-Anforderung senden, um alle oder einen Teil der Objekte in einem Bucket zurückzugeben, oder Auswahlkriterien anwenden, um eine Untermenge der Objekte in einem Bucket zurückzugeben. Weitere Informationen finden Sie unter GET-Bucket(List Objects)-Version-2 in Amazon Simple Storage Service – API-Referenz.
Effiziente Implementierung von Listen
Die Listenleistung wird von der Gesamtzahl der Schlüssel in Ihrem Bucket nicht wesentlich beeinflusst. Es ist auch nicht von der Anwesenheit oder Abwesenheit der Argumente prefix
, marker
, maxkeys
oder delimiter
betroffen.
Durchlaufen mehrseitiger Ergebnisse
Buckets können nahezu unbegrenzt viele Schlüssel enthalten, die vollständigen Ergebnisse einer Listenabfrage können deshalb extrem umfangreich sein. Um große Ergebnismengen zu verwalten, unterstützt die Amazon-S3-API eine Paginierung, um sie in mehrere Antworten aufzuteilen. Jede Antwort für Listenschlüssel gibt eine Seite mit bis zu 1000 Schlüsseln zurück, mit einer Angabe, ob die Antwort gekürzt wurde. Sie senden eine Reihe von Anforderungen zum Auflisten von Schlüsseln, bis Sie alle Schlüssel erhalten haben. AWS SDK-Wrapper-Bibliotheken bieten dieselbe Paginierung.
Beispiele
In den folgenden Codebeispielen wird veranschaulicht, wie Sie Objekte in einem S3 Bucket auflisten.
- .NET
-
- AWS SDK for .NET
-
/// <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;
}
}
Listen Sie Objekte mit einem Paginator auf.
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}");
}
}
}
}
- Bash
-
- AWS CLI mit Bash-Skript
-
###############################################################################
# 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
}
- C++
-
- SDK für C++
-
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();
}
- CLI
-
- AWS CLI
-
Im folgenden Beispiel wird der list-objects
Befehl verwendet, um die Namen aller Objekte im angegebenen Bucket anzuzeigen:
aws s3api list-objects --bucket text-content --query 'Contents[].{Key: Key, Size: Size}'
Das Beispiel verwendet das Argument --query
, um die Ausgabe von auf den Schlüsselwert und die Größe für jedes Objekt list-objects
zu filtern
Weitere Informationen zu Objekten finden Sie unter Arbeiten mit Amazon S3-Objekten im Amazon S3-Entwicklerhandbuch.
- Go
-
- SDK für Go V2
-
// 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
}
- Java
-
- SDK für Java 2.x
-
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;
}
}
Listet Objekte mithilfe der Paginierung auf.
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);
}
}
}
- JavaScript
-
- SDK für JavaScript (v3)
-
Listen Sie alle Objekte in Ihrem Bucket auf. Wenn es mehr als ein Objekt gibt, IsTruncated NextContinuationToken wird verwendet, um über die vollständige Liste zu iterieren.
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);
}
};
- Kotlin
-
- SDK für Kotlin
-
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
}
- PHP
-
- SDK für PHP
-
Listen Sie Objekte in einem Bucket auf.
$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.");
}
- Python
-
- SDK für Python (Boto3)
-
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
- Ruby
-
- SDK für Ruby
-
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__
- Rust
-
- SDK für Rust
-
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(())
}
- SAP ABAP
-
- SDK für SAP ABAP
-
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.
- Swift
-
- SDK für Swift
-
Diese ist die Vorabdokumentation für ein SDK in der Vorversion. Änderungen sind vorbehalten.
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
}