CopyObject介面用於拷貝一個在OSS上已經存在的object成另外一個object。

該介面可以發送一個PUT請求給OSS，並在PUT要求標頭中添加元素x-oss-copy-source來指定拷貝源。OSS會自動判斷出這是一個Copy操作，並直接在伺服器端執行該操作。如果拷貝成功，則返回新的object資訊給用戶。

該操作適用於拷貝小於1GB的檔案，當拷貝一個大於1GB的檔案時，必須使用Multipart Upload操作，具體見Upload Part Copy。

Copy操作的源Bucket和目標Bucket必須是同一個Region，不同Region的Bucket不能執行Copy Object操作。

請求文法

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

請求Header

名稱 類型 描述
x-oss-copy-source 字元串 複製源地址（必須有可讀許可權）

預設值：無
x-oss-copy-source-if-match 字元串 如果源Object的ETag值和用戶提供的ETag相等，則執行拷貝操作，並返回200；否則返回412 HTTP錯誤碼（預先處理失敗）。

預設值：無
x-oss-copy-source-if-none-match 字元串 如果源Object的ETag值和用戶提供的ETag不相等，則執行拷貝操作，並返回200；否則返回304 HTTP錯誤碼（預先處理失敗）。

預設值：無
x-oss-copy-source-if-unmodified-since 字元串 如果傳入參數中的時間等於或者晚於檔案實際修改時間，則正常傳輸檔案，並返回200 OK；否則返回412 precondition failed錯誤。

預設值：無
x-oss-copy-source-if-modified-since 字元串 如果源Object自從用戶指定的時間以後被修改過，則執行拷貝操作；否則返回304 HTTP錯誤碼（預先處理失敗）。

預設值：無
x-oss-metadata-directive 字元串 有效值為COPY和REPLACE。如果該值設為COPY，則新的Object的meta都從源Object複製過來；如果設為REPLACE，則忽視所有源Object的meta值，而採用用戶這次請求中指定的meta值；其他值則返回400 HTTP錯誤碼。注意該值為COPY時，源Object的x-oss-server-side-encryption的meta值不會進行拷貝。
取值：
  • COPY （預設值）
  • REPLACE
x-oss-server-side-encryption 字元串 指定oss建立目標object時的伺服器端熵編碼密碼編譯演算法

取值：AES256 或 KMS

说明
您需要購買KMS套件，才可以使用KMS密碼編譯演算法，否則會報KmsServiceNotEnabled錯誤碼。
x-oss-object-acl 字元串 指定oss建立object時的存取權限。

取值：public-read，private，public-read-write

響應元素(Response Elements)

表 1. 響應元素
名稱 類型 描述
CopyObjectResult 字元串 Copy Object的結果。

預設值：無
ETag 字元串 新Object的ETag值。

父元素：CopyObjectResult
LastModified 字元串 新Object最後更新時間。

父元素：CopyObjectResult

細節分析

  • 可以通過拷貝操作來實現修改已有Object的meta資訊。
  • 如果拷貝操作的源Object地址和目標Object地址相同，則無論x-oss-metadata-directive為何值，都會直接替換源Object的meta資訊。
  • OSS支援拷貝操作的四個預判斷Header任意個同時出現，相應邏輯參見Get Object操作的細節分析。
  • 拷貝操作需要要求者對源Object有讀許可權。
  • 源Object和目標Object必須屬於同一個資料中心，否則返回403 AccessDenied，錯誤資訊為：Target object does not reside in the same data center as source object。
  • 拷貝操作的計費統計會對源Object所在的Bucket增加一次Get請求次數，並對目標Object所在的Bucket增加一次Put請求次數，以及相應的新增儲存空間。
  • 拷貝操作涉及到的要求標頭，都是以“x-oss-”開頭的，所以要加入簽名字元串中。
  • 若在拷貝操作中指定了x-oss-server-side-encryption要求標頭，並且請求值合法（為AES256），則無論源Object是否進行過伺服器端加密編碼，拷貝之後的目標Object都會進行伺服器端加密編碼。並且拷貝操作的回應標頭中會包含x-oss-server-side-encryption，值被設定成目標Object的密碼編譯演算法。在這個目標Object被下載時，回應標頭中也會包含x-oss-server-side-encryption，值被設定成該Object的密碼編譯演算法；若拷貝操作中未指定x-oss-server-side-encryption要求標頭，則無論源Object是否進行過伺服器端加密編碼，拷貝之後的目標Object都是未進行過伺服器端加密編碼加密的數據。
  • 拷貝操作中x-oss-metadata-directive要求標頭為COPY（預設值）時，並不拷貝源Object的x-oss-server-side-encryption值，即目標Object是否進行伺服器端加密編碼只根據COPY操作是否指定了x-oss-server-side-encryption要求標頭來決定。
  • 若在拷貝操作中指定了x-oss-server-side-encryption要求標頭，並且請求值非AES256，則返回400和相應的錯誤提示：InvalidEncryptionAlgorithmError。
  • 如果拷貝的檔案大小大於1GB，會返回400和錯誤提示：EntityTooLarge。
  • 該操作不能拷貝通過Append追加上傳方式產生的object。
  • 如果檔案類型為符號連結，只拷貝符號連結。

樣本

請求樣本：

PUT /copy_oss.jpg HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 24 Feb 2012 07:18:48 GMT
x-oss-copy-source: /oss-example/oss.jpg
Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:gmnwPKuu20LQEjd+iPkL259A+n0=

返回樣本：

HTTP/1.1 200 OK
x-oss-request-id: 559CC9BDC755F95A64485981
Content-Type: application/xml
Content-Length: 193
Connection: keep-alive
Date: Fri, 24 Feb 2012 07:18:48 GMT
Server: AliyunOSS
<?xml version="1.0" encoding="UTF-8"?>
<CopyObjectResult xmlns=”http://doc.oss-cn-hangzhou.aliyuncs.com”>
 <LastModified>Fri, 24 Feb 2012 07:18:48 GMT</LastModified>
 <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE"</ETag>
</CopyObjectResult>