프로그래밍 방식으로 객체 키 나열 - 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 래퍼 라이브러리는 동일한 페이지 매김을 제공합니다.

Java

다음 예제에서는 버킷의 객체 키를 나열합니다. 이 예제는 페이지 매김을 사용하여 객체 키 세트를 검색합니다. 첫 페이지 이후 반환할 키가 더 있는 경우, Amazon S3는 연속 토큰을 응답에 포함시킵니다. 이 예제에서는 후속 요청에서 연속 토큰을 사용하여 다음 객체 키 세트를 가져옵니다.

실제 예제를 작성 및 테스트하는 방법에 대한 자세한 내용은 Amazon S3 Java 코드 예제 테스트 섹션을 참조하세요.

import com.amazonaws.AmazonServiceException; import com.amazonaws.SdkClientException; import com.amazonaws.auth.profile.ProfileCredentialsProvider; import com.amazonaws.regions.Regions; import com.amazonaws.services.s3.AmazonS3; import com.amazonaws.services.s3.AmazonS3ClientBuilder; import com.amazonaws.services.s3.model.ListObjectsV2Request; import com.amazonaws.services.s3.model.ListObjectsV2Result; import com.amazonaws.services.s3.model.S3ObjectSummary; import java.io.IOException; public class ListKeys { public static void main(String[] args) throws IOException { Regions clientRegion = Regions.DEFAULT_REGION; String bucketName = "*** Bucket name ***"; try { AmazonS3 s3Client = AmazonS3ClientBuilder.standard() .withCredentials(new ProfileCredentialsProvider()) .withRegion(clientRegion) .build(); System.out.println("Listing objects"); // maxKeys is set to 2 to demonstrate the use of // ListObjectsV2Result.getNextContinuationToken() ListObjectsV2Request req = new ListObjectsV2Request().withBucketName(bucketName).withMaxKeys(2); ListObjectsV2Result result; do { result = s3Client.listObjectsV2(req); for (S3ObjectSummary objectSummary : result.getObjectSummaries()) { System.out.printf(" - %s (size: %d)\n", objectSummary.getKey(), objectSummary.getSize()); } // If there are more than maxKeys keys in the bucket, get a continuation token // and list the next objects. String token = result.getNextContinuationToken(); System.out.println("Next Continuation Token: " + token); req.setContinuationToken(token); } while (result.isTruncated()); } catch (AmazonServiceException e) { // The call was transmitted successfully, but Amazon S3 couldn't process // it, so it returned an error response. e.printStackTrace(); } catch (SdkClientException e) { // Amazon S3 couldn't be contacted for a response, or the client // couldn't parse the response from Amazon S3. e.printStackTrace(); } } }
.NET

다음 C# 예제에서는 버킷의 객체 키를 나열합니다. 이 예제에서는 페이지 매김을 사용하여 객체 키 세트를 검색합니다. 반환할 키가 더 있는 경우, Amazon S3는 연속 토큰을 응답에 포함시킵니다. 이 코드에서는 후속 요청에서 연속 토큰을 사용하여 다음 객체 키 세트를 가져옵니다.

실제 예제를 작성하여 테스트하는 방법에 대한 자세한 내용은 Amazon S3 .NET 코드 예제 실행 섹션을 참조하세요.

using Amazon; using Amazon.S3; using Amazon.S3.Model; using System; using System.Threading.Tasks; namespace Amazon.DocSamples.S3 { class ListObjectsTest { private const string bucketName = "*** bucket name ***"; // Specify your bucket region (an example region is shown). private static readonly RegionEndpoint bucketRegion = RegionEndpoint.USWest2; private static IAmazonS3 client; public static void Main() { client = new AmazonS3Client(bucketRegion); ListingObjectsAsync().Wait(); } static async Task ListingObjectsAsync() { try { ListObjectsV2Request request = new ListObjectsV2Request { BucketName = bucketName, MaxKeys = 10 }; ListObjectsV2Response response; do { response = await client.ListObjectsV2Async(request); // Process the response. foreach (S3Object entry in response.S3Objects) { Console.WriteLine("key = {0} size = {1}", entry.Key, entry.Size); } Console.WriteLine("Next Continuation Token: {0}", response.NextContinuationToken); request.ContinuationToken = response.NextContinuationToken; } while (response.IsTruncated); } catch (AmazonS3Exception amazonS3Exception) { Console.WriteLine("S3 error occurred. Exception: " + amazonS3Exception.ToString()); Console.ReadKey(); } catch (Exception e) { Console.WriteLine("Exception: " + e.ToString()); Console.ReadKey(); } } } }
PHP

이 예제에서는 AWS SDK for PHP 버전 3의 클래스를 사용하여 Amazon S3 버킷에 포함된 객체 키를 나열하는 방법을 설명합니다.

이 예제에서는 이미 AWS SDK for PHP 사용 및 PHP 예제 실행의 지침에 따라 AWS SDK for PHP가 올바르게 설치되어 있다고 가정합니다.

AWS SDK for PHP를 사용하여 버킷에 포함된 객체 키를 나열하려면 먼저 버킷에 포함된 객체를 나열한 후 나열된 각 객체에서 키를 추출해야 합니다. 버킷의 객체를 나열할 때 하위 수준의 Aws\S3\S3Client::listObjects() 메서드 또는 상위 수준의 Aws\ResultPaginator 클래스를 선택하여 사용할 수 있습니다.

하위 수준의 listObjects() 메서드는 기본 Amazon S3 REST API로 매핑됩니다. 각 listObjects() 메서드는 최대 1,000개의 객체가 포함된 페이지를 반환합니다. 버킷의 객체가 1,000개보다 많을 경우 응답은 잘려서 표시되며, 다음 1,000개의 객체 조합을 검색하려면 다시 listObjects() 요청을 전송해야 합니다.

상위 수준 ListObjects 페이지네이터를 사용하면 버킷에 포함된 객체를 손쉽게 나열할 수 있습니다. ListObjects 페이지네이터를 사용하여 객체 목록을 생성하려면 ListObjects 명령을 첫 번째 인수로, 지정된 버킷에서 반환되는 객체가 포함될 배열을 두 번째 인수로 지정하여 Aws/AwsClientInterface 클래스에서 상속된 Amazon S3 클라이언트의 getPaginator() 메서드를 실행합니다.

ListObjects 페이지네이터를 사용할 때 getPaginator() 메서드는 지정된 버킷에 포함된 모든 객체를 반환합니다. 이 경우에는 1,000개의 객체 한도가 없으므로 응답이 잘리는지 여부에 대해 염려하지 않아도 됩니다.

다음 작업은 PHP Amazon S3 클라이언트 메서드를 사용하여 버킷에 포함된 객체를 나열한 후 객체 키를 나열하는 방법을 보여줍니다.

예 객체 키 나열

다음 PHP 예제는 지정된 버킷에서 키를 나열하는 방법을 보여줍니다. 버킷의 객체를 나열한 후 목록의 각 객체에서 키를 추출하는 상위 수준의 getIterator() 메서드를 사용하는 방법과 버킷의 객체를 나열한 후 반환된 목록의 각 객체에서 키를 추출하는 하위 수준의 listObjects() 메서드를 사용하는 방법을 보여줍니다. 이 가이드의 PHP 예제 실행에 대한 자세한 내용은 PHP 예제 실행 섹션을 참조하세요.

require 'vendor/autoload.php'; use Aws\S3\S3Client; use Aws\S3\Exception\S3Exception; $bucket = '*** Your Bucket Name ***'; // Instantiate the client. $s3 = new S3Client([ 'version' => 'latest', 'region' => 'us-east-1' ]); // Use the high-level iterators (returns ALL of your objects). try { $results = $s3->getPaginator('ListObjects', [ 'Bucket' => $bucket ]); foreach ($results as $result) { foreach ($result['Contents'] as $object) { echo $object['Key'] . PHP_EOL; } } } catch (S3Exception $e) { echo $e->getMessage() . PHP_EOL; } // Use the plain API (returns ONLY up to 1000 of your objects). try { $objects = $s3->listObjects([ 'Bucket' => $bucket ]); foreach ($objects['Contents'] as $object) { echo $object['Key'] . PHP_EOL; } } catch (S3Exception $e) { echo $e->getMessage() . PHP_EOL; }