# CopyObject(SOAP API)
<a name="SOAPCopyObject"></a>

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

## 설명
<a name="SOAPCopyObject_Description"></a>

소스 객체의 키 및 버킷과 대상의 키 및 버킷을 지정하면 `CopyObject` 작업이 객체의 복사본을 생성합니다.

객체를 복사할 때 모든 메타데이터를 보존(기본값)하거나 새 메타데이터를 지정할 수 있습니다. 그러나 ACL은 보존되지 않으며 요청을 하는 사용자에 대해 `private`으로 설정됩니다. 기본 ACL 설정을 재정의하려면 복사 요청을 생성할 때 새 ACL을 지정합니다. 자세한 내용은 [ACL 사용](https://docs.aws.amazon.com/AmazonS3/latest/userguide/S3_ACLs_UsingACLs.html)을 참조하십시오.

모든 복사 요청은 인증되어야 합니다. 또한 소스 객체에 대한 *읽기* 액세스 권한과 대상 버킷에 대한 *쓰기* 액세스 권한이 있어야 합니다. 자세한 내용은 [인증 액세스 사용](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-access-control.html)을 참조하세요.

Etag가 일치하는지 여부 또는 객체가 지정된 날짜 이전 또는 이후에 수정되었는지 여부와 같은 특정 조건에서만 객체를 복사하려면 요청 파라미터 `CopySourceIfUnmodifiedSince`, `CopyIfUnmodifiedSince`, `CopySourceIfMatch` 또는 `CopySourceIfNoneMatch`를 사용합니다.

**참고**  
 대형 객체를 복사하기 위해 SOAP 스택 소켓 제한 시간을 구성해야 할 수 있습니다.

## 구문 요청
<a name="SOAPCopyObject_RequestSyntax"></a>

```
 1. <CopyObject xmlns="http://bucket_name.s3.amazonaws.com/2006-03-01">
 2.   <SourceBucket>source_bucket</SourceBucket>
 3.   <SourceObject>source_object</SourceObject>
 4.   <DestinationBucket>destination_bucket</DestinationBucket>
 5.   <DestinationObject>destination_object</DestinationObject>
 6.   <MetadataDirective>{REPLACE | COPY}</MetadataDirective>
 7.   <Metadata>
 8.     <Name>metadata_name</Name>
 9.     <Value>metadata_value</Value>
10.   </Metadata>
11.   ...
12.   <AccessControlList>
13.     <Grant>
14.       <Grantee xsi:type="user_type">
15.         <ID>user_id</ID>
16.         <DisplayName>display_name</DisplayName>
17.       </Grantee>
18.       <Permission>permission</Permission>
19.     </Grant>
20.     ...
21.   </AccessControlList>
22.   <CopySourceIfMatch>etag</CopySourceIfMatch>
23.   <CopySourceIfNoneMatch>etag</CopySourceIfNoneMatch>
24.   <CopySourceIfModifiedSince>date_time</CopySourceIfModifiedSince>
25.   <CopySourceIfUnmodifiedSince>date_time</CopySourceIfUnmodifiedSince>
26.   <AWSAccessKeyId>AWSAccessKeyId</AWSAccessKeyId>
27.   <Timestamp>TimeStamp</Timestamp>
28.   <Signature>Signature</Signature>
29. </CopyObject>
```

## 요청 파라미터
<a name="SOAPCopyObject_RequestParameters"></a>


|  이름  |  설명  |  필수  | 
| --- | --- | --- | 
|  SourceBucket  | 소스 버킷의 이름입니다.<br />유형: 문자열<br />기본값: None<br />제약 조건: 유효한 소스 버킷. |  예  | 
|  SourceKey  | 소스 객체의 키 이름입니다.<br />유형: 문자열<br />기본값: None<br />제약 조건: READ 액세스 권한이 있는 유효한 소스 객체의 키. |  예  | 
|  DestinationBucket  | 대상 버킷의 이름입니다.<br />유형: 문자열<br />기본값: None<br />제약 조건: 대상 버킷에 대한 WRITE 액세스 권한이 있어야 합니다. |  예  | 
|  DestinationKey  |  대상 객체의 키입니다.<br />유형: 문자열<br />기본값: None<br />제약 조건: 대상 버킷에 대한 WRITE 액세스 권한이 있어야 합니다. |  예  | 
|  MetadataDirective  |  메타데이터가 소스 객체에서 복사되는지 아니면 요청에 제공된 메타데이터로 대체되는지 지정합니다.<br />유형: 문자열<br />기본값: COPY<br />유효한 값: COPY \| REPLACE<br />제약 조건: `COPY` 또는 `REPLACE` 이외의 값은 즉시 오류가 발생합니다. MetadataDirective 헤더를 지정하고 해당 값을 `REPLACE`로 설정하지 않으면 객체를 자체로 복사할 수 없습니다. |  아니요  | 
|  Metadata  |  객체에 설정할 메타데이터 이름-값 쌍을 지정합니다. MetadataDirective가 `COPY`로 설정된 경우 모든 메타데이터가 무시됩니다.<br />유형: 문자열<br />기본값: None<br />제약 조건: 없음. |  아니요  | 
|  AccessControlList  | 이메일 주소 또는 정식 사용자 ID를 기준으로 사용자에게 액세스 권한을 부여합니다.<br />유형: 문자열<br />기본값: None<br />제약 조건: 없음 |  아니요  | 
|  CopySourceIfMatch  | 객체의 엔터티 태그(ETag)가 지정된 태그와 일치하면 객체를 복사하고, 그렇지 않으면 PreconditionFailed를 반환합니다.<br />유형: 문자열<br />기본값: None<br />제약 조건: 없음. Etag가 일치하지 않으면 객체가 복사되지 않습니다. |  아니요  | 
|  CopySourceIfNoneMatch  | 객체의 엔터티 태그(ETag)가 지정된 Etag와 다르면 객체를 복사하고, 그렇지 않으면 오류를 반환합니다.<br />유형: 문자열<br />기본값: None<br />제약 조건: 없음. |  아니요  | 
|  CopySourceIfUnmodifiedSince  |  객체가 지정된 시간 이후에 수정되지 않았으면 객체를 복사하고, 그렇지 않으면 PreconditionFailed를 반환합니다.<br />유형: 날짜/시간<br />기본값: None |  아니요  | 
|  CopySourceIfModifiedSince  | 객체가 지정된 시간 이후에 수정되었으면 객체를 복사하고, 그렇지 않으면 오류를 반환합니다.<br />유형: 날짜/시간<br />기본값: None |  아니요  | 

## Response Syntax
<a name="SOAPCopyObject_ResponseSyntax"></a>

```
1. <CopyObjectResponse xmlns="http://bucket_name.s3.amazonaws.com/2006-03-01">
2.   <CopyObjectResponse>
3.     <ETag>"etag"</ETag>
4.     <LastModified>timestamp</LastModified>
5.   </CopyObjectResponse>
6. </CopyObjectResponse>
```

## Response Elements
<a name="SOAPCopyObject_CommonResponseElements"></a>

다음은 응답 요소의 목록입니다.

**참고**  
 SOAP API는 추가 공백을 반환하지 않습니다. 추가 공백은 REST API에서만 반환됩니다.


|  이름  |  설명  | 
| --- | --- | 
|  Etag  | 새 객체의 etag를 반환합니다. ETag는 객체의 콘텐츠에 대한 변경 사항만 반영하고 메타데이터에 대한 변경을 반영하지 않습니다.<br />유형: 문자열<br />상위 항목: CopyObjectResult | 
|  LastModified  | 객체가 마지막으로 수정된 날짜를 반환합니다.<br />유형: 문자열<br />상위 항목: CopyObjectResult | 

일반 응답 요소에 대한 자세한 내용은 [REST 오류 응답 헤더 사용](https://docs.aws.amazon.com/AmazonS3/latest/userguide/HandlingErrors.html#UsingRESTErrorResponseHeaders)을 참조하세요.

## 특수 오류
<a name="SOAPCopyObject_SpecialErrors"></a>

이 작업에는 특수 오류가 없습니다. Amazon S3 오류에 관한 일반 정보는 [오류 코드 목록](ErrorResponses.md#ErrorCodeList) 섹션을 참조하세요.

## 예제
<a name="SOAPCopyObject_Examples"></a>

이 예제는 메타데이터를 유지하면서 `flotsam` 버킷의 `pacific` 객체를 `jetsam` 버킷의 `atlantic` 객체로 복사합니다.

### 샘플 요청
<a name="SOAPCopyObject_Examples_Request1"></a>

```
1. <CopyObject xmlns="http://doc.s3.amazonaws.com/2006-03-01">
2.   <SourceBucket>pacific</SourceBucket>
3.   <SourceObject>flotsam</SourceObject>
4.   <DestinationBucket>atlantic</DestinationBucket>
5.   <DestinationObject>jetsam</DestinationObject>
6.   <AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
7.   <Timestamp>2008-02-18T13:54:10.183Z</Timestamp>
8.   <Signature>Iuyz3d3P0aTou39dzbq7RrtSFmw=</Signature>
9. </CopyObject>
```

### 샘플 응답
<a name="SOAPCopyObject_Examples_Response1"></a>

```
1. <CopyObjectResponse xmlns="http://doc.s3.amazonaws.com/2006-03-01">
2.   <CopyObjectResponse>
3.     <ETag>"828ef3fdfa96f00ad9f27c383fc9ac7f"</ETag>
4.     <LastModified>2008-02-18T13:54:10.183Z</LastModified>
5.   </CopyObjectResponse>
6. </CopyObjectResponse>
```

이 예제에서는 wonderland 버킷의 'tweedledee' 객체를 wonderland 버킷의 'tweedledum' 객체로 복사하여 해당 메타데이터를 대체합니다.

### 샘플 요청
<a name="SOAPCopyObject_Examples_Request2"></a>

```
 1. <CopyObject xmlns="http://doc.s3.amazonaws.com/2006-03-01">
 2.   <SourceBucket>wonderland</SourceBucket>
 3.   <SourceObject>tweedledee</SourceObject>
 4.   <DestinationBucket>wonderland</DestinationBucket>
 5.   <DestinationObject>tweedledum</DestinationObject>
 6.   <MetadataDirective >REPLACE</MetadataDirective >
 7.   <Metadata>
 8.     <Name>Content-Type</Name>
 9.     <Value>text/plain</Value>
10.   </Metadata>
11.   <Metadata>
12.     <Name>relationship</Name>
13.     <Value>twins</Value>
14.   </Metadata>
15.   <AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
16.   <Timestamp>2008-02-18T13:54:10.183Z</Timestamp>
17.   <Signature>Iuyz3d3P0aTou39dzbq7RrtSFmw=</Signature>
18. </CopyObject>
```

### 샘플 응답
<a name="SOAPCopyObject_Examples_Response2"></a>

```
1. <CopyObjectResponse xmlns="http://doc.s3.amazonaws.com/2006-03-01">
2.   <CopyObjectResponse>
3.     <ETag>"828ef3fdfa96f00ad9f27c383fc9ac7f"</ETag>
4.     <LastModified>2008-02-18T13:54:10.183Z</LastModified>
5.   </CopyObjectResponse>
6. </CopyObjectResponse>
```

## 관련 리소스
<a name="SOAPCopyObject_RelatedResources"></a>
+  [PutObject(SOAP API)](SOAPPutObject.md) 
+  [PutObjectInline(SOAP API)](SOAPPutObjectInline.md)