本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
CopyObject (SOAP API)
注意
Amazon S3 的 SOAP API 不適用於新客戶，並且將於 2025 年 8 月 31 日接近生命週期結束 (EOL)。我們建議您使用 REST API 或 AWS SDKs。
說明
當您指定來源物件的金鑰和儲存貯體，以及目標目的地的金鑰和儲存貯體時， 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 限制條件： |
否 |
Metadata
|
指定要為物件設定的中繼資料名稱/值對。如果 MetadataDirective 設定為 類型：字串 預設：無 限制條件：無。 |
否 |
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 只會反映物件內容的變更，而不是其中繼資料。 類型：字串 Ancestor：CopyObjectResult |
LastModified
|
傳回物件上次修改的日期。 類型：字串 Ancestor：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」物件從奇觀樂園儲存貯體複製到奇觀樂園儲存貯體的「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>
相關資源
