# 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 />默认值：无<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 />原级：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>
```

此示例将“tweedledee”对象从 wonderland 存储桶复制到 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)