本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

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

**注意**  
 Amazon S3 的 SOAP API 不適用於新客戶，並且將於 2025 年 8 月 31 日接近生命週期結束 (EOL)。我們建議您使用 REST API 或 AWS SDKs。

## 說明
<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 />預設：無<br />限制條件：有效的來源儲存貯體。 |  是  | 
|  SourceKey  | 來源物件的金鑰名稱。<br />類型：字串<br />預設：無<br />限制：您具有 READ 存取權之有效來源物件的金鑰。 |  是  | 
|  DestinationBucket  | 目的地 儲存貯體的名稱。<br />類型：字串<br />預設：無<br />限制條件：您必須擁有目的地儲存貯體的 WRITE 存取權。 |  是  | 
|  DestinationKey  |  目的地物件的金鑰。<br />類型：字串<br />預設：無<br />限制條件：您必須擁有目的地儲存貯體的 WRITE 存取權。 |  是  | 
|  MetadataDirective  |  指定中繼資料是從來源物件複製，還是取代為請求中提供的中繼資料。<br />類型：字串<br />預設：COPY<br />有效值：COPY \| REPLACE<br />限制條件： `COPY`或 以外的值`REPLACE`將導致立即錯誤。除非已指定 MetadataDirective 標頭，且其值設為 ，否則您無法將物件複製到其本身`REPLACE`。 |  否  | 
|  Metadata  |  指定要為物件設定的中繼資料名稱/值對。如果 MetadataDirective 設定為 `COPY`，則會忽略所有中繼資料。<br />類型：字串<br />預設：無<br />限制條件：無。 |  否  | 
|  AccessControlList  | 授予使用者電子郵件地址或正式使用者 ID 的存取權。<br />類型：字串<br />預設：無<br />限制條件：無 |  否  | 
|  CopySourceIfMatch  | 如果物件的實體標籤 (ETag) 符合指定的標籤，則複製物件；否則傳回 PreconditionFailed。<br />類型：字串<br />預設：無<br />限制條件：無。如果 Etag 不相符，則不會複製物件。 |  否  | 
|  CopySourceIfNoneMatch  | 如果物件的實體標籤 (ETag) 與指定的 Etag 不同，則複製物件；否則 會傳回錯誤。<br />類型：字串<br />預設：無<br />限制條件：無。 |  否  | 
|  CopySourceIfUnmodifiedSince  |  如果物件自指定時間以來尚未修改，請複製物件；否則 會傳回 PreconditionFailed。<br />類型：dateTime<br />預設：無 |  否  | 
|  CopySourceIfModifiedSince  | 如果物件自指定時間以來已經過修改，則複製物件；否則 會傳回錯誤。<br />類型：dateTime<br />預設：無 |  否  | 

## 回應語法
<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>
```

## 回應元素
<a name="SOAPCopyObject_CommonResponseElements"></a>

以下是回應元素的清單。

**注意**  
 SOAP API 不會傳回額外的空格。只有 REST API 會傳回額外的空格。


|  名稱  |  描述  | 
| --- | --- | 
|  Etag  | 傳回新物件的 etag。ETag 只會反映物件內容的變更，而不是其中繼資料。<br />類型：字串<br />Ancestor：CopyObjectResult | 
|  LastModified  | 傳回物件上次修改的日期。<br />類型：字串<br />Ancestor：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>
```

此範例會將「tweedledee」物件從奇觀樂園儲存貯體複製到奇觀樂園儲存貯體的「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)