全部產品
Search

搜尋本產品

    Object Storage Service：cp（下載檔案）

    文件中心

    Object Storage Service：cp（下載檔案）

    更新時間：Jul 31, 2024

    當您需要將已上傳至OSS的檔案、圖片、視頻等資源下載到本地時，可以使用ossutil的cp命令。您也可以按照本文樣本，下載多個檔案、下載時限速，或者在已開啟版本控制的Bucket內下載指定版本檔案。

    注意事項

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

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

      命令格式

      ossutil cp cloud_url file_url
[-r, --recursive]
[-f --force]
[-u --update]
[--maxdownspeed <value>]
[--disable-ignore-error]
[--only-current-dir]
[--bigfile-threshold <value>]
[--part-size <value>]
[--checkpoint-dir <value>]
[--range <value>]
[--encoding-type <value>]
[--include <value>]
[--exclude <value>]
[--meta <value>]
[--acl <value>]
[--snapshot-path <value>]
[--disable-crc64]
[--payer <value>]
[--partition-download <value>]
[-j, --job <value>]
[--parallel <value>]
[--version-id <value>]
[--start-time <value>]
[--end-time <value>]

      參數及選項說明如下：

      配置項

      說明

      cloud_url

      OSS檔案路徑。格式為oss://bucketname/objectname。例如oss://examplebucket/examplefile.txt。

      file_url

      本地檔案路徑。例如Linux系統檔案路徑/localfolder/examplefile.txt，Windows系統檔案路徑D:\localfolder\examplefile.txt。

      -r, --recursive

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

      -f --force

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

      -u，--update

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

      --maxdownspeed

      最大下載速度，單位為KB/s。預設值為0，表示不限制下載速度。

      --disable-ignore-error

      大量操作時不忽略錯誤。

      --only-current-dir

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

      --bigfile-threshold

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

      預設值：100 MB

      取值範圍：0~9223372036854775807

      --part-size

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

      取值範圍：1~9223372036854775807

      --checkpoint-dir

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

      --range

      下載目標檔案的指定欄位，並儲存為一個新的檔案，欄位從0開始編號。

      • 指定區間

        例如指定為3-9，表示下載檔案的第3個位元組到第9個位元組（包含第3和第9位元組）。

      • 指定開始位置

        例如指定為3-，表示從第3個位元組開始到檔案結尾（包含第3個位元組）。

      • 指定結束位置

        例如指定為-9，表示從0位元組到第9個位元組（包含第9個位元組）。

      --encoding-type

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

      --include

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

      更多資訊，請參見include和exclude選項。

      --exclude

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

      更多資訊，請參見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內檔案進行讀寫操作。這有可能造成您資料的外泄以及費用激增，如果被人惡意寫入違法資訊還可能會侵害您的合法權益。除特殊情境外，不建議您配置公用讀寫許可權。

      --snapshot-path

      指定儲存下載檔案時的快照資訊所在的目錄。在下一次下載檔案時，ossutil會讀取指定目錄下的快照資訊進行增量下載。

      --disable-crc64

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

      --payer

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

      --partition-download

      用於分區下載。該選項取值格式為分區編號：總分區數。例如1：5，表示當前ossutil下載分區1，總共有5個分區。分區號從1開始編號，Object的分區規則由工具內部演算法決定。通過該選項將待下載的Object分成多個分區，並由多個ossutil命令並行下載，各個ossutil命令下載各自的分區。

      -j，--job

      多檔案操作時的並發任務數，預設值為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系統為例，將OSS內的檔案下載到本地。您在實際使用中，請根據您的系統和使用環境修改對應參數。樣本環境如下：

      • 作業系統：Linux

      • 目標Bucket：examplebucket

      • 目標Bucket指定目錄：destfolder

      • 本地檔案：examplefile.txt（根目錄下的檔案）

      • 本地檔案夾：localfolder（根目錄下的檔案夾）

      下載單個檔案

      下載檔案時如果未指定檔案名稱，則預設使用原檔案名稱儲存在本地。如果指定檔案名稱，則按照指定檔案名稱儲存在本地。

      • 沿用原檔案名稱儲存檔案

        ossutil cp oss://examplebucket/destfolder/examplefile.txt localfolder/

      • 按指定檔案名稱儲存檔案

        ossutil cp oss://examplebucket/destfolder/examplefile.txt localfolder/example.txt

      下載多個檔案

      ossutil不支援通過直接指定多個檔案名稱的方式下載多個檔案。您可以通過以下方式下載多個檔案：

      • 下載某一類檔案

        如果您希望同時下載多個檔案名稱規律的檔案，例如這些檔案均包含相同首碼或者尾碼，此時您可以結合--include和--exclude選項在下載時選擇合格檔案。

        • 下載所有檔案格式不為JPG的檔案 

          ossutil cp oss://examplebucket/destfolder/ localfolder/ --exclude "*.jpg" -r

        • 下載所有檔案名稱包含abc且不是JPG和TXT格式的檔案 

          ossutil cp oss://examplebucket/destfolder/ localfolder/ --include "*abc*" --exclude "*.jpg" --exclude "*.txt" -r

      • 下載檔案夾（包含子目錄）

        下載某一個檔案夾（包含子目錄）下所有檔案的樣本如下：

        ossutil cp -r oss://examplebucket/destfolder/ localfolder/

        當批量下載失敗或者需要增量下載檔案時，可以通過指定--update（可縮寫為-u）選項選擇跳過已經成功下載的檔案。如果本地與OSS沒有同名檔案，或本地同名檔案的最後修改時間早於OSS檔案，ossutil會下載該檔案。如果本地已有同名檔案，且檔案的最後修改時間晚於OSS內檔案時，ossutil會跳過該檔案。樣本如下： 

        ossutil cp -r oss://examplebucket/destfolder/  localfolder/  --update

      • 下載檔案夾（不包含子目錄）

        如果您僅希望下載目前的目錄而忽略子目錄下的檔案時，可以通過指定--only-current-dir選項。樣本如下：

        ossutil cp oss://examplebucket/destfolder/ localfolder/ --only-current-dir -r

      • 下載檔案夾（指定時間戳記）

        當某一個檔案夾（包含子目錄）下的檔案修改時間在北京時間2023年10月31日10:09:18至2023年10月31日12:55:58內時，才會被下載。樣本如下：

        ossutil cp -r oss://examplebucket/destfolder/ localfolder/ --start-time 1698718158 --end-time 1698728158

      • 下載Bucket根目錄下的所有檔案

        將examplebucket根目錄下的所有檔案下載到本地localfolder/目錄，樣本如下：

        ossutil cp -r oss://examplebucket  localfolder/

      下載時限速

      您可以在下載檔案時，結合--maxdownspeed選項來限制下載的最大速度，單位為KB/s。樣本如下：

      • 下載檔案並設定限速為1 MB/s

        ossutil cp oss://examplebucket/destfolder/examplefile.txt  localfolder/ --maxdownspeed 1024

      • 下載檔案夾並設定限速為1 MB/s 

        ossutil cp -r  oss://examplebucket/destfolder/  localfolder/ --maxdownspeed 1024

      範圍下載

      下載檔案時，可以通過--range選項指定下載範圍。例如將examplefile.txt的第10到第20個字元作為一個檔案下載到本地，命令如下：

      ossutil cp oss://examplebucket/destfolder/examplefile.txt localfolder/  --range=10-20
Succeed: Total num: 1, size: 11. OK num: 1(download 1 objects).

      下載並產生快照資訊

      批量下載時，如果指定--snapshot-path選項，ossutil在指定的目錄下組建檔案下載的快照資訊，在下一次指定該選項下載時，ossutil會讀取指定路徑下的快照資訊進行增量下載。詳情請參見上傳並產生快照。

      ossutil cp -r oss://examplebucket/destfolder/ localfolder/ --snapshot-path=path

      在已開啟版本控制的Bucket內下載指定版本檔案

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

      ossutil cp oss://my-bucket/test.jpg localfolder/ --version-id  CAEQARiBgID8rumR2hYiIGUyOTAyZGY2MzU5MjQ5ZjlhYzQzZjNlYTAyZDE3MDRk
      重要

      通用選項

      當您需要通過命令列工具ossutil切換至另一個地區的Bucket時，可以通過-e選項指定該Bucket所屬的Endpoint。當您需要通過命令列工具ossutil切換至另一個阿里雲帳號下的Bucket時，可以通過-i選項指定該帳號的AccessKey ID，並通過-k選項指定該帳號的AccessKey Secret。

      說明

      您需要根據Bucket所在地區填寫對應的Endpoint。更多資訊，請參見訪問網域名稱和資料中心。

      例如，您需要將另一個阿里雲帳號下，華東2（上海）地區下儲存空間examplebucket根目錄下的檔案exampleobject.txt下載至本地目錄localfolder下，命令如下：

      ossutil cp oss://examplebucket/exampleobject.txt  localfolder/  -e oss-cn-shanghai.aliyuncs.com -i LTAI4Fw2NbDUCV8zYUzA****  -k 67DLVBkH7EamOjy2W5RVAHUY9H****

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