全部產品
Search
文件中心

Object Storage Service:cp(上傳檔案)

更新時間:Jul 31, 2024

當您需要將本地檔案、圖片、視頻等資源上傳到OSS,或者需要上傳大檔案至OSS時,可以使用ossutil的cp命令。您也可以指定--include--exclude選項,批量上傳符合指定條件的檔案。

注意事項

  • 要上傳檔案,您必須具有oss:PutObject許可權。具體操作,請參見為RAM使用者授權自訂的權限原則

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

  • 使用cp命令上傳檔案時,ossutil會根據檔案大小自動選擇不同的上傳方式:

    • 如果上傳的檔案大小小於斷點續傳上傳檔案大小的閾值(該閾值通過--bigfile-threshold選項指定,預設值是100 MB),ossutil將採用簡單上傳的方式。

    • 如果上傳的檔案大小大於等於斷點續傳上傳檔案大小的閾值,ossutil將採用斷點續傳上傳的方式。

      如果您因意外中斷了檔案上傳的過程,且未繼續完成該檔案的上傳,則已上傳的部分會以片段(Part)的形式儲存在OSS的儲存空間(Bucket)中。如果您不再需要這些Part,建議您通過以下方式刪除,以免產生額外的儲存費用。

    命令格式

    ossutil cp file_url cloud_url
    [-r, --recursive]
    [-f --force]
    [-u --update]
    [--maxupspeed <value>]
    [--enable-symlink-dir]
    [--disable-all-symlink]
    [--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>]
    [--snapshot-path <value>]
    [--disable-crc64]
    [--disable-dir-object]
    [--payer <value>]
    [--tagging <value>]
    [-j, --job <value>]
    [--parallel <value>]
    [--start-time <value>]
    [--end-time <value>]

    參數及選項說明如下:

    配置項

    說明

    file_url

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

    cloud_url

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

    -r, --recursive

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

    -f --force

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

    -u,--update

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

    --maxupspeed

    最大上傳速度,單位為KB/s。預設值為0,表示不限制上傳速度。

    --enable-symlink-dir

    上傳連結子目錄,預設不上傳。

    --disable-all-symlink

    上傳時忽略所有的軟連結子檔案以及軟連結子目錄。

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

    檔案的中繼資料。包括部分HTTP標準屬性(HTTP Header)以及以x-oss-meta-開頭的使用者自訂中繼資料(User Meta)。檔案中繼資料格式為header:value#header:value,樣本為Cache-Control:no-cache#Content-Encoding:gzip。有關OSS支援中繼資料的更多介紹,請參見管理檔案中繼資料

    --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校正。

    --disable-dir-object

    表示上傳檔案時不為目錄產生Object。

    --payer

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

    --tagging

    上傳檔案時設定標籤資訊,格式為TagkeyA=TagvalueA&TagkeyB=TagvalueB....

    -j,--jobs

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

    --parallel

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

    --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中。您在實際使用中,請根據您的系統和使用環境修改對應參數。本文涉及的通用樣本說明如下:

    • 本地檔案:examplefile.txt(根目錄下的檔案)

    • 本地檔案夾:localfolder(根目錄下的檔案夾)

    • 目標Bucket:examplebucket

    • 目標Bucket指定目錄:desfolder

    簡單上傳

    當您需要將本地檔案、圖片、視頻等資源上傳到OSS,可以使用ossutil,樣本如下:

    • 上傳單個檔案

      上傳檔案時,如果不指定上傳至OSS的檔案名稱,則預設使用原檔案名稱進行儲存;如果指定檔案名稱,則按照指定的檔案名稱儲存在OSS中。

      ossutil cp examplefile.txt oss://examplebucket/desfolder/
    • 僅上傳檔案夾內的檔案

      使用cp命令時增加-r選項,可以只將本地檔案夾內的檔案上傳到OSS指定路徑。

      ossutil cp -r localfolder/ oss://examplebucket/desfolder/
    • 上傳檔案夾內的檔案並指定時間戳記

      將本地檔案夾內的檔案上傳到OSS指定路徑,檔案修改時間限定在北京時間2023年10月31日10:09:18至2023年10月31日12:55:58內。

      ossutil cp -r localfolder/ oss://examplebucket/desfolder/ --start-time 1698718158 --end-time 1698728158
    • 上傳檔案夾及檔案夾內的檔案

      使用cp命令時增加-r選項,並在OSS指定路徑下添加本地檔案夾名稱,可以將本地檔案夾以及檔案夾內的檔案上傳到OSS指定路徑。 對於檔案夾內的檔案夾,OSS會對應建立0 KB大小、以正斜線(/)結尾的Object;對於指定的檔案夾,OSS不會建立對應的Object。如果您需要建立對應的Object,您可以使用mkdir(建立目錄)

      ossutil cp -r localfolder/ oss://examplebucket/desfolder/localfolder/
    • 上傳單個檔案並指定--meta選項

      上傳檔案的同時可以使用--meta選項設定檔案的meta資訊,其內容格式為header:value#header:value...

      ossutil cp examplefile.txt oss://examplebucket/desfolder/examplefile.txt --meta=Cache-Control:no-cache#Content-Encoding:gzip
    • 上傳檔案夾並跳過已有檔案

      批量上傳失敗重傳時,可以指定--update(可縮寫為-u)選項跳過已經上傳成功的檔案,實現增量上傳。樣本如下:

      ossutil cp -r localfolder/ oss://examplebucket/desfolder/ -u
    • 上傳檔案到開通了要求者付費模式的Bucket

      ossutil cp localfolder/examplefile.txt oss://examplebucket/ --payer=requester
    • 僅上傳目前的目錄下的檔案,忽略子目錄

      ossutil cp localfolder/ oss://examplebucket/desfolder/ --only-current-dir -r
    • 上傳時不為目錄產生Object

      OSS的目錄是用一個0 KB大小,名稱以正斜線(/)結尾的Object類比的。上傳時增加--disable-dir-object參數,ossutil不會為該目錄產生Object,但您仍可以在OSS控制台看到對應的目錄結構。當您刪除目錄內的檔案時,該目錄也會消失。

      ossutil cp localfolder/ oss://examplebucket/desfolder/ --disable-dir-object -r
    • 上傳軟連結子目錄下的檔案

      ossutil cp localfolder/ oss://examplebucket/desfolder/ --enable-symlink-dir -r
    • 上傳時忽略所有的軟連結子檔案以及軟連結子目錄

      ossutil cp localfolder/ oss://examplebucket/desfolder/ -r --disable-all-symlink

    上傳時限速

    您可以在上傳檔案時,結合--maxupspeed選項來限制上傳的最大速度,單位為KB/s。樣本如下:

    • 上傳檔案並設定限速為1 MB/s

      ossutil cp examplefile.txt oss://examplebucket/desfolder/ --maxupspeed 1024
    • 上傳檔案夾並設定限速為1 MB/s

      ossutil cp -r localfolder/ oss://examplebucket/desfolder/ --maxupspeed 1024

    上傳並設定對象標籤

    您可以在上傳檔案時,通過--tagging選項設定檔案對象標籤,多個標籤以and(&)符號隔開。樣本如下:

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

    關於對象標籤的更多說明請參見object-tagging(對象標籤)

    上傳並指定儲存類型

    您可以在上傳檔案時,通過--meta選項設定檔案儲存體類型。儲存類型可選值為:

    • Standard:標準儲存

    • IA:低頻訪問

    • Archive:Archive Storage

    • ColdArchive:冷Archive Storage

    • DeepColdArchive:深度冷Archive Storage

    如果上傳時未指定儲存類型,則以儲存空間的儲存類型為準。更多資訊,請參見儲存類型概述

    上傳並指定儲存類型的樣本如下:

    • 上傳單個檔案並指定儲存類型為低頻訪問類型

      ossutil cp examplefile.txt oss://examplebucket/desfolder/ --meta X-oss-Storage-Class:IA
    • 上傳檔案夾並指定儲存類型為標準儲存類型

      ossutil cp localfolder/ oss://examplebucket/desfolder/ --meta X-oss-Storage-Class:Standard -r

    上傳並指定讀寫權限ACL

    您可以在上傳檔案時,通過--acl選項設定檔案的ACL。檔案ACL可選值為:

    • default:繼承Bucket(預設)

    • private:私人

    • public-read:公用讀取

    • public-read-write:公用讀寫

    樣本如下:

    • 上傳單個檔案並指定ACL為私人

      ossutil cp examplefile.txt oss://examplebucket/desfolder/ --acl private
    • 上傳檔案夾並指定ACL為公用讀取

      ossutil cp localfolder/ oss://examplebucket/desfolder/ --acl public-read  -r

    上傳並指定加密方式

    您可以在上傳檔案時指定檔案的伺服器端加密方式,將檔案加密後儲存在Bucket內。 樣本如下:

    • 上傳檔案並指定加密方式為OSS完全託管,密碼編譯演算法為AES256

      ossutil cp examplefile.txt oss://examplebucket/desfolder/ --meta=x-oss-server-side-encryption:AES256
    • 上傳檔案並指定加密方式為KMS,不指定CMK ID

      ossutil cp examplefile.txt oss://examplebucket/desfolder/ --meta=x-oss-server-side-encryption:KMS

      使用KMS加密時,會產生少量KMS密鑰使用費用,詳情請參見KMS計費標準

    • 上傳檔案並指定加密方式為KMS,指定CMK ID

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

    有關伺服器端加密功能介紹,請參見伺服器端加密

    上傳並產生快照

    批量上傳時,如果指定--snapshot-path選項,ossutil在指定的目錄下組建檔案上傳的快照,記錄成功上傳的檔案的本地lastModifiedTime,在下次上傳時通過比較lastModifiedTime來決定是否跳過相同檔案,所以在使用該選項時,請確保兩次上傳期間沒有其他使用者更改了OSS上對應的Object。--snapshot-path選項適用於加速增量上傳的情境。樣本如下:

    ossutil cp -r localfolder/ oss://examplebucket/desfolder/ --snapshot-path=path                                
    重要
    • ossutil不會主動刪除snapshot-path檔案夾中的快照資訊。為避免快照資訊過多,請定期刪除snapshot-path檔案夾內無用的快照。

    • 由於讀寫snapshot資訊需要額外開銷,當待批量上傳的檔案數量較少、網路狀況較好、或有其他使用者操作相同Object時,不建議使用該選項。針對以上情況,您可以使用--update選項來增量上傳。

    • --update選項和--snapshot-path選項可以同時使用,ossutil會優先根據snapshot-path資訊判斷是否跳過此檔案,如果不滿足跳過條件,再根據--update判斷是否跳過此檔案。

    批量上傳合格檔案

    批量上傳時,如果指定--include--exclude選項,ossutil會批量上傳符合指定條件的檔案。

    --include--exclude選項支援格式:

    • 萬用字元星號(*):匹配所有字元。例如:*.txt表示匹配所有TXT格式的檔案。

    • 萬用字元問號(?):匹配單個字元。例如:abc?.jpg表示匹配所有檔案名稱為abc+任意單個字元的JPG格式的檔案,如abc1.jpg

    • [sequence]:匹配序列的任一字元,例如:abc[1-5].jpg表示匹配檔案名稱為abc1.jpg~abc5.jpg的檔案。

    • [!sequence]:匹配序列外的任一字元,例如:abc[!0-7].jpg表示匹配檔案名稱不為abc0.jpg~abc7.jpg的檔案。

    一條規則中可以包含多個include(包含)和exclude(排除)條件,且每個檔案從左至右逐一運用每個規則,直至最後才能最終確定匹配的結果。例如指定生效的檔案夾中包含名為test.txt的檔案,匹配不同的規則產生的結果如下。

    • 規則一:--include "*test*" --exclude "*.txt" ,當規則匹配到--include "*test*",匹配的結果為test.txt符合條件;當規則繼續匹配到--exclude "*.txt"時,因test.txt檔案名稱包含.txt,所以被排除。則匹配的最終結果為test.txt不符合條件。

    • 規則二:--exclude "*.txt" --include "*test*",當規則匹配到--exclude "*.txt",匹配的結果為test.txt不符合條件;當規則繼續匹配到--include "*test*",因test.txt檔案名稱包含test,所以符合條件。則匹配的最終結果為test.txt符合條件。

    • 規則三:--include "*test*" --exclude "*.txt" --include "te?t.txt" ,當規則匹配到--include "*test*",匹配的結果為test.txt符合條件;當規則繼續匹配到--exclude "*.txt"時,因test.txt檔案名稱包含.txt,所以被排除;當規則最後匹配到--include "te?t.txt"時,因test.txt符合條件,所以被包含。則匹配的最終結果為test.txt符合條件。

    重要

    設定條件時不支援目錄格式,例如--include "/usr/test/.jpg"

    樣本如下:

    • 上傳所有檔案格式為TXT的檔案

      ossutil cp localfolder/ oss://examplebucket/desfolder/ --include "*.txt" -r
    • 上傳所有檔案名稱包含abc且不是JPGTXT格式的檔案

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

    通用選項

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

    例如,您需要將本地檔案exampleobject.txt上傳至另一個阿里雲帳號下,華東2(上海)地區的儲存空間examplebucket的destfolder目錄下,命令如下:

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

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