# ListBucket(SOAP API)
<a name="SOAPListBucket"></a>

**참고**  
 Amazon S3용 SOAP API는 신규 고객에게 제공되지 않으며 2025년 8월 31일에 서비스 종료(EOL)됩니다. REST API 또는 AWS SDK를 사용하는 것이 좋습니다.

 `ListBucket` 작업은 버킷의 일부 항목에 대한 정보를 반환합니다.

 목록 작업에 대한 일반적인 소개는 [객체 키 나열](https://docs.aws.amazon.com/AmazonS3/latest/userguide/ListingKeysUsingAPIs.html)을 참조하세요.

## 요청
<a name="SOAPBucketGET_Request"></a>

이 예제에서는 'quotes' 버킷에서 접두사 'notes'가 있는 키를 최대 1,000개까지 나열합니다.

### 구문
<a name="SOAPBucketGET_RequestSyntax"></a>

```
1. <ListBucket xmlns="https://doc.s3.amazonaws.com/2006-03-01">
2.   <Bucket>quotes</Bucket>
3.   <Prefix>notes/</Prefix>
4.   <Delimiter>/</Delimiter>
5.   <MaxKeys>1000</MaxKeys>
6.   <AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
7.   <Timestamp>2006-03-01T12:00:00.183Z</Timestamp>
8.   <Signature>Iuyz3d3P0aTou39dzbqaEXAMPLE=</Signature>
9. </ListBucket>
```

### 파라미터
<a name="SOAPBucketGET_RequestHeaders"></a>


|  이름  |  설명  |  필수  | 
| --- | --- | --- | 
|  prefix  | 응답을 표시된 접두사로 시작하는 키로 제한합니다. 접두사를 사용하여 파일 시스템이 폴더를 사용하는 방식과 유사하게 버킷을 다른 키 세트로 분리할 수 있습니다.<br />유형: 문자열<br />기본값: None |  아니요  | 
|  marker  | 버킷에서 나열을 시작할 위치를 나타냅니다. 이 목록에는 문자순으로 마커 뒤에 오는 키만 포함됩니다. 이는 페이지 매김에 편리합니다. 결과의 다음 페이지를 가져오려면 현재 페이지의 마지막 키를 마커로 사용합니다.<br />유형: 문자열<br />기본값: None |  아니요  | 
|  max-keys  | 응답 본문에서 보려는 최대 키 수입니다. 서버는 이보다 적은 수의 키를 반환할 수는 있지만 더 많은 키를 반환하지는 않습니다.<br />유형: 문자열<br />기본값: None |  아니요  | 
|  delimiter  | 접두사와 첫 번째 구분 기호 사이에 동일한 문자열이 포함된 키를 CommonPrefixes 모음의 단일 결과 요소로 롤업합니다. 이러한 롤업 키는 응답의 다른 곳에서 반환되지 않습니다.<br />유형: 문자열<br />기본값: None |  아니요  | 

## 성공 응답
<a name="SOAPBucketGET_ResponseSuccess"></a>

이 응답은 버킷에 다음 키가 포함되어 있다고 가정합니다.

```
1. notes/todos.txt
2. notes/2005-05-23/customer_mtg_notes.txt
3. notes/2005-05-23/phone_notes.txt
4. notes/2005-05-28/sales_notes.txt
```

### 구문
<a name="SOAPBucketGET_ResponseSuccess-syntax"></a>

```
 1. <?xml version="1.0" encoding="UTF-8"?>
 2. <ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
 3.   <Name>backups</Name>
 4.   <Prefix>notes/</Prefix>
 5.   <MaxKeys>1000</MaxKeys>
 6.   <Delimiter>/</Delimiter>
 7.   <IsTruncated>false</IsTruncated>
 8.   <Contents>
 9.     <Key>notes/todos.txt</Key>
10.     <LastModified>2006-01-01T12:00:00.000Z</LastModified>
11.     <ETag>&quot;828ef3fdfa96f00ad9f27c383fc9ac7f&quot;</ETag>
12.     <Size>5126</Size>
13.     <StorageClass>STANDARD</StorageClass>
14.     <Owner>
15.       <ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
16.       <DisplayName>webfile</DisplayName>
17.     </Owner>
18.     <StorageClass>STANDARD</StorageClass>
19.   </Contents>
20.   <CommonPrefixes>
21.     <Prefix>notes/2005-05-23/</Prefix>
22.   </CommonPrefixes>
23.   <CommonPrefixes>
24.     <Prefix>notes/2005-05-28/</Prefix>
25.   </CommonPrefixes>
26.   </ListBucketResult>
```

보다시피 응답의 많은 필드는 요청 파라미터를 그대로 반영합니다. 새로운 정보를 포함할 수 있는 유일한 응답 요소는 `IsTruncated`, `Contents`, `CommonPrefixes`뿐입니다.

### 응답 요소
<a name="SOAPBucketGET_ResponseSuccess-response-elements"></a>


|  이름  |  설명  | 
| --- | --- | 
|  Contents  | 반환된 각 객체에 대한 메타데이터입니다.<br />유형: XML 메타데이터<br />상위 항목: ListBucketResult | 
|  CommonPrefixes  |  `delimiter`를 지정하는 경우에만 응답에 `CommonPrefixes`가 포함될 수 있습니다. 그러면 `CommonPrefixes`에 `Prefix`와 `delimiter`로 지정된 문자열의 다음번 발생 지점 사이에 있는 모든 키(있는 경우)가 포함됩니다. 실제로 `CommonPrefixes`는 `Prefix`로 지정된 디렉터리의 하위 디렉터리처럼 작동하는 키를 나열합니다. 예를 들어 `prefix`가 `notes/`이고 `delimiter`가 슬래시(/)인 경우 `notes/summer/july`에서 공통 접두사는 `notes/summer/`입니다.<br />유형: 문자열<br />상위 항목: ListBucketResult | 
|  Delimiter  | 접두사와 첫 번째 구분 기호 사이에 동일한 문자열이 포함된 키를 CommonPrefixes 모음의 단일 결과 요소로 롤업합니다. 이러한 롤업 키는 응답의 다른 곳에서 반환되지 않습니다.<br />유형: 문자열<br />상위 항목: ListBucketResult | 
|  IsTruncated  | 모든 결과가 반환되었는지(true) 또는 반환되지 않았는지(false) 지정합니다. 결과가 `MaxKeys`로 지정된 수를 초과하는 경우 모든 결과가 반환되지 않을 수 있습니다.<br />유형: 문자열<br />상위 항목: 부울 | 
|  Marker  | 버킷에서 나열을 시작할 위치를 나타냅니다.<br />유형: 문자열<br />상위 항목: ListBucketResult | 
|  MaxKeys  | 응답 본문에서 반환되는 최대 키 수입니다.<br />유형: 문자열<br />상위 항목: ListBucketResult | 
|  Name  | 버킷의 이름입니다.<br />유형: 문자열<br />상위 항목: ListBucketResult | 
|  Prefix  | 표시된 접두사로 시작하는 키입니다.<br />유형: 문자열<br />상위 항목: ListBucketResult | 

## 응답 본문
<a name="SOAPListBucketResponseBody"></a>

 목록 응답에 대한 자세한 내용은 [키 나열 응답](https://docs.aws.amazon.com/AmazonS3/latest/userguide/ListingKeysUsingAPIs.html)을 참조하세요.

## 액세스 통제
<a name="SOAPListBucketAccessControl"></a>

버킷의 키를 나열하려면 버킷에 대한 `READ` 액세스 권한이 부여되어야 합니다.