當您需要將本地檔案、圖片、視頻等資源上傳到OSS,或者需要上傳大檔案至OSS時,可以使用ossutil的cp命令。您也可以指定--include和--exclude選項,批量上傳符合指定條件的檔案。
注意事項
要上傳檔案,您必須具有
oss:PutObject
許可權。具體操作,請參見為RAM使用者授權自訂的權限原則。從ossutil 1.6.16版本開始,命令列中Binary名稱支援直接使用ossutil,您無需根據系統重新整理Binary名稱。如果您的ossutil版本低於1.6.16,則需要根據系統重新整理Binary名稱。更多資訊,請參見命令列工具ossutil命令參考。
使用cp命令上傳檔案時,ossutil會根據檔案大小自動選擇不同的上傳方式:
命令格式
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系統檔案路徑 |
cloud_url | OSS檔案路徑。格式為 |
-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會自動建立名為 |
--encoding-type | 檔案名稱的編碼方式。取值為url。如果不指定該選項,則表示檔案名稱未經過編碼。 |
--include | 包含符合指定條件的所有檔案。文法規範和使用樣本,請參見批量上傳合格檔案。 |
--exclude | 不包含任何符合指定條件的檔案。文法規範和使用樣本,請參見批量上傳合格檔案。 |
--meta | 檔案的中繼資料。包括部分HTTP標準屬性(HTTP Header)以及以 |
--acl | 檔案的讀寫權限ACL。取值如下:
|
--snapshot-path | 指定儲存上傳檔案時的快照資訊所在的目錄。在下一次上傳檔案時,ossutil會讀取指定目錄下的快照資訊進行增量上傳。 |
--disable-crc64 | 關閉CRC64資料校正。預設情況下,ossutil進行資料轉送時都會開啟CRC64校正。 |
--disable-dir-object | 表示上傳檔案時不為目錄產生Object。 |
--payer | 請求的支付方式。如果希望訪問指定路徑下的資源產生的流量、請求次數等費用由要求者支付,請將此選項的值設定為requester。 |
--tagging | 上傳檔案時設定標籤資訊,格式為 |
-j,--jobs | 多檔案操作時的並發任務數,預設值為3,取值範圍為1~10000。 |
--parallel | 單檔案操作時的並發任務數,取值範圍為1~10000。 如果不設定此選項,預設由ossutil根據操作類型和檔案大小自行決定。 |
--start-time | Unix時間戳記。如果輸入這個選項,最後更新時間早於該時間的Object會被忽略。 說明 僅1.7.18及以上版本支援設定該參數。關於如何升級版本,請參見update(ossutil版本升級)。 |
--end-time | Unix時間戳記。如果使用該選項,則最後更新時間晚於通過此選項指定時間的Object會被忽略。 說明
|
從以上命令格式中的-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且不是JPG和TXT格式的檔案
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****
關於此命令的其他通用選項的更多資訊,請參見通用選項。