프로그래밍 방식으로 객체 키 나열 - Amazon Simple Storage Service

프로그래밍 방식으로 객체 키 나열

Amazon S3에서는 접두사별로 키를 나열할 수 있습니다. 관련 키 이름에 대한 공통 접두사를 선택하고 계층 구조를 구분하는 특수 문자로 이러한 키를 표시할 수 있습니다. 그런 다음 나열 작업을 사용하여 계층적으로 키를 선택하고 찾아볼 수 있습니다. 이는 파일 시스템 내 각 디렉토리에 파일이 저장되는 방식과 유사합니다.

Amazon S3는 버킷에 포함된 키를 열거할 수 있는 나열 작업을 제공합니다. 버킷과 접두사를 기준으로 키를 선택하여 나열할 수 있습니다. 예를 들어 모든 영어 단어에 대한 키가 포함된 "dictionary"라는 이름의 버킷을 가정해 보겠습니다. 버킷에서 "q"로 시작하는 모든 키를 나열하도록 요청할 수 있습니다. 나열 결과는 항상 UTF-8 이진 순서로 반환됩니다.

SOAP 및 REST 나열 작업은 모두 일치하는 키의 이름과 각 키에 의해 식별되는 객체에 대한 정보가 포함된 XML 문서를 반환합니다.

참고

HTTP를 통한 SOAP 지원은 중단되었지만 SOAP는 HTTPS를 통해 계속해서 사용할 수 있습니다. Amazon S3의 새로운 기능들은 SOAP에서 지원되지 않습니다. SOAP를 사용하는 대신 REST API 또는 AWS SDK를 사용하는 것이 좋습니다.

특수 구분 기호로 끝나는 접두사를 공유하는 키의 그룹은 나열의 목적을 위해 공통 접두사별로 분류할 수 있습니다. 이를 통해 애플리케이션은 파일 시스템에서 디렉토리별로 파일을 정렬하는 것과 유사한 방식으로 계층적 구조에 따라 키를 정렬하고 탐색할 수 있습니다.

예를 들어 영어 외 다른 언어의 단어도 포함하도록 dictionary 버킷을 확장하려면 그 언어와 구분 기호(예: "French/logical")를 사용하여 각 단어에 접두사를 추가하여 키를 만들 것입니다. 이 명명 스키마와 계층적 나열 기능을 사용하여 프랑스어 단어의 목록만 검색할 수 있습니다. 또한 사전에 등재된 모든 단어에 대한 키를 살펴볼 필요 없이 최상위 수준에서 해당 단어의 목록만 탐색할 수 있습니다. 이 나열 기능에 대한 자세한 내용은 접두어를 사용한 객체 구성 섹션을 참조하십시오.

REST API

애플리케이션에서 요구할 경우 REST 요청을 직접 전송할 수 있습니다. GET 요청을 전송하여 버킷의 일부 또는 전체 객체를 반환하거나, 선택 조건을 사용하여 버킷의 일부 객체를 반환할 수 있습니다. 자세한 내용은 Amazon Simple Storage Service API 참조GET Bucket(List Objects) 버전 2를 참조하십시오.

효율적인 나열 기능 구현

나열 기능의 성능은 버킷의 총 키 수에 크게 영향을 받지 않습니다. 또한 prefix, marker, maxkeys 또는 delimiter 인수의 유무에도 영향을 받지 않습니다.

여러 페이지의 결과 살펴보기

버킷에 포함할 수 있는 키는 거의 무제한이므로 나열 쿼리의 전체 결과는 매우 방대할 수 있습니다. 이처럼 대량의 결과 조합을 관리하기 위해 Amazon S3 API는 그 조합을 여러 개의 응답으로 나눌 수 있도록 페이지 매김을 지원합니다. 각 나열 키 응답은 최대 1,000개의 키로 구성된 페이지와 함께 응답이 잘린 경우 이를 나타내는 표시 기호를 반환합니다. 모든 키가 수신될 때까지 나열 키 요청을 반복해서 전송해야 합니다. AWS SDK 래퍼 라이브러리는 동일한 페이지 매김을 제공합니다.

다음 코드 예제는 S3 버킷의 객체를 나열하는 방법을 보여줍니다.

.NET
AWS SDK for .NET
참고

GitHub에 더 많은 내용이 있습니다. 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; } }

페이지네이터를 사용하여 객체를 나열합니다.

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}"); } } } }
  • API 세부 정보는  AWS SDK for .NET API 참조의 ListObjectsV2를 참조하십시오.

Bash
Bash 스크립트와 함께 AWS CLI사용
참고

GitHub에 더 많은 내용이 있습니다. 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 }
  • API 세부 정보는  AWS CLI 명령 참조의 ListObjectsV2를 참조하십시오.

C++
C++용 SDK
참고

GitHub에 더 많은 내용이 있습니다. 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(); }
  • API 세부 정보는 AWS SDK for C++ API 참조ListObjectsV2를 참조하십시오.

CLI
AWS CLI

다음 예시에서는 list-objects 명령을 사용하여 지정된 버킷에 있는 모든 객체의 이름을 표시합니다.

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

이 예시에서는 --query 인수를 사용하여 list-objects의 출력을 각 객체의 키 값 및 크기로 필터링합니다.

객체에 대한 자세한 내용은 Amazon S3 개발자 안내서의 Amazon S3 객체 작업을 참조하세요.

  • API 세부 정보는  AWS CLI 명령 참조의 ListObjectsV2를 참조하십시오.

Go
SDK for Go V2
참고

GitHub에 더 많은 내용이 있습니다. 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 }
  • API 세부 정보는  AWS SDK for Go API 참조의 ListObjectsV2를 참조하십시오.

Java
SDK for Java 2.x
참고

GitHub에 더 많은 내용이 있습니다. 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; } }

페이지 매김을 사용하여 객체를 나열합니다.

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); } } }
  • API 세부 정보는  AWS SDK for Java 2.x API 참조의 ListObjectsV2를 참조하십시오.

JavaScript
SDK for JavaScript(v3)
참고

GitHub에 더 많은 내용이 있습니다. AWS 코드 예제 리포지토리에서 전체 예제를 찾고 설정 및 실행하는 방법을 배워보세요.

버킷의 모든 객체를 나열합니다. 객체가 두 개 이상인 경우, 전체 목록을 반복하는 데 IsTruncated 및 NextContinuationToken이 사용됩니다.

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); } };
  • API 세부 정보는  AWS SDK for JavaScript API 참조의 ListObjectsV2를 참조하십시오.

Kotlin
SDK for Kotlin
참고

GitHub에 더 많은 내용이 있습니다. 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 }
  • API 세부 정보는 AWS SDK for Kotlin API 참조ListObjectsV2를 참조하십시오.

PHP
SDK for PHP
참고

GitHub에 더 많은 내용이 있습니다. AWS 코드 예제 리포지토리에서 전체 예제를 찾고 설정 및 실행하는 방법을 배워보세요.

버킷의 객체를 나열합니다.

$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."); }
  • API 세부 정보는  AWS SDK for PHP API 참조의 ListObjectsV2를 참조하십시오.

Python
SDK for Python (Boto3)
참고

GitHub에 더 많은 내용이 있습니다. 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
  • API 세부 정보는 AWSSDK for Python (Boto3) API 참조ListObjectsV2를 참조하십시오.

Ruby
SDK for Ruby
참고

GitHub에 더 많은 내용이 있습니다. 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__
  • API 세부 정보는  AWS SDK for Ruby API 참조의 ListObjectsV2를 참조하십시오.

Rust
SDK for Rust
참고

GitHub에 더 많은 내용이 있습니다. 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(()) }
  • API 세부 정보는 AWS SDK for Rust API 참조ListObjectsV2을 참조하십시오.

SAP ABAP
SDK for SAP ABAP API
참고

GitHub에 더 많은 내용이 있습니다. 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.
  • API 세부 정보는 AWSSDK for SAP ABAP APIListObjectsV2을 참조하십시오.

Swift
SDK for Swift
참고

이 사전 릴리스 설명서는 평가판 버전 SDK에 관한 것입니다. 변경될 수 있습니다.

참고

GitHub에 더 많은 내용이 있습니다. 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 }
  • API 세부 정보는 Swift용 AWS SDK API 참조의 ListObjectsV2를 참조하십시오.