cp（拷貝文件）
拷貝文件（Object）是指在不改變文件內(nèi)容的情況下，將同一地域下的源存儲空間（Bucket）內(nèi)的文件復(fù)制到目標Bucket，或者將文件復(fù)制到相同存儲空間（Bucket）的其他目錄。您可以通過ossutil的cp完成拷貝。
注意事項
要拷貝文件，您必須具有
oss:GetObject、oss:ListObjects和oss:PutObject權(quán)限。具體操作，請參見為RAM用戶授權(quán)自定義的權(quán)限策略。從ossutil 1.6.16版本開始，命令行中Binary名稱支持直接使用ossutil，您無需根據(jù)系統(tǒng)刷新Binary名稱。如果您的ossutil版本低于1.6.16，則需要根據(jù)系統(tǒng)刷新Binary名稱。更多信息，請參見命令行工具ossutil命令參考。
不支持通過cp命令跨賬號或者跨地域拷貝文件。如果您需要跨賬號或者跨地域拷貝（遷移）文件，請使用ossimport或者在線遷移服務(wù)。
目前只支持拷貝文件，不支持拷貝未完成的分片（Part）。
不支持對通過追加上傳方式生成的Object進行拷貝。
您需要有源Object的讀權(quán)限及目標Bucket的讀寫權(quán)限，否則無法完成拷貝操作。關(guān)于拷貝文件的更多信息，請參見拷貝文件。
當您在OSS ON云盒中使用該命令時：
將配置文件中的Endpoint替換為云盒Endpoint。更多信息，請參見云盒Endpoint。
在本文已有示例的基礎(chǔ)上添加--sign-version、--region以及--cloudbox-id選項。關(guān)于這三個選項的具體用法，請參見通用選項。
命令格式
ossutil cp cloud_url cloud_url
[-r, --recursive]
[-f --force]
[-u --update]
[--disable-ignore-error]
[--only-current-dir]
[--bigfile-threshold <value>]
[--part-size <value>]
[--checkpoint-dir <value>]
[--encoding-type <value>]
[--include <value>]
[--exclude <value>]
[--meta <value>]
[--acl <value>]
[--disable-crc64]
[--payer <value>]
[-j, --job <value>]
[--parallel <value>]
[--version-id <value>]
[--start-time <value>]
[--end-time <value>]參數(shù)及選項說明如下：
配置項 | 說明 |
cloud_url | 分別填寫OSS源文件和目標文件路徑。格式為 |
-r, --recursive | 遞歸操作。當指定該選項時，ossutil會對Bucket下所有符合條件的Object進行操作，否則只對指定的單個Object進行操作。 |
-f --force | 強制操作，不進行詢問提示。 |
-u，--update | 只有當目標文件不存在，或源文件的最后修改時間晚于目標文件時，ossutil才會執(zhí)行拷貝操作。 |
--disable-ignore-error | 批量操作時不忽略錯誤。 |
--only-current-dir | 僅拷貝當前目錄下的文件，忽略子目錄及子目錄下的文件。 |
-bigfile-threshold | 設(shè)置斷點續(xù)傳文件的大小閾值，單位為字節(jié)。 默認值：100 MB 取值范圍：0~9223372036854775807 |
--part-size | 設(shè)置分片大小，單位為字節(jié)。默認情況下ossutil會根據(jù)文件大小自行計算合適的分片大小值。 取值范圍：1~9223372036854775807 |
--checkpoint-dir | 指定斷點續(xù)傳記錄信息所在的目錄。斷點續(xù)傳操作失敗時，ossutil會自動創(chuàng)建名為 |
--encoding-type | 文件名稱的編碼方式。取值為url。如果不指定該選項，則表示文件名稱未經(jīng)過編碼。 |
--include | 包含符合指定條件的所有文件。 |
--exclude | 不包含任何符合指定條件的文件。 |
--meta | 設(shè)置文件的元數(shù)據(jù)，格式為 |
--acl | 文件的讀寫權(quán)限ACL。取值如下：
|
--disable-crc64 | 關(guān)閉CRC64數(shù)據(jù)校驗。默認情況下，ossutil進行數(shù)據(jù)傳輸時都會打開CRC64校驗。 |
--payer | 請求的支付方式。如果希望訪問指定路徑下的資源產(chǎn)生的流量、請求次數(shù)等費用由請求者支付，請將此選項的值設(shè)置為requester。 |
-j，--jobs | 多文件操作時的并發(fā)任務(wù)數(shù)，默認值為3，取值范圍為1~10000。 |
--parallel | 單文件操作時的并發(fā)任務(wù)數(shù)，取值范圍為1~10000。 如果不設(shè)置此選項，默認由ossutil根據(jù)操作類型和文件大小自行決定。 |
--version-id | 拷貝指定版本的文件，僅支持在已開啟版本控制的Bucket內(nèi)使用。 |
--start-time | Unix時間戳。如果輸入這個選項，最后更新時間早于該時間的Object會被忽略。 說明 僅1.7.18及以上版本支持設(shè)置該參數(shù)。關(guān)于如何升級版本，請參見update（ossutil版本升級）。 |
--end-time | Unix時間戳。如果使用該選項，則最后更新時間晚于通過此選項指定時間的Object會被忽略。 說明
|
從以上命令格式中的-j，--jobs和--parallel選項得知，當ossutil自行設(shè)置的默認并發(fā)數(shù)達不到用戶的性能要求時，您可以自行調(diào)整這兩個選項來升降性能。默認情況下，ossutil會根據(jù)文件大小來計算parallel個數(shù)。當批量拷貝大文件時，實際的并發(fā)數(shù)為jobs個數(shù)乘以parallel個數(shù)。
當ECS虛擬機或者服務(wù)器在網(wǎng)絡(luò)、內(nèi)存、CPU等資源不是特別充足的情況下，建議將并發(fā)數(shù)調(diào)整到100以下。如果網(wǎng)絡(luò)、內(nèi)存、CPU等資源沒有占滿，可以適當增加并發(fā)數(shù)。
由于線程間資源切換及搶奪等原因，如果并發(fā)數(shù)過大，ossutil拷貝性能可能會下降。此外，并發(fā)數(shù)過大還可能產(chǎn)生EOF錯誤。所以請根據(jù)實際的機器情況調(diào)整-j，--jobs和--parallel選項的數(shù)值。如果要進行壓測，可在一開始時調(diào)低這兩項數(shù)值，然后逐漸調(diào)大直至找到最優(yōu)值。
示例環(huán)境
本文以Linux系統(tǒng)為例，演示如何在不同目錄或不同Bucket之間拷貝文件。您在實際使用中，請根據(jù)您的系統(tǒng)和使用環(huán)境修改對應(yīng)參數(shù)。示例環(huán)境如下：
操作系統(tǒng)：Linux
源Bucket：examplebucket1
源Bucket指定目錄1：srcfolder1
源Bucket指定目錄2：srcfolder2
目標Bucket：examplebucket2
目標Bucket指定目錄：desfolder
是否拷貝源目錄
拷貝文件時，如果源路徑末尾沒有攜帶正斜線（/），則拷貝與指定前綴匹配的所有文件到目標Bucket。如果源路徑末尾攜帶了正斜線（/），則僅拷貝指定目錄下的文件拷到目標Bucket。
假設(shè)源存儲空間examplebucket1指定目錄srcfolder1下包含以下文件：
srcfolder1/exampleobject1.txt
srcfolder1/exampleobject2.png
srcfolder1/dir1/
srcfolder1/dir1/exampleobject3.jpg
srcfolder1/dir2/
srcfolder1/dir2/exampleobject4.jpg拷貝時指定的源路徑不以正斜線（/）結(jié)尾
ossutil cp oss://examplebucket1/srcfolder1 oss://examplebucket2 -r拷貝完成后，目標存儲空間examplebucket2下將新增以下文件：
srcfolder1/exampleobject1.txt srcfolder1/exampleobject2.png srcfolder1/dir1/ srcfolder1/dir1/exampleobject3.jpg srcfolder1/dir2/ srcfolder1/dir2/exampleobject4.jpg拷貝時指定的源路徑以正斜線（/）結(jié)尾
ossutil cp oss://examplebucket1/srcfolder1/ oss://examplebucket2 -r拷貝完成后，目標存儲空間examplebucket2下將新增以下文件：
exampleobject1.txt exampleobject2.png dir1/ dir1/exampleobject3.jpg dir2/ dir2/exampleobject4.jpg
簡單拷貝文件
拷貝單個文件
ossutil cp oss://examplebucket1/examplefile.txt oss://examplebucket1/srcfolder2/拷貝增量文件
批量拷貝時，如果指定--update選項，只有當目標文件不存在，或源文件的最后修改時間晚于目標文件時，ossutil才會執(zhí)行拷貝操作。命令如下：
ossutil cp oss://examplebucket1/srcfolder1/ oss://examplebucket2/path2/ -r --update該選項可用于當批量拷貝失敗重傳時，跳過已經(jīng)拷貝成功的文件，實現(xiàn)增量拷貝。
批量拷貝文件
限定srcfolder1中文件的修改時間，在北京時間2023年10月31日10:09:18至2023年10月31日12:55:58內(nèi)時，文件才會被拷貝。
ossutil cp -r oss://examplebucket1/srcfolder1/ oss://examplebucket2/path2/ --start-time 1698718158 --end-time 1698728158重命名文件
ossutil cp oss://examplebucket1/examplefile.txt oss://examplebucket1/example.txt通過cp命令重命名文件時，原文件仍存在，您可以在重命名后刪除原文件。
僅拷貝當前目錄下的文件，忽略子目錄
ossutil cp oss://examplebucket1/srcfolder1/ oss://examplebucket1/srcfolder2/ --only-current-dir -r修改文件meta信息
拷貝文件的同時可以使用--meta選項修改文件的meta信息，其內(nèi)容格式為
header:value#header:value...。ossutil cp oss://examplebucket1/examplefile.txt oss://examplebucket1/ --meta=Cache-Control:no-cache從開通了請求者付費模式的Bucket拷貝文件到普通Bucket
ossutil cp oss://examplebucket1/examplefile.txt oss://examplebucket2/desfolder/ --payer=requester
拷貝符合指定條件的文件
您可以使用--include和--exclude參數(shù)，在拷貝時選定符合條件的文件。
拷貝所有文件格式不為JPG的文件
ossutil cp oss://examplebucket1/srcfolder1/ oss://examplebucket2/desfolder/ --exclude "*.jpg" -r拷貝所有文件名包含abc且不是JPG和TXT格式的文件
ossutil cp oss://examplebucket1/srcfolder1/ oss://examplebucket2/desfolder/ --include "*abc*" --exclude "*.jpg" --exclude "*.txt" -r
修改文件存儲類型
您可以在覆寫 文件時，添加--meta選項來修改文件存儲類型。存儲類型可選值為：
Standard：標準存儲
說明在OSS ON云盒使用場景中，僅支持Standard類型。
IA：低頻訪問
Archive：歸檔存儲
ColdArchive：冷歸檔存儲
DeepColdArchive：深度冷歸檔存儲
關(guān)于存儲類型的更多信息，請參見存儲類型概述。
通過--meta選項修改存儲類型時，默認會覆蓋已有的自定義文件元數(shù)據(jù)。 如果您希望修改存儲類型時保留已有的自定義文件元數(shù)據(jù)，則需要利用x-oss-metadata-directive:COPY選項，先通過該選項保留已有的自定義文件元數(shù)據(jù)，然后再進行文件存儲類型的修改。
覆蓋已有的自定義文件元數(shù)據(jù)
將指定文件的存儲類型修改為歸檔存儲
ossutil cp oss://examplebucket1/srcfolder1/examplefile.txt oss://examplebucket1/srcfolder1/examplefile.txt --meta X-oss-Storage-Class:Archive將指定文件夾下所有文件的存儲類型修改為標準存儲
ossutil cp oss://examplebucket1/srcfolder1/ oss://examplebucket1/srcfolder1/ --meta X-oss-Storage-Class:Standard -r
保留已有的自定義文件元數(shù)據(jù)
保留已有單個文件的文件元數(shù)據(jù)。
ossutil cp oss://examplebucket1/srcfolder1/examplefile.txt oss://examplebucket1/srcfolder1/examplefile.txt --meta x-oss-metadata-directive:COPY保留已有多個文件的元數(shù)據(jù)。
ossutil cp oss://examplebucket1/srcfolder1/ oss://examplebucket1/srcfolder1/ --meta x-oss-metadata-directive:COPY -r -f
通過cp修改文件存儲類型時，按Object源存儲類型收取Put類請求費用，并計量到目標Bucket。
如果將Object轉(zhuǎn)換為低頻訪問、歸檔存儲、冷歸檔存儲或者深度冷歸檔存儲類型，且存儲未滿指定周期，會產(chǎn)生存儲不足規(guī)定時長容量費用。更多信息，請參見存儲費用。
通過cp命令將歸檔存儲、冷歸檔存儲或者深度冷歸檔存儲類型的Object轉(zhuǎn)換為標準、低頻訪問類型時，必須先通過restore（解凍文件）命令解凍該Object，然后再使用cp命令轉(zhuǎn)換Object的存儲類型。如果開啟了歸檔直讀，歸檔存儲類型Object無需解凍，就可以轉(zhuǎn)換存儲類型。
通過cp命令對超過100 MB的文件進行存儲類型轉(zhuǎn)換操作時，ossutil默認會根據(jù)文件大小自行計算合適的分片大小值。如果自動切片無法滿足需求，您可以通過--part-size選項指定分片大小，但需確保分片數(shù)不能超過10000。
修改文件對象標簽
您可以在覆寫文件時，添加--tagging選項修改文件對象標簽，多個標簽以and（&）符號隔開。命令如下：
ossutil cp oss://examplebucket1/examplefile.txt oss://examplebucket1/ --tagging "abc=1&bcd=2&……"關(guān)于對象標簽的更多信息，請參見object-tagging（對象標簽）。
拷貝并加密文件
您可以在拷貝文件時指定文件的服務(wù)器端加密方式，將文件加密后保存在Bucket內(nèi)，關(guān)于服務(wù)器端加密功能介紹的更多信息，請參見服務(wù)器端加密。
拷貝文件并指定加密方式為AES256
ossutil cp oss://examplebucket1/examplefile.txt oss://examplebucket1/srcfolder2/ --meta=x-oss-server-side-encryption:AES256拷貝文件并指定加密方式為KMS
ossutil cp oss://examplebucket1/examplefile.txt oss://examplebucket2/desfolder/ --meta=x-oss-server-side-encryption:KMS重要使用KMS加密時，OSS會在KMS平臺上為這個文件創(chuàng)建一個主密鑰，會產(chǎn)生少量KMS密鑰API調(diào)用費用。更多信息，請參見KMS計費標準。
拷貝文件并指定加密方式為KMS，指定加密算法為SM4，指定CMK ID
ossutil cp oss://examplebucket1/examplefile.txt oss://examplebucket2/desfolder/ --meta=x-oss-server-side-encryption:KMS#x-oss-server-side-data-encryption:SM4#x-oss-server-side-encryption-key-id:7bd6e2fe-cd0e-483e-acb0-f4b9e1******
在已開啟版本控制的Bucket內(nèi)恢復(fù)文件
開啟Bucket的版本控制后，針對數(shù)據(jù)的覆蓋和刪除操作將會以歷史版本的形式保存下來。您可以在cp命令中增加--version-id選項，將歷史版本覆寫為最新版本。示例如下：
ossutil cp oss://examplebucket1/examplefile.txt oss://examplebucket2/ --version-id CAEQARiBgID8rumR2hYiIGUyOTAyZGY2MzU5MjQ5ZjlhYzQzZjNlYTAyZDE3MDRk使用--version-id選項前，需使用ls --all-versions命令獲取文件的versionid。
--version-id選項僅支持在已開啟版本控制的Bucket內(nèi)使用。關(guān)于開啟Bucket版本控制的具體操作，請參見bucket-versioning（版本控制）。
通用選項
當您需要通過命令行工具ossutil切換至另一個地域的Bucket時，可以通過-e選項指定該Bucket所屬的Endpoint。當您需要通過命令行工具ossutil切換至另一個阿里云賬號下的Bucket時，可以通過-i選項指定該賬號的AccessKey ID，并通過-k選項指定該賬號的AccessKey Secret。
例如，您需要將另一個阿里云賬號下，華東2（上海）地域下源存儲空間examplebucket根目錄下的文件srcobject.png拷貝至目標存儲空間destbucket，命令如下：
ossutil cp oss://examplebucket/srcobject.png oss://destbucket -e oss-cn-shanghai.aliyuncs.com -i LTAI4Fw2NbDUCV8zYUzA**** -k 67DLVBkH7EamOjy2W5RVAHUY9H****關(guān)于此命令的其他通用選項的更多信息，請參見通用選項。