View a markdown version of this page

CopyObject（SOAP API） - Amazon Simple Storage Service
说明请求语法请求参数响应语法响应元素特殊错误示例相关资源

CopyObject（SOAP API）

注意

Amazon S3 的 SOAP API 不适用于新客户，并将于 2025 年 8 月 31 日接近使用寿命终止（EOL）。我们建议您使用 REST API 或 AWS SDK。

说明

当您指定源对象的键和存储桶以及目标目的地的键和存储桶时，CopyObject 操作创建对象的副本。

复制对象时，您可以保留所有元数据（默认）或指定新的元数据。但是，ACL 不予以保留，而是针对发出请求的用户设置为 private。要覆盖默认 ACL 设置，请在生成复制请求时指定新的 ACL。有关更多信息，请参阅使用 ACL。

所有复制请求都必须进行身份验证。此外，您必须对源对象拥有读取访问权限，并对目标存储桶拥有写入访问权限。有关更多信息，请参阅使用身份验证访问。

要仅在某些条件下才复制对象，例如 Etag 是否匹配或者对象是在指定日期之前还是之后修改的，请使用请求参数 CopySourceIfUnmodifiedSince、CopyIfUnmodifiedSince、CopySourceIfMatch 或 CopySourceIfNoneMatch。

注意

您可能需要为复制大型对象配置 SOAP 堆栈套接字超时。

请求语法


<CopyObject xmlns="http://bucket_name.s3.amazonaws.com/2006-03-01">
  <SourceBucket>source_bucket</SourceBucket>
  <SourceObject>source_object</SourceObject>
  <DestinationBucket>destination_bucket</DestinationBucket>
  <DestinationObject>destination_object</DestinationObject>
  <MetadataDirective>{REPLACE | COPY}</MetadataDirective>
  <Metadata>
    <Name>metadata_name</Name>
    <Value>metadata_value</Value>
  </Metadata>
  ...
  <AccessControlList>
    <Grant>
      <Grantee xsi:type="user_type">
        <ID>user_id</ID>
        <DisplayName>display_name</DisplayName>
      </Grantee>
      <Permission>permission</Permission>
    </Grant>
    ...
  </AccessControlList>
  <CopySourceIfMatch>etag</CopySourceIfMatch>
  <CopySourceIfNoneMatch>etag</CopySourceIfNoneMatch>
  <CopySourceIfModifiedSince>date_time</CopySourceIfModifiedSince>
  <CopySourceIfUnmodifiedSince>date_time</CopySourceIfUnmodifiedSince>
  <AWSAccessKeyId>AWSAccessKeyId</AWSAccessKeyId>
  <Timestamp>TimeStamp</Timestamp>
  <Signature>Signature</Signature>
</CopyObject>

请求参数

名称 描述 必填
SourceBucket

源存储桶的名称。

类型：字符串

默认值：无

约束：有效的源存储桶。

 是
SourceKey

源对象的键名称。

类型：字符串

默认值：无

约束：您拥有 READ 访问权限的有效源对象的键。

 是
DestinationBucket

目标 存储桶的名称。

类型：字符串

默认值：无

约束：您必须对目标存储桶拥有 WRITE 权限。

 是
DestinationKey

目标对象的键。

类型：字符串

默认值：无

约束：您必须对目标存储桶拥有 WRITE 权限。

 是
MetadataDirective

指定是从源对象复制元数据，还是用请求中提供的元数据替换元数据。

类型：字符串

默认：COPY

有效值：COPY | REPLACE

约束：除 COPY 或 REPLACE 以外的值将立即导致错误。除非指定 MetadataDirective 标头且其值设置为 REPLACE，否则您无法将对象复制到其自身。

 否
Metadata

指定要为对象设置的元数据名称-值对。如果 MetadataDirective 设置为 COPY，则忽略所有元数据。

类型：字符串

默认值：无

约束：无。

 否
AccessControlList

按电子邮件地址或规范用户 ID 向用户授予访问权限。

类型：字符串

默认值：无

约束：无

 否
CopySourceIfMatch

如果对象的实体标签（ETag）与指定的标签匹配，则复制该对象；否则返回 PreconditionFailed。

类型：字符串

默认值：无

约束：无。如果 Etag 不匹配，则不会复制对象。

 否
CopySourceIfNoneMatch

如果对象的实体标签（ETag）与指定的 Etag 不同，则复制该对象；否则返回错误。

类型：字符串

默认值：无

约束：无。

 否
CopySourceIfUnmodifiedSince

如果自指定的时间以来未修改过对象，则复制该对象；否则返回 PreconditionFailed。

类型：dateTime

默认值：无

 否
CopySourceIfModifiedSince

如果对象自指定的时间以来已被修改，则复制该对象；否则返回错误。

类型：dateTime

默认值：无

 否

响应语法

<CopyObjectResponse xmlns="http://bucket_name.s3.amazonaws.com/2006-03-01">
  <CopyObjectResponse>
    <ETag>"etag"</ETag>
    <LastModified>timestamp</LastModified>
  </CopyObjectResponse>
</CopyObjectResponse>

响应元素

以下是响应元素的列表。

注意

SOAP API 不返回额外的空格。额外的空格只会由 REST API 返回。

名称 描述
Etag

返回新对象的 ETag。ETag 仅反映对于对象内容的更改，而不反映对其元数据的更改。

类型：字符串

原级：CopyObjectResult
LastModified

返回上次修改对象的日期。

类型：字符串

原级：CopyObjectResult

有关常规响应元素的信息，请参阅使用 REST 错误响应标头。

特殊错误

此操作没有特殊错误。有关一般 Amazon S3 错误的信息，请参阅错误代码列表。

示例

本示例将 flotsam 存储桶中的 pacific 对象复制到 jetsam 存储桶的 atlantic 对象，同时保留其元数据。

示例请求

<CopyObject xmlns="http://doc.s3.amazonaws.com/2006-03-01">
  <SourceBucket>pacific</SourceBucket>
  <SourceObject>flotsam</SourceObject>
  <DestinationBucket>atlantic</DestinationBucket>
  <DestinationObject>jetsam</DestinationObject>
  <AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
  <Timestamp>2008-02-18T13:54:10.183Z</Timestamp>
  <Signature>Iuyz3d3P0aTou39dzbq7RrtSFmw=</Signature>
</CopyObject>

示例响应

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

此示例将“tweedledee”对象从 wonderland 存储桶复制到 wonderland 存储桶的“tweedledum”对象，同时替换其元数据。

示例请求

<CopyObject xmlns="http://doc.s3.amazonaws.com/2006-03-01">
  <SourceBucket>wonderland</SourceBucket>
  <SourceObject>tweedledee</SourceObject>
  <DestinationBucket>wonderland</DestinationBucket>
  <DestinationObject>tweedledum</DestinationObject>
  <MetadataDirective >REPLACE</MetadataDirective >
  <Metadata>
    <Name>Content-Type</Name>
    <Value>text/plain</Value>
  </Metadata>
  <Metadata>
    <Name>relationship</Name>
    <Value>twins</Value>
  </Metadata>
  <AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
  <Timestamp>2008-02-18T13:54:10.183Z</Timestamp>
  <Signature>Iuyz3d3P0aTou39dzbq7RrtSFmw=</Signature>
</CopyObject>

示例响应

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

相关资源