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

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

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

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

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

참고

HTTP를 통한 SOAP 지원은 중단되었지만 HTTPS를 통해 계속해서 사용할 수 있습니다. 새로운 Amazon S3 기능은 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 래퍼 라이브러리는 동일한 페이지 매김을 제공합니다.

예시:

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

.NET
AWS SDK for .NET
작은 정보

이 예제를 설정하고 실행하는 방법에 대해 자세히 알아보려면 GitHub 단원을 참조하십시오.

/// <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("--------------------------------------"); var response = new ListObjectsV2Response(); 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; } }
  • API 세부 정보는 AWS SDK for .NET API 참조ListObjects를 참조하세요.

C++
SDK for C++
작은 정보

이 예제를 설정하고 실행하는 방법에 대해 자세히 알아보려면 GitHub 단원을 참조하십시오.

bool AwsDoc::S3::ListObjects(const Aws::String& bucketName, const Aws::String& region) { Aws::Client::ClientConfiguration config; if (!region.empty()) { config.region = region; } Aws::S3::S3Client s3_client(config); Aws::S3::Model::ListObjectsRequest request; request.WithBucket(bucketName); auto outcome = s3_client.ListObjects(request); if (outcome.IsSuccess()) { std::cout << "Objects in bucket '" << bucketName << "':" << std::endl << std::endl; Aws::Vector<Aws::S3::Model::Object> objects = outcome.GetResult().GetContents(); for (Aws::S3::Model::Object& object : objects) { std::cout << object.GetKey() << std::endl; } return true; } else { std::cout << "Error: ListObjects: " << outcome.GetError().GetMessage() << std::endl; return false; } } int main() { Aws::SDKOptions options; Aws::InitAPI(options); { //TODO: Name of a bucket in your account. //The bucket must have at least one object in it. One way to achieve //this is to configure and run put_object.cpp's executable first. const Aws::String bucket_name = "DOC-EXAMPLE-BUCKET"; //TODO: Set to the AWS Region in which the bucket was created. Aws::String region = "us-east-1"; if (!AwsDoc::S3::ListObjects(bucket_name, region)) { return 1; } } Aws::ShutdownAPI(options); return 0; }
  • API 세부 정보는 AWS SDK for C++ API 참조ListObjects를 참조하세요.

Go
SDK for Go V2
작은 정보

이 예제를 설정하고 실행하는 방법에 대해 자세히 알아보려면 GitHub 단원을 참조하십시오.

// List objects in the bucket. // n.b. object keys in Amazon S3 do not begin with '/'. You do not need to lead your // prefix with it. fmt.Println("Listing the objects in the bucket:") listObjsResponse, err := client.ListObjectsV2(context.TODO(), &s3.ListObjectsV2Input{ Bucket: aws.String(name), Prefix: aws.String(""), }) if err != nil { panic("Couldn't list bucket contents") } for _, object := range listObjsResponse.Contents { fmt.Printf("%s (%d bytes, class %v) \n", *object.Key, object.Size, object.StorageClass) }
  • API 세부 정보는 AWS SDK for Go API 참조ListObjects를 참조하세요.

Java
SDK for Java 2.x
작은 정보

이 예제를 설정하고 실행하는 방법에 대해 자세히 알아보려면 GitHub 단원을 참조하십시오.

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; }
  • API 세부 정보는 AWS SDK for Java 2.x API 참조ListObjects를 참조하세요.

JavaScript
SDK for JavaScript V3
작은 정보

이 예제를 설정하고 실행하는 방법에 대해 자세히 알아보려면 GitHub 단원을 참조하십시오.

클라이언트를 생성합니다.

// Create service client module using ES6 syntax. import { S3Client } from "@aws-sdk/client-s3"; // Set the AWS Region. const REGION = "REGION"; //e.g. "us-east-1" // Create an Amazon S3 service client object. const s3Client = new S3Client({ region: REGION }); export { s3Client };

객체를 나열합니다.

// Import required AWS SDK clients and commands for Node.js. import { ListObjectsCommand } from "@aws-sdk/client-s3"; import { s3Client } from "./libs/s3Client.js"; // Helper function that creates an Amazon S3 service client module. // Create the parameters for the bucket export const bucketParams = { Bucket: "BUCKET_NAME" }; export const run = async () => { try { const data = await s3Client.send(new ListObjectsCommand(bucketParams)); console.log("Success", data); return data; // For unit tests. } catch (err) { console.log("Error", err); } }; run();

1,000개 이상의 객체를 나열합니다.

// Import required AWS SDK clients and commands for Node.js. import { ListObjectsCommand } from "@aws-sdk/client-s3"; import { s3Client } from "./libs/s3Client.js"; // Helper function that creates an Amazon S3 service client module. // Create the parameters for the bucket export const bucketParams = { Bucket: "BUCKET_NAME" }; export async function run() { // Declare truncated as a flag that the while loop is based on. let truncated = true; // Declare a variable to which the key of the last element is assigned to in the response. let pageMarker; // while loop that runs until 'response.truncated' is false. while (truncated) { try { const response = await s3Client.send(new ListObjectsCommand(bucketParams)); // return response; //For unit tests response.Contents.forEach((item) => { console.log(item.Key); }); // Log the key of every item in the response to standard output. truncated = response.IsTruncated; // If truncated is true, assign the key of the last element in the response to the pageMarker variable. if (truncated) { pageMarker = response.Contents.slice(-1)[0].Key; // Assign the pageMarker value to bucketParams so that the next iteration starts from the new pageMarker. bucketParams.Marker = pageMarker; } // At end of the list, response.truncated is false, and the function exits the while loop. } catch (err) { console.log("Error", err); truncated = false; } } } run();
  • API 세부 정보는 AWS SDK for JavaScript API 참조ListObjects를 참조하세요.

Kotlin
Kotlin용 SDK
참고

이 시험판 설명서는 미리 보기 버전 기능에 관한 것입니다. 변경될 수 있습니다.

작은 정보

이 예제를 설정하고 실행하는 방법에 대해 자세히 알아보려면 GitHub 단원을 참조하십시오.

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 ${calKb(myObject.size)} KBs") println("The owner is ${myObject.owner}") } } } private fun calKb(intValue: Long): Long { return intValue / 1024 }
  • API 세부 정보는 Kotlin용 AWS SDK API 참조ListObjects를 참조하세요.

PHP
SDK for PHP
작은 정보

이 예제를 설정하고 실행하는 방법에 대해 자세히 알아보려면 GitHub 단원을 참조하십시오.

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

$s3client = new Aws\S3\S3Client(['region' => 'us-west-2', 'version' => 'latest']); try { $contents = $s3client->listObjects([ 'Bucket' => $bucket_name, ]); 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 $bucket_name with error: " . $exception->getMessage(); exit("Please fix error with listing objects before continuing."); }
  • API 세부 정보는 AWS SDK for PHP API 참조ListObjects를 참조하세요.

Python
SDK for Python(Boto3)
작은 정보

이 예제를 설정하고 실행하는 방법에 대해 자세히 알아보려면 GitHub 단원을 참조하십시오.

class ObjectWrapper: def __init__(self, s3_object): 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. :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 세부 정보는 Python용 AWS SDK(Boto3) API 참조ListObjects를 참조하세요.

Ruby
SDK for Ruby
작은 정보

이 예제를 설정하고 실행하는 방법에 대해 자세히 알아보려면 GitHub 단원을 참조하십시오.

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 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 참조ListObjects를 참조하세요.

Rust
SDK for Rust
참고

이 설명서는 평가판 버전 SDK에 관한 것입니다. SDK는 변경될 수 있으며 프로덕션에서 사용해서는 안 됩니다.

작은 정보

이 예제를 설정하고 실행하는 방법에 대해 자세히 알아보려면 GitHub 단원을 참조하십시오.

pub async fn list_objects(client: &Client, bucket_name: &str) -> Result<(), Error> { let objects = client.list_objects_v2().bucket(bucket_name).send().await?; println!("Objects in bucket:"); for obj in objects.contents().unwrap_or_default() { println!("{:?}", obj.key().unwrap()); } Ok(()) }
  • API 세부 정보는 Rust용 AWS SDK API 참조ListObjects를 참조하세요.