프로그래밍 방식으로 객체 키 나열하기
프로그래밍 방식으로 객체 키 나열하기
버킷 안에 어떤 키들이 있는지 코드로 확인하고 싶을 때가 있어요. Amazon S3에서 키는 접두사로 나열할 수 있어요. 관련된 키들 이름에 공통 접두사를 정하고, 그 키들을 계층을 구분하는 특수 문자로 표시할 수 있어요. 그런 다음 목록 작업을 사용해 키를 계층적으로 선택하고 탐색할 수 있어요. 이건 파일 시스템에서 디렉터리 안에 파일을 저장하는 방식과 비슷해요.
Amazon S3는 버킷에 포함된 키를 열거할 수 있는 목록 작업을 제공해요. 키는 버킷과 접두사로 목록을 선택해요. 예를 들어 영어 단어마다 하나의 키가 들어 있는 "dictionary"라는 버킷이 있다고 해볼게요. 그 버킷에서 "q"로 시작하는 모든 키를 나열하는 호출을 만들 수 있어요. 목록 결과는 항상 UTF-8 이진 순서로 반환돼요.
SOAP와 REST 목록 작업은 모두 일치하는 키의 이름과 각 키가 식별하는 객체에 대한 정보를 담은 XML 문서를 반환해요.
참고
Amazon S3용 SOAP API는 신규 고객에게 제공되지 않고, 2025년 8월 31일에 수명 종료(EOL)에 가까워지고 있어요. REST API나 AWS SDK를 사용하는 것을 권장해요.
특수 구분자로 끝나는 공통 접두사를 공유하는 키 그룹은 그 공통 접두사로 묶어서 나열할 수 있어요. 이 기능 덕분에 애플리케이션은 키를 계층적으로 정리하고 탐색할 수 있어요. 파일 시스템에서 파일을 디렉터리로 정리하는 것과 아주 비슷하죠.
예를 들어 dictionary 버킷을 영어 단어만 담는 것을 넘어 확장하려면, 각 단어 앞에 언어와 구분자를 붙여 "French/logical"처럼 키를 만들 수 있어요. 이 명명 체계와 계층적 목록 기능을 사용하면 프랑스어 단어만 목록으로 가져올 수 있어요. 또한 사전순으로 사이에 끼는 모든 키를 반복하지 않고도 사용 가능한 언어의 최상위 목록을 탐색할 수 있어요. 목록의 이런 측면에 대한 자세한 내용은 접두사를 사용한 객체 정리를 참고하세요.
출처: 문서
본문
REST API
애플리케이션이 요구한다면 REST 요청을 직접 보낼 수 있어요. GET 요청을 보내 버킷에 있는 객체의 일부 또는 전체를 반환하거나, 선택 기준을 사용해 버킷 안 객체의 하위 집합을 반환할 수 있어요. 자세한 내용은 _Amazon Simple Storage Service API Reference_의 GET Bucket (List Objects) Version 2를 참고하세요.
목록 구현 효율성
목록 성능은 버킷의 총 키 수에 크게 영향을 받지 않아요. prefix, marker, maxkeys, delimiter 인수의 유무에도 영향을 받지 않아요.
여러 페이지 결과 반복
버킷에는 사실상 무제한의 키가 들어 있을 수 있으므로 목록 쿼리의 전체 결과는 매우 커질 수 있어요. 큰 결과 집합을 관리하기 위해 Amazon S3 API는 페이지네이션을 지원해 여러 응답으로 분할해요. 각 목록 키 응답은 최대 1,000개의 키 페이지를 반환하고, 응답이 잘렸는지를 나타내는 표시기를 포함해요. 모든 키를 받을 때까지 일련의 목록 키 요청을 보내요. AWS SDK 래퍼 라이브러리도 같은 페이지네이션을 제공해요.
예시
버킷의 모든 객체를 나열할 때는 s3:ListBucket 권한이 있어야 한다는 점을 기억하세요.
CLI
list-objects
다음 예시는 list-objects 명령을 사용해 지정된 버킷에 있는 모든 객체의 이름을 표시해요.
aws s3api list-objects --bucket text-content --query 'Contents[].{Key: Key, Size: Size}'
이 예시는 --query 인수를 사용해 list-objects의 출력을 각 객체의 키 값과 크기로 필터링해요.
객체에 대한 자세한 내용은 Amazon S3에서 객체 작업하기를 참고하세요.
- API 세부 정보는 _AWS CLI Command Reference_의 ListObjects를 참고하세요.
ls
다음 예시는 ls 명령을 사용해 버킷에 있는 모든 객체와 접두사를 나열해요.
이 예시 명령을 사용하려면 amzn-s3-demo-bucket을 여러분의 버킷 이름으로 바꾸세요.
$ aws s3 ls s3://amzn-s3-demo-bucket
- 상위 수준 명령
ls에 대한 자세한 내용은 _AWS Command Line Interface User Guide_의 버킷·객체 나열을 참고하세요.
PowerShell
Tools for PowerShell V4
- 예시 1: 이 명령은 "test-files" 버킷에 있는 모든 항목에 대한 정보를 가져와요.
Get-S3Object -BucketName amzn-s3-demo-bucket
- 예시 2: 이 명령은 "test-files" 버킷의 "sample.txt" 항목에 대한 정보를 가져와요.
Get-S3Object -BucketName amzn-s3-demo-bucket -Key sample.txt
- 예시 3: 이 명령은 "test-files" 버킷에서 "sample" 접두사를 가진 모든 항목에 대한 정보를 가져와요.
Get-S3Object -BucketName amzn-s3-demo-bucket -KeyPrefix sample
- API 세부 정보는 _AWS Tools for PowerShell Cmdlet Reference (V4)_의 ListObjects를 참고하세요.
Tools for PowerShell V5
- 예시 1: 이 명령은 "test-files" 버킷에 있는 모든 항목에 대한 정보를 가져와요.
Get-S3Object -BucketName amzn-s3-demo-bucket
- 예시 2: 이 명령은 "test-files" 버킷의 "sample.txt" 항목에 대한 정보를 가져와요.
Get-S3Object -BucketName amzn-s3-demo-bucket -Key sample.txt
- 예시 3: 이 명령은 "test-files" 버킷에서 "sample" 접두사를 가진 모든 항목에 대한 정보를 가져와요.
Get-S3Object -BucketName amzn-s3-demo-bucket -KeyPrefix sample
- API 세부 정보는 _AWS Tools for PowerShell Cmdlet Reference (V5)_의 ListObjects를 참고하세요.