全部產品
Search

搜尋本產品

    Object Storage Service：cp（拷貝檔案）

    文件中心

    Object Storage Service：cp（拷貝檔案）

    更新時間：Oct 22, 2024

    拷貝檔案（Object）是指在不改變檔案內容的情況下，將同一地區下的源儲存空間（Bucket）內的檔案複製到目標Bucket，或者將檔案複製到相同儲存空間（Bucket）的其他目錄。您可以通過ossutil的cp完成拷貝。

    注意事項

    • 要拷貝檔案，您必須具有oss:GetObject、oss:ListObjects和oss:PutObject許可權。具體操作，請參見為RAM使用者授權自訂的權限原則。

    • 從ossutil 1.6.16版本開始，命令列中Binary名稱支援直接使用ossutil，您無需根據系統重新整理Binary名稱。如果您的ossutil版本低於1.6.16，則需要根據系統重新整理Binary名稱。更多資訊，請參見命令列工具ossutil命令參考。

    • 不支援通過cp命令跨帳號或者跨地區拷貝檔案。如果您需要跨帳號或者跨地區拷貝（遷移）檔案，請使用ossimport或者線上遷移服務。

    • 目前只支援拷貝檔案，不支援拷貝未完成的分區（Part）。

    • 不支援對通過追加上傳方式產生的Object進行拷貝。

    • 您需要有源Object的讀許可權及目標Bucket的讀寫權限，否則無法完成拷貝操作。關於拷貝檔案的更多資訊，請參見拷貝檔案。

    命令格式

    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>]

    參數及選項說明如下：

    配置項

    說明

    cloud_url

    分別填寫OSS源檔案和目標檔案路徑。格式為oss://bucketname/objectname。例如，將目標儲存空間examplebucket下的源檔案srcobject.jpg拷貝到相同儲存空間下的目標檔案destobject.jpg，則源檔案路徑填寫為oss://examplebucket/srcobject.jpg，目標檔案路徑填寫為oss://examplebucket/destobject.jpg。

    -r, --recursive

    遞迴操作。當指定該選項時，ossutil會對Bucket下所有合格Object進行操作，否則只對指定的單個Object進行操作。

    -f --force

    強制操作，不進行詢問提示。

    -u，--update

    只有當目標檔案不存在，或源檔案的最後修改時間晚於目標檔案時，ossutil才會執行拷貝操作。

    --disable-ignore-error

    大量操作時不忽略錯誤。

    --only-current-dir

    僅拷貝目前的目錄下的檔案，忽略子目錄及子目錄下的檔案。

    -bigfile-threshold

    設定斷點續傳檔案的大小閾值，單位為位元組。

    預設值：100 MB

    取值範圍：0~9223372036854775807

    --part-size

    設定分區大小，單位為位元組。預設情況下ossutil會根據檔案大小自行計算合適的分區大小值。

    取值範圍：1~9223372036854775807

    --checkpoint-dir

    指定斷點續傳記錄資訊所在的目錄。斷點續傳操作失敗時，ossutil會自動建立名為.ossutil_checkpoint的目錄，並在該目錄下記錄checkpoint資訊，斷點續傳成功後會刪除該目錄。如果指定了該選項，請確保指定的目錄可以被刪除。

    --encoding-type

    檔案名稱的編碼方式。取值為url。如果不指定該選項，則表示檔案名稱未經過編碼。

    --include

    包含符合指定條件的所有檔案。

    --exclude

    不包含任何符合指定條件的檔案。

    --meta

    設定檔案的中繼資料，格式為header:value#header:value，樣本為Cache-Control:no-cache#Content-Encoding:gzip。關於中繼資料的介紹，請參見set-meta（管理檔案中繼資料）。

    --acl

    檔案的讀寫權限ACL。取值如下：

    • default（預設值）：繼承Bucket的讀寫權限。

    • private：只有該Bucket的擁有者可以對該Bucket內的檔案進行讀寫操作，其他人無法訪問該Bucket內的檔案。

    • public-read：只有Bucket擁有者可以對該Bucket內的檔案進行寫操作，其他使用者（包括匿名訪問者）都可以對該Bucket中的檔案進行讀操作。這有可能造成您資料的外泄以及費用激增，如果被人惡意寫入違法資訊還可能會侵害您的合法權益。除特殊情境外，不建議您配置此許可權。

    • public-read-write：任何人（包括匿名訪問者）都可以對該Bucket內檔案進行讀寫操作。這有可能造成您資料的外泄以及費用激增，請謹慎操作。

    --disable-crc64

    關閉CRC64資料校正。預設情況下，ossutil進行資料轉送時都會開啟CRC64校正。

    --payer

    請求的支付方式。如果希望訪問指定路徑下的資源產生的流量、請求次數等費用由要求者支付，請將此選項的值設定為requester。

    -j，--jobs

    多檔案操作時的並發任務數，預設值為3，取值範圍為1~10000。

    --parallel

    單檔案操作時的並發任務數，取值範圍為1~10000。 如果不設定此選項，預設由ossutil根據操作類型和檔案大小自行決定。

    --version-id

    拷貝指定版本的檔案，僅支援在已開啟版本控制的Bucket內使用。

    --start-time

    Unix時間戳記。如果輸入這個選項，最後更新時間早於該時間的Object會被忽略。

    說明

    僅1.7.18及以上版本支援設定該參數。關於如何升級版本，請參見update（ossutil版本升級）。

    --end-time

    Unix時間戳記。如果使用該選項，則最後更新時間晚於通過此選項指定時間的Object會被忽略。

    說明

    • 如果同時指定了start-time和end-time，檔案的修改時間在start-time和end-time之間才會執行拷貝命令。

    • 僅1.7.18及以上版本支援設定該參數。關於如何升級版本，請參見update（ossutil版本升級）。

    從以上命令格式中的-j，--jobs和--parallel選項得知，當ossutil自行設定的預設並發數達不到使用者的效能要求時，您可以自行調整這兩個選項來升降效能。預設情況下，ossutil會根據檔案大小來計算parallel個數。當批量拷貝大檔案時，實際的並發數為jobs個數乘以parallel個數。

    • 當ECS虛擬機器或者伺服器在網路、記憶體、CPU等資源不是特別充足的情況下，建議將並發數調整到100以下。如果網路、記憶體、CPU等資源沒有佔滿，可以適當增加並發數。

    • 由於線程間資源切換及搶奪等原因，如果並發數過大，ossutil拷貝效能可能會下降。此外，並發數過大還可能產生EOF錯誤。所以請根據實際的機器情況調整-j，--jobs和--parallel選項的數值。如果要進行壓測，可在一開始時調低這兩項數值，然後逐漸調大直至找到最優值。

    樣本環境

    本文以Linux系統為例，示範如何在不同目錄或不同Bucket之間拷貝檔案。您在實際使用中，請根據您的系統和使用環境修改對應參數。樣本環境如下：

    • 作業系統：Linux

    • 源Bucket：examplebucket1

    • 源Bucket指定目錄1：srcfolder1

    • 源Bucket指定目錄2：srcfolder2

    • 目標Bucket：examplebucket2

    • 目標Bucket指定目錄：desfolder

    是否拷貝來源目錄

    拷貝檔案時，如果源路徑末尾沒有攜帶正斜線（/），則拷貝與指定首碼匹配的所有檔案到目標Bucket。如果源路徑末尾攜帶了正斜線（/），則僅拷貝指定目錄下的檔案拷到目標Bucket。

    假設源儲存空間examplebucket1指定目錄srcfolder1下包含以下檔案：

    srcfolder1/exampleobject1.txt
srcfolder1/exampleobject2.png
srcfolder1/dir1/
srcfolder1/dir1/exampleobject3.jpg
srcfolder1/dir2/
srcfolder1/dir2/exampleobject4.jpg

    • 拷貝時指定的源路徑不以正斜線（/）結尾

      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

    • 拷貝時指定的源路徑以正斜線（/）結尾

      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才會執行拷貝操作。命令如下： 

      ossutil cp oss://examplebucket1/srcfolder1/ oss://examplebucket2/path2/ -r --update

      該選項可用於當批量拷貝失敗重傳時，跳過已經拷貝成功的檔案，實現增量拷貝。

    • 批量拷貝檔案

      限定srcfolder1中檔案的修改時間，在北京時間2023年10月31日10:09:18至2023年10月31日12:55:58內時，檔案才會被拷貝。

      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資訊，其內容格式為 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參數，在拷貝時選定合格檔案。

    • 拷貝所有檔案格式不為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：標準儲存

    • IA：低頻訪問

    • Archive：Archive Storage

    • ColdArchive：冷Archive Storage

    • DeepColdArchive：深度冷Archive Storage

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

    重要

    通過--meta選項修改儲存類型時，預設會覆蓋已有的自訂檔案中繼資料。 如果您希望修改儲存類型時保留已有的自訂檔案中繼資料，則需要利用x-oss-metadata-directive:COPY選項，先通過該選項保留已有的自訂檔案中繼資料，然後再進行檔案儲存體類型的修改。

    覆蓋已有的自訂檔案中繼資料

    • 將指定檔案的儲存類型修改為Archive Storage

      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

    保留已有的自訂檔案中繼資料

    • 保留已有單個檔案的檔案中繼資料。

      ossutil cp oss://examplebucket1/srcfolder1/examplefile.txt oss://examplebucket1/srcfolder1/examplefile.txt --meta x-oss-metadata-directive:COPY

    • 保留已有多個檔案的中繼資料。

      ossutil cp oss://examplebucket1/srcfolder1/ oss://examplebucket1/srcfolder1/ --meta x-oss-metadata-directive:COPY -r -f
    重要

    • 通過cp修改檔案儲存體類型時，按Object源儲存類型收取Put類請求費用，並計量到目標Bucket。

    • 如果將Object轉換為低頻訪問、Archive Storage、冷Archive Storage或者深度冷Archive Storage類型，且儲存未滿指定周期，會產生儲存不足規定時間長度容量費用。更多資訊，請參見儲存費用。

    • 通過cp命令將Archive Storage、冷Archive Storage或者深度冷Archive Storage類型的Object轉換為標準、低頻訪問類型時，必須先通過restore（解凍檔案）命令解凍該Object，然後再使用cp命令轉換Object的儲存類型。如果開啟了歸檔直讀，Archive Storage類型Object無需解凍，就可以轉換儲存類型。

    • 通過cp命令對超過100 MB的檔案進行儲存類型轉換操作時，ossutil預設會根據檔案大小自行計算合適的分區大小值。如果自動切片無法滿足需求，您可以通過--part-size選項指定分區大小，但需確保分區數不能超過10000。

    修改檔案對象標籤

    您可以在覆寫檔案時，添加--tagging選項修改檔案對象標籤，多個標籤以and（&）符號隔開。命令如下：

    ossutil cp oss://examplebucket1/examplefile.txt oss://examplebucket1/ --tagging "abc=1&bcd=2&……"

    關於對象標籤的更多資訊，請參見object-tagging（對象標籤）。

    拷貝並加密檔案

    您可以在拷貝檔案時指定檔案的伺服器端加密方式，將檔案加密後儲存在Bucket內，關於伺服器端加密功能介紹的更多資訊，請參見伺服器端加密。

    • 拷貝檔案並指定加密方式為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平台上為這個檔案建立一個主要金鑰，會產生少量KMS密鑰API調用費用。更多資訊，請參見KMS計費標準。

    • 拷貝檔案並指定加密方式為KMS，指定CMK ID

      ossutil cp oss://examplebucket1/examplefile.txt oss://examplebucket2/desfolder/ --meta=x-oss-server-side-encryption:KMS#x-oss-server-side-encryption-key-id:7bd6e2fe-cd0e-483e-acb0-f4b9e1******

    在已開啟版本控制的Bucket內恢複檔案

    開啟Bucket的版本控制後，針對資料的覆蓋和刪除操作將會以歷史版本的形式儲存下來。您可以在cp命令中增加--version-id選項，將歷史版本覆寫為最新版本。樣本如下：

    ossutil cp oss://examplebucket1/examplefile.txt oss://examplebucket2/ --version-id  CAEQARiBgID8rumR2hYiIGUyOTAyZGY2MzU5MjQ5ZjlhYzQzZjNlYTAyZDE3MDRk
    重要

    通用選項

    當您需要通過命令列工具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****

    關於此命令的其他通用選項的更多資訊，請參見通用選項。