全部產品
Search

搜尋本產品

    Object Storage Service：CopyObject

    文件中心

    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-overwrite為false時，表示允許覆蓋同名目標Object。

    • 指定x-oss-forbid-overwrite為true時，表示禁止覆蓋同名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（拷貝檔案）。