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

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. It was created using AWS SDK for .NET 3.5
    /// and .NET Core 5.0.
    /// </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" "$*" 2>&1
}

###############################################################################
# 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++

SDK for C++

참고

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

Go

Go V2용 SDK

참고

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

Java 2.x용 SDK

참고

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

    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;
    }

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

    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

JavaScript용 SDK(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

Kotlin용 SDK

참고

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

참고

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 ${calKb(myObject.size)} KBs")
            println("The owner is ${myObject.owner}")
        }
    }
}

private fun calKb(intValue: Long): Long {
    return intValue / 1024
}

• API 세부 정보는 Kotlin용 AWS SDK API 참조의 ListObjectsV2를 참조하세요.

PHP

PHP용 SDK

참고

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

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

$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 참조의 ListObjectsV2를 참조하세요.

Python

Python용 SDK(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 세부 정보는 Python용 AWS SDK(Boto3) API 참조의 ListObjectsV2를 참조하세요.

Ruby

Ruby용 SDK

참고

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

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

Rust용 SDK

참고

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

참고

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

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

SAP ABAP

SAP ABAP용 SDK

참고

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 세부 정보는 SAP ABAP용 AWS SDK API 참조의 ListObjectsV2를 참조하세요.

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