# GetObject(SOAP API)
<a name="SOAPGetObject"></a>

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

`GetObject` 작업은 객체의 현재 버전을 반환합니다. 삭제 마커가 현재 버전인 객체에 대해 `GetObject`를 시도하면 S3가 404 오류를 반환합니다. 이 SOAP API를 사용하여 객체의 지정된 버전을 검색할 수 없습니다. 이를 위해서는 REST API를 사용합니다. 자세한 내용은 [버전 관리](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Versioning.html)를 참조하십시오. 추가 옵션을 선택하려면 [GetObjectExtended(SOAP API)](SOAPGetObjectExtended.md) 작업을 사용합니다.

**참고**  
값이 "soap"인 객체 키 이름은 [가상 호스팅 스타일 요청](https://docs.aws.amazon.com/AmazonS3/latest/userguide/VirtualHosting.html#virtual-hosted-style-access)에 지원되지 않습니다. "soap"이 사용되는 객체 키 이름 값의 경우 [경로 스타일 URL](https://docs.aws.amazon.com/AmazonS3/latest/userguide/VirtualHosting.html#path-style-access)을 대신 사용해야 합니다.

**Example**  
이 예제에서는 'quotes' 버킷에서 'Nelson' 객체를 가져옵니다.  
`Sample Request`  

```
 1. <GetObject xmlns="https://doc.s3.amazonaws.com/2006-03-01">
 2.   <Bucket>quotes</Bucket>
 3.   <Key>Nelson</Key>
 4.   <GetMetadata>true</GetMetadata>
 5.   <GetData>true</GetData>
 6.   <InlineData>true</InlineData>
 7.   <AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
 8.   <Timestamp>2006-03-01T12:00:00.183Z</Timestamp>
 9.   <Signature>Iuyz3d3P0aTou39dzbqaEXAMPLE=</Signature>
10. </GetObject>
```
`Sample Response`  

```
 1. <GetObjectResponse xmlns="https://s3.amazonaws.com/doc/2006-03-01">
 2.   <GetObjectResponse>
 3.     <Status>
 4.       <Code>200</Code>
 5.       <Description>OK</Description>
 6.     </Status>
 7.     <Metadata>
 8.       <Name>Content-Type</Name>
 9.       <Value>text/plain</Value>
10.     </Metadata>
11.     <Metadata>
12.       <Name>family</Name>
13.       <Value>Muntz</Value>
14.     </Metadata>
15.     <Data>aGEtaGE=</Data>
16.     <LastModified>2006-01-01T12:00:00.000Z</LastModified>
17.     <ETag>&quot;828ef3fdfa96f00ad9f27c383fc9ac7f&quot;</ETag>
18.   </GetObjectResponse>
19. </GetObjectResponse>
```

## 요소
<a name="SOAPGetObjectElements"></a>
+ `Bucket:` 객체를 검색할 버킷입니다.
+ `Key:` 객체를 식별하는 키입니다.
+ `GetMetadata:` true인 경우 메타데이터가 객체와 함께 반환됩니다.
+ `GetData:` true인 경우 객체 데이터가 반환됩니다.
+ `InlineData:` true인 경우 데이터가 응답의 SOAP 본문의 일부로 Base64로 인코딩된 상태로 반환됩니다. false인 경우 데이터가 SOAP 첨부 파일로 반환됩니다. InlineData 옵션은 대형 객체에 사용하기에 적합하지 않습니다. 시스템은 이 작업을 1MB 이하의 데이터에 사용하도록 제한합니다. InlineData 플래그가 설정된 GetObject 요청은 결과 데이터 파라미터의 인코딩 후 크기가 1MB를 초과하게 될 경우 `InlineDataTooLargeError` 상태 코드와 함께 실패합니다. 대형 객체를 다운로드하려면 InlineData 플래그를 설정하지 않고 GetObject를 직접적으로 호출하거나 대신 REST API를 사용하는 것이 좋습니다.

## 반환된 요소
<a name="SOAPGetObjectReturnedElements"></a>
+ `Metadata:` 객체와 함께 저장된 이름-값 쌍 메타데이터입니다.
+ `Data:` 요청에서 InlineData가 true인 경우 여기에는 Base64로 인코딩된 객체 데이터가 포함됩니다.
+ `LastModified:` 객체가 Amazon S3에 저장된 시간입니다.
+ `ETag:` 객체의 엔터티 태그입니다. 조건부 가져오기를 수행하는 데 사용할 수 있는 객체의 해시입니다. ETag는 객체의 콘텐츠에 대한 변경 사항만 반영하고 메타데이터에 대한 변경을 반영하지 않습니다.

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

객체에 대한 `READ` 액세스 권한이 부여된 경우에만 객체를 읽을 수 있습니다.

## SOAP 청크 다운로드 및 재개 가능 다운로드
<a name="SOAPResumableDownloads"></a>

`GET` 유연성을 제공하기 위해 Amazon S3는 청크 다운로드와 재개 가능한 다운로드를 지원합니다.

다음 중에서 선택합니다.
+ 대형 객체 다운로드의 경우 객체를 작은 청크로 분할해야 할 수 있습니다. 자세한 내용은 [범위 GET](#SOAPRangeGETs) 섹션을 참조하세요.
+ `GET` 작업이 실패하는 경우 전체 파일 대신 나머지 파일을 다운로드하도록 애플리케이션을 설계할 수 있습니다. 자세한 내용은 [REST GET 오류 복구](#SOAPGETErrorRecovery) 섹션을 참조하세요.

### 범위 GET
<a name="SOAPRangeGETs"></a>

일부 클라이언트의 경우 대용량 다운로드를 더 작은 다운로드로 분할할 수 있습니다. GET을 더 작은 단위로 분할하려면 범위를 사용합니다.

GET을 더 작은 단위로 분할하려면 먼저 크기를 결정해야 합니다. 예를 들어 다음 요청은 bigfile 객체의 크기를 가져옵니다.

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

Amazon S3는 다음 응답을 반환합니다.

```
 1. <ListBucketResult xmlns="https://s3.amazonaws.com/doc/2006-03-01">
 2.   <Name>quotes</Name>
 3.   <Prefix>N</Prefix>
 4.   <MaxKeys>1</MaxKeys>
 5.   <IsTruncated>false</IsTruncated>
 6.   <Contents>
 7.     <Key>bigfile</Key>
 8.     <LastModified>2006-01-01T12:00:00.000Z</LastModified>
 9.     <ETag>&quot;828ef3fdfa96f00ad9f27c383fc9ac7f&quot;</ETag>
10.     <Size>2023276</Size>
11.     <StorageClass>STANDARD</StorageClass>
12.     <Owner>
13.       <ID>bcaf1ffd86f41161ca5fb16fd081034f</ID>
14.       <DisplayName>bigfile</DisplayName>
15.      </Owner>
16.   </Contents>
17. </ListBucketResult>
```

다음은 bigfile 객체에서 첫 번째 메가바이트를 다운로드하는 요청입니다.

```
 1. <GetObject xmlns="https://doc.s3.amazonaws.com/2006-03-01">
 2.   <Bucket>bigbucket</Bucket>
 3.   <Key>bigfile</Key>
 4.   <GetMetadata>true</GetMetadata>
 5.   <GetData>true</GetData>
 6.   <InlineData>true</InlineData>
 7.   <ByteRangeStart>0</ByteRangeStart>
 8.   <ByteRangeEnd>1048576</ByteRangeEnd>
 9.   <AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
10.   <Timestamp>2006-03-01T12:00:00.183Z</Timestamp>
11.   <Signature>Iuyz3d3P0aTou39dzbqaEXAMPLE=</Signature>
12. </GetObject>
```

Amazon S3는 파일의 첫 번째 메가바이트와 파일의 Etag를 반환합니다.

```
 1. <GetObjectResponse xmlns="http://s3.amazonaws.com/doc/2006-03-01">
 2.   <GetObjectResponse>
 3.     <Status>
 4.       <Code>200</Code>
 5.       <Description>OK</Description>
 6.     </Status>
 7.     <Metadata>
 8.       <Name>Content-Type</Name>
 9.       <Value>text/plain</Value>
10.     </Metadata>
11.     <Metadata>
12.       <Name>family</Name>
13.       <Value>Muntz</Value>
14.     </Metadata>
15.     <Data>--first megabyte of bigfile--</Data>
16.     <LastModified>2006-01-01T12:00:00.000Z</LastModified>
17.     <ETag>"828ef3fdfa96f00ad9f27c383fc9ac7f"</ETag>
18.   </GetObjectResponse>
19. </GetObjectResponse>
```

이전 부분이 다운로드된 이후 파일이 변경되지 않았는지 확인하려면 IfMatch 요소를 지정합니다. IfMatch 요소가 필수는 아니지만 변경 가능성이 있는 콘텐츠에는 권장됩니다.

다음은 IfMatch 요청 헤더를 사용하여 파일의 나머지 부분을 가져오는 요청입니다.

```
 1. <GetObject xmlns="https://doc.s3.amazonaws.com/2006-03-01">
 2.   <Bucket>bigbucket</Bucket>
 3.   <Key>bigfile</Key>
 4.   <GetMetadata>true</GetMetadata>
 5.   <GetData>true</GetData>
 6.   <InlineData>true</InlineData>
 7.   <ByteRangeStart>10485761</ByteRangeStart>
 8.   <ByteRangeEnd>2023276</ByteRangeEnd>
 9.   <IfMatch>"828ef3fdfa96f00ad9f27c383fc9ac7f"</IfMatch>
10.   <AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
11.   <Timestamp>2006-03-01T12:00:00.183Z</Timestamp>
12.   <Signature>Iuyz3d3P0aTou39dzbqaEXAMPLE=</Signature>
13. </GetObject>
```

Amazon S3는 다음 응답과 함께 파일의 나머지 부분을 반환합니다.

```
 1. <GetObjectResponse xmlns="http://s3.amazonaws.com/doc/2006-03-01">
 2.   <GetObjectResponse>
 3.     <Status>
 4.       <Code>200</Code>
 5.       <Description>OK</Description>
 6.     </Status>
 7.     <Metadata>
 8.       <Name>Content-Type</Name>
 9.       <Value>text/plain</Value>
10.     </Metadata>
11.     <Metadata>
12.       <Name>family</Name>
13.       <Value>>Muntz</Value>
14.     </Metadata>
15.     <Data>--remainder of bigfile--</Data>
16.     <LastModified>2006-01-01T12:00:00.000Z</LastModified>
17.     <ETag>"828ef3fdfa96f00ad9f27c383fc9ac7f"</ETag>
18.   </GetObjectResponse>
19. </GetObjectResponse>
```

### 버전이 지정된 GetObject
<a name="SOAPResumableDownloads-versioned-getobject"></a>

다음 요청은 버킷에 있는 객체의 지정된 버전을 반환합니다.

```
 1. <GetObject xmlns="https://doc.s3.amazonaws.com/2006-03-01">
 2. <Bucket>quotes</Bucket>
 3. <Key>Nelson</Key>
 4. <GetMetadata>true</GetMetadata>
 5. <GetData>true</GetData>
 6. <InlineData>true</InlineData>
 7. <AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
 8. <Timestamp>2006-03-01T12:00:00.183Z</Timestamp>
 9. <Signature>Iuyz3d3P0aTou39dzbqaEXAMPLE=</Signature>
10. </GetObject>
```

샘플 응답

```
 1. <GetObjectResponse xmlns="https://s3.amazonaws.com/doc/2006-03-01">
 2. <GetObjectResponse>
 3. <Status>
 4. <Code>200</Code>
 5. <Description>OK</Description>
 6. </Status>
 7. <Metadata>
 8. <Name>Content-Type</Name>
 9. <Value>text/plain</Value>
10. </Metadata>
11. <Metadata>
12. <Name>family</Name>
13. <Value>Muntz</Value>
14. </Metadata>
15. <Data>aGEtaGE=</Data>
16. <LastModified>2006-01-01T12:00:00.000Z</LastModified>
17. <ETag>&quot;828ef3fdfa96f00ad9f27c383fc9ac7f&quot;</ETag>
18. </GetObjectResponse>
19. </GetObjectResponse>
```

### REST GET 오류 복구
<a name="SOAPGETErrorRecovery"></a>

객체 GET이 실패하면 다운로드할 범위를 지정하여 파일의 나머지 부분을 가져올 수 있습니다. 이렇게 하려면 `ListBucket`을 사용하여 객체의 크기를 가져오고 파일의 나머지 부분에서 범위 `GET`을 수행해야 합니다. 자세한 내용은 [GetObjectExtended(SOAP API)](SOAPGetObjectExtended.md) 섹션을 참조하세요.

### 관련 리소스
<a name="SOAPGettingObjectsRelatedTopics"></a>

[객체에 대한 작업(SOAP API)](SOAPObjectsOps.md)