全部產品
Search
文件中心

Object Storage Service:CopyObject

更新時間:Jul 20, 2024

調用CopyObject介面拷貝同一地區下相同或不同儲存空間(Bucket)之間的檔案(Object)。

版本控制

x-oss-copy-source預設拷貝Object的目前的版本,您可以在x-oss-copy-source中加入versionId來拷貝指定的Object版本。拷貝Object時,如果源Object的對應版本為刪除標記,則返回404表示該Object不存在。

如果需要恢複Object的早期版本為目前的版本,您只需將Object的早期版本拷貝到同一個Bucket中,OSS會將該Object對應早期版本置為目前的版本。

如果目標Bucket已開啟版本控制,OSS將會為新拷貝的Object自動產生唯一的版本ID,此版本ID將會在響應Header中的x-oss-version-id返回。如果目標Bucket未開啟或者暫停了版本控制,OSS將會為新拷貝的Object自動產生version ID為null的版本,且會覆蓋原有versionId為null的版本。

使用限制

  • Object大小限制

    • 如果源Bucket和目標Bucket相同,且通過CopyObject拷貝時不修改Object的儲存類型,則Object的大小可以大於5 GB。

    • 如果源Bucket和目標Bucket不同,且通過CopyObject拷貝時不修改Object的儲存類型,則Object的大小不能大於5 GB。

    • 通過CopyObject拷貝時修改Object的儲存類型,則Object的大小不能大於1 GB。如果Object大小超過1 GB,需使用UploadPartCopy介面。

  • 許可權說明

    使用CopyObject或UploadPartCopy介面均要求對源Object有讀許可權。

  • 在非版本控制的Bucket中使用CopyObject,且源Object與目標Object為同一個Object時:

    • 拷貝過程中不涉及修改源Object的加密類型或者儲存類型,則OSS只修改源Object的中繼資料,不拷貝源Object的內容。

    • 拷貝過程中涉及修改源Object的加密類型或者儲存類型,則OSS在修改源Object中繼資料的同時還會拷貝源Object的內容。

  • 源Object為軟連結

    通過CopyObject介面拷貝時,只拷貝軟連結,不支援拷貝軟連結指向的檔案內容。

  • Bucket已開啟階層命名空間

    不支援拷貝該Bucket中的目錄(Directory)。

計量計費

  • 調用一次CopyObject介面只對目標Object所在的Bucket增加一次Put請求次數。

  • 調用CopyObject介面會對目標Object所在的Bucket增加相應的儲存量。

  • 調用CopyObject介面更改Object儲存類型會涉及資料覆蓋。例如低頻訪問IA建立後10天內被覆蓋為標準儲存Standard,則會產生20天的低頻訪問不足規定時間長度容量費用。關於儲存費用的更多資訊,請參見儲存費用

請求文法

PUT /DestObjectName HTTP/1.1
Host: DestBucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue
x-oss-copy-source: /SourceBucketName/SourceObjectName

要求標頭

拷貝操作涉及到的要求標頭均以x-oss-開頭,因此所有要求標頭都要加到簽名字串中。

名稱

類型

是否必選

取值

描述

x-oss-forbid-overwrite

字串

true

指定CopyObject操作時是否覆蓋同名目標Object。當目標Bucket處於已開啟或已暫停版本控制狀態時,x-oss-forbid-overwrite請求Header設定無效,即允許覆蓋同名Object。

  • 未指定x-oss-forbid-overwrite或者指定x-oss-forbid-overwritefalse時,表示允許覆蓋同名目標Object。

  • 指定x-oss-forbid-overwritetrue時,表示禁止覆蓋同名Object。

設定x-oss-forbid-overwrite請求Header會導致QPS處理效能下降,如果您有大量的操作需要使用x-x-oss-forbid-overwrite請求Header(QPS>1000),請聯絡支援人員,避免影響您的業務。

預設值:false

x-oss-copy-source

字串

/oss-example/oss.jpg

指定拷貝的源地址。

預設值:無

x-oss-copy-source-if-match

字串

5B3C1A2E053D763E1B002CC607C5****

如果源Object的ETag值和您提供的ETag相等,則執行拷貝操作,並返回200 OK。

預設值:無

x-oss-copy-source-if-none-match

字串

5B3C1A2E053D763E1B002CC607C5****

如果源Object的ETag值和您提供的ETag不相等,則執行拷貝操作,並返回200 OK。

預設值:無

x-oss-copy-source-if-unmodified-since

字串

Mon, 11 May 2020 08:16:23 GMT

如果指定的時間等於或者晚於檔案實際修改時間,則正常拷貝檔案,並返回200 OK。

預設值:無

x-oss-copy-source-if-modified-since

字串

Mon, 11 May 2020 08:16:23 GMT

如果指定的時間早於檔案實際修改時間,則正常拷貝檔案,並返回200 OK。

預設值:無

x-oss-metadata-directive

字串

COPY

指定如何設定目標Object的中繼資料。

  • COPY(預設值):複製源Object的中繼資料到目標Object。

    OSS不會複製源Object的x-oss-server-side-encryption屬性配置到目標Object。目標Object的伺服器端加密編碼方式取決於當前拷貝操作是否指定了x-oss-server-side-encryption

  • REPLACE:忽略源Object的中繼資料,直接採用請求中指定的中繼資料。

重要

如果拷貝操作的源Object地址和目標Object地址相同,且未開啟版本控制時,則無論x-oss-metadata-directive為何值,都會忽略源Object的中繼資料,目標Object將直接採用請求中指定的中繼資料。

x-oss-server-side-encryption

字串

AES256

指定OSS建立目標Object時,伺服器端使用熵編碼密碼編譯演算法 。

取值:AES256 KMS

您只有購買了KMS套件,才能使用KMS密碼編譯演算法,否則OSS會返回KmsServiceNotEnabled錯誤。

  • 如果拷貝操作中未指定x-oss-server-side-encryption,則無論源Object是否進行過伺服器端加密編碼,拷貝後的目標Object均不進行伺服器端加密編碼。

  • 如果拷貝操作中指定了x-oss-server-side-encryption,則無論源Object是否進行過伺服器端加密編碼,拷貝後的目標Object均會進行伺服器端加密編碼。並且拷貝操作的回應標頭中會包含x-oss-server-side-encryption,值為目標Object的密碼編譯演算法。

    在目標Object被下載時,回應標頭中也會包含x-oss-server-side-encryption,值為該Object的密碼編譯演算法。

x-oss-server-side-encryption-key-id

字串

9468da86-3509-4f8d-a61e-6eab1eac****

表示KMS託管的使用者主要金鑰。

該參數僅在x-oss-server-side-encryption為KMS時有效。

x-oss-object-acl

字串

private

指定OSS建立目標Object時的存取權限。

取值:

  • default(預設):Object遵循所在儲存空間的存取權限。

  • private:Object是私人資源。只有Object的擁有者和授權使用者有該Object的讀寫權限,其他使用者沒有許可權操作該Object。

  • public-read:Object是公用讀取資源。只有Object的擁有者和授權使用者有該Object的讀寫權限,其他使用者只有該Object的讀許可權。請謹慎使用該許可權。

  • public-read-write:Object是公用讀寫資源。所有使用者都有該Object的讀寫權限。請謹慎使用該許可權。

關於存取權限的更多資訊,請參見設定Object ACL

x-oss-storage-class

字串

Standard

指定Object的儲存類型。

對於任意儲存類型Bucket,如果上傳Object時指定該值,則此次上傳的Object將儲存為指定的類型。例如在IA類型的Bucket中上傳Object時,如果指定x-oss-storage-class為Standard,則該Object直接儲存為Standard類型。

取值:

  • Standard(預設):標準儲存

  • IA:低頻訪問

  • Archive:Archive Storage

  • ColdArchive:冷Archive Storage

  • DeepColdArchive:深度冷Archive Storage

    重要

    如果要拷貝的檔案數量較多,直接指定拷貝後的檔案儲存體類型為深度冷歸檔類型會造成較高的PUT類請求費用。建議您通過生命週期規則將檔案轉儲為深度冷歸檔類型,從而降低PUT類請求費用。

關於儲存類型的更多資訊,請參見儲存類型概述

x-oss-tagging

字串

a:1

指定Object的對象標籤,可同時設定多個標籤,例如TagA=A&TagB=B。

說明

Key和Value需要先進行URL編碼,如果某項沒有“=”,則看作Value為空白字元串。

x-oss-tagging-directive

字串

Copy

指定如何設定目標Object的對象標籤。取值如下:

  • Copy(預設值):複製源Object的對象標籤到目標 Object。

  • Replace:忽略源Object的對象標籤,直接採用請求中指定的對象標籤。

此介面還需要包含Host、Date等公用要求標頭。更多資訊,請參見公用要求標頭(Common Request Headers)

回應標頭

此介面僅包含公用回應標頭。更多資訊,請參見公用回應標頭(Common Response Headers)

響應元素

名稱

類型

樣本值

描述

CopyObjectResult

容器

不涉及

儲存CopyObject的結果。

預設值:無

ETag

字串

5B3C1A2E053D763E1B002CC607C5****

目標Object的ETag值。

父元素:CopyObjectResult

LastModified

字串

Fri, 24 Feb 2012 07:18:48 GMT

目標Object最後更新時間。

父元素:CopyObjectResult

樣本

  • 未開啟版本控制

    請求樣本

    PUT /test%2FAK.txt HTTP/1.1
    Host: tesx.oss-cn-zhangjiakou.aliyuncs.com
    Accept-Encoding: identity
    User-Agent: aliyun-sdk-python/2.6.0(Windows/7/AMD64;3.7.0)
    Accept: text/html
    Connection: keep-alive
    x-oss-copy-source: /test/AK.txt
    date: Fri, 28 Dec 2018 09:41:55 GMT
    authorization: OSS qn6qrrqxo2oawuk53otfjbyc:gmnwPKuu20LQEjd+iPkL259A****
    Content-Length: 0

    返回樣本

    x-oss-hash-crc64ecma表示Object的64位CRC值。該64位CRC值根據ECMA-182標準計算得出。進行CopyObject操作時,產生的Object不保證具有64位CRC值。

    HTTP/1.1 200 OK
    Server: AliyunOSS
    Date: Fri, 28 Dec 2018 09:41:56 GMT
    Content-Type: application/xml
    Content-Length: 184
    Connection: keep-alive
    x-oss-request-id: 5C25EFE4462CE00EC6D87156
    ETag: "F2064A169EE92E9775EE5324D0B1****"
    x-oss-hash-crc64ecma: 12753002859196105360
    x-oss-server-time: 150
    <?xml version="1.0" encoding="UTF-8"?>
    <CopyObjectResult>
      <ETag>"F2064A169EE92E9775EE5324D0B1****"</ETag>
      <LastModified>2018-12-28T09:41:56.000Z</LastModified>
    </CopyObjectResult>
  • 未指定versionId進行拷貝

    請求樣本

    PUT /dest-object-example HTTP/1.1
    Host: versioning-copy.oss-cn-hangzhou.aliyuncs.com
    Date: Tue, 09 Apr 2019 03:45:32 GMT
    Authorization: OSS qn6q**************:77Dv****************
    x-oss-copy-source: /versioning-copy-source/source-object

    返回樣本

    樣本中的x-oss-copy-source-version-id為源拷貝Object的versionId,在該樣本中即為源拷貝Object的目前的版本。x-oss-version-id為新拷貝產生Object的versionId。

    HTTP/1.1 200 OK
    x-oss-copy-source-version-id: CAEQNRiBgIC28uaA0BYiIDY5OGIwNmNlNjYyMTRjNTc4N2M2OGNiMjZkZTQ2****
    x-oss-version-id: CAEQNxiBgIDG8uaA0BYiIGZhZDRkZTk5Zjg3YzRhNzdiMWEwZGViNDM1NTFh****
    x-oss-request-id: 5CAC155CB7AEADE01700****
    Content-Type: application/xml
    Content-Length: 184
    Connection: keep-alive
    Date: Tue, 09 Apr 2019 03:45:32 GMT
    Server: AliyunOSS
    <?xml version="1.0" encoding="UTF-8"?>
    <CopyObjectResult>
      <ETag>"C81E728D9D4C2F636F067F89CC14****"</ETag>
      <LastModified>2019-04-09T03:45:32.000Z</LastModified>
    </CopyObjectResult>
  • 指定versionId進行拷貝

    請求樣本

    PUT /dest-object-example HTTP/1.1
    Host: versioning-copy.oss-cn-hangzhou.aliyuncs.com
    Date: Tue, 09 Apr 2019 03:45:32 GMT
    Authorization: OSS qn6q**************:77Dv****************
    x-oss-copy-source: /versioning-copy-source/source-object?versionId=CAEQNRiBgICv8uaA0BYiIDliZDc3MTc1NjE5MjRkMDI4ZGU4MTZkYjY1ZDgy****

    返回樣本

    樣本中的x-oss-copy-source-version-id為源拷貝Object的versionId,在該樣本中即為x-oss-copy-source中versionId指定的版本,x-oss-version-id為新拷貝產生Object的versionId。

    HTTP/1.1 200 OK
    x-oss-copy-source-version-id: CAEQNRiBgICv8uaA0BYiIDliZDc3MTc1NjE5MjRkMDI4ZGU4MTZkYjY1ZDgy****
    x-oss-version-id: CAEQNxiBgMDP8uaA0BYiIDIyNGNhZDQ1M2M3NzRkZThiNzE0N2I3ZDkxOWY4****
    x-oss-request-id: 5CAC155CB7AEADE01700****
    Content-Type: application/xml
    Content-Length: 184
    Connection: keep-alive
    Date: Tue, 09 Apr 2019 03:45:32 GMT
    Server: AliyunOSS
    <?xml version="1.0" encoding="UTF-8"?>
    <CopyObjectResult>
      <ETag>"C4CA4238A0B923820DCC509A6F75****"</ETag>
      <LastModified>2019-04-09T03:45:32.000Z</LastModified>
    </CopyObjectResult>

SDK

此介面所對應的各語言SDK如下:

錯誤碼

錯誤碼

HTTP狀態代碼

描述

InvalidArgument

400

x-oss-storage-class等參數的值無效。

Precondition Failed

412

返回該錯誤的可能原因如下:

  • 指定了x-oss-copy-source-if-match要求標頭,但源Object的ETag值和您提供的ETag值不相等。

  • 指定了x-oss-copy-source-if-unmodified-since要求標頭,但指定的時間早於檔案實際修改時間。

Not Modified

304

返回該錯誤的可能原因如下:

  • 指定了x-oss-copy-source-if-none-match要求標頭,但源Object的ETag值和您提供的ETag值相等。

  • 指定了x-oss-copy-source-if-modified-since要求標頭,但源Object在指定的時間後沒被修改過。

KmsServiceNotEnabled

403

x-oss-server-side-encryption指定為KMS,但沒有預先購買KMS套件。

FileAlreadyExists

409

返回該錯誤的可能原因如下:

  • 請求Header中攜帶了x-oss-forbid-overwrite=true來禁止覆蓋同名檔案,但是Bucket中已有同名檔案。

  • Bucket開啟階層命名空間後,當您要在該Bucket下拷貝Object時,設定的源Object或者目標Object為目錄。

FileImmutable

409

Bucket內的資料處於被保護狀態時,如果嘗試刪除或修改這些資料,則返回該錯誤。

常見問題

CopyObject是否支援批量複製檔案?

不支援。CopyObject用於複製單個檔案。如果需要批量複製檔案,您可以使用ossutil工具。更多資訊,請參見cp(拷貝檔案)