本文介紹ossutil的一些配置操作,您可以通過本文瞭解如何更好地使用ossutil。
版本升級
推薦您使用全新升級的ossutil2.0,快速安裝並使用,請參見安裝ossutil。
ossutil2.0重點功能如下:
全新的命令組織圖:引入了多級命令支援,包括API級命令(例如
ossutil api put-bucket-acl
)和進階命令(如ossutil config
)。改進的組態管理機制:簡化了初始配置流程,使用者僅需提供AccessKey ID、AccessKey Secret及地區ID即可完成安裝後的基礎配置,並且支援通過
--profile
參數指定多個設定檔,增強了靈活性。豐富的過濾參數:對於批量處理命令(如
ls
、cp
、rm
等),新增了基於路徑、檔案大小、修改時間以及對象中繼資料等多種過濾條件的支援,極大地提升了操作的精確性和效率。靈活的輸出格式調整:新增
--output-format
參數,允許使用者將輸出格式設定為JSON、YAML或XML,以便更好地適配不同的資料處理需求;同時引入了--output-query
選項,讓使用者能夠對輸出內容進行篩選,擷取所需資訊。安全性增強:為了提高安全性,ossutil 2.0支援通過環境變數設定敏感參數,避免在命令列中直接暴露密鑰,減少了泄露風險;此外,新增的
--dry-run
選項使使用者能夠在實際執行命令前驗證其行為,確保操作無誤。
通過config命令進行快速配置
對於大多數情況,通過該命令可以快速設定您的ossutil工具。該命令提供了互動式方式組建組態檔案。
以Linux環境為例進行說明。
輸入配置命令。
ossutil config
根據提示設定設定檔路徑。
您可以根據實際需要設定設定檔的路徑。預設情況下,設定檔儲存到~/.ossutilconfig檔案裡, 直接按斷行符號則使用預設配置。
請輸入設定檔名,檔案名稱可以帶路徑(預設為:/home/user/.ossutilconfig,斷行符號將使用預設路徑。 如果使用者佈建為其他路徑,在使用命令時需要將--config-file選項設定為該路徑):
根據提示設定工具的語言。
請輸入語言CH或EN。工具使用的語言預設與作業系統保持一致。該配置項將在此次config命令設定成功後生效。
根據提示分別設定Endpoint、AccessKey ID、AccessKey Secret和STSToken參數。
參數說明如下:
參數
說明
endpoint
填寫Bucket所在地區的Endpoint。關於各地區Endpoint的更多資訊,請參見OSS地區和訪問網域名稱。
您也可以增加
http://
或https://
指定ossutil訪問OSS使用的協議,預設使用HTTP協議。例如,使用HTTPS協議訪問華東1(杭州)的Bucket,設定為https://oss-cn-hangzhou.aliyuncs.com
。accessKeyID
填寫帳號的AccessKey。
使用阿里雲帳號或RAM使用者訪問時,AccessKey的擷取方式,請參見建立AccessKey。
使用STS臨時授權帳號訪問時,AccessKey的擷取方式,請參見AssumeRole - 擷取扮演角色的臨時身份憑證。
accessKeySecret
stsToken
使用STS臨時授權帳號訪問OSS時需要配置該項,否則置空即可。關於stsToken的產生方式,請參見AssumeRole - 擷取扮演角色的臨時身份憑證。
說明關於設定檔的更多資訊,請參見config。
如果在步驟2設定了設定檔的路徑,則每次使用命令時需增加-c選項指定設定檔。
例如,設定檔儲存為/home/config,使用ls時,命令格式如下:
ossutil -c /home/config ls oss://examplebucket
命令設定檔
您可以將常用的憑證資訊和配置資訊儲存到設定檔裡,以方便使用。設定檔採用了INI格式結構,以節(section)和鍵(key)構成, 配置參數儲存在指定的節裡。常用的配置參數如下:
配置參數 | 說明 | 範例程式碼 |
language | 設定ossutil工具的語言。取值:
|
|
endpoint | 設定Bucket所在地區的網域名稱資訊。 |
|
accessKeyID | 存取金鑰的一部分,用於標識使用者身份,以對命令請求進行身分識別驗證。 |
|
accessKeySecret | 存取金鑰的一部分,用於驗證使用者的密鑰,以對命令請求進行身分識別驗證。 |
|
stsToken | 臨時密鑰的Token,以對命令請求進行身分識別驗證。 |
|
mode | 採用的鑒權模式,取值可以為AK、StsToken、RamRoleArn或者EcsRamRole。 |
|
ramRoleArn | 鑒權模式下的RAM角色ARN。 |
|
roleSessionName | 鑒權模式下的會話名稱,用於RamRoleArn模式。不設定時,會產生隨機值。 |
|
tokenTimeout | 表示Token的有效時間,單位為秒,預設值為3600,用於RamRoleArn模式。 |
|
ecsRoleName | EcsRamRole鑒權模式下的角色名稱。 |
|
更多命令配置參數,請參見編輯設定檔。
命令列選項
除了通過命令設定檔外,您還可以使用命令列參數設定相關的配置。命令列選項的優先順序要高於命令設定檔。常用命令列選項如下:
選項 | 說明 | 範例程式碼 |
--loglevel | 記錄層級,預設為空白,表示不輸出記錄檔。取值:
|
|
--connect-timeout | 表示用戶端連線逾時的時間,單位為秒,預設值為120。 |
|
--read-timeout | 表示用戶端讀逾時的時間,單位為秒,預設值為1200。 |
|
--retry-times | 當錯誤發生時的重試次數,預設值為10。 |
|
-e, --endpoint | 請求的網域名稱。 |
|
-i, --access-key-id | 訪問OSS使用的訪問憑證。 |
|
-k, --access-key-secret | 訪問OSS使用的訪問憑證。 |
|
-t, --sts-token | 訪問OSS使用的STSToken。 |
|
--mode | 表示鑒權模式,取值可以為AK、StsToken、RamRoleArn、EcsRamRole,預設值為空白。 | 使用AK模式訪問的範例程式碼如下:
|
--ram-role-arn | 鑒權模式下的RAM角色ARN。 |
|
--role-session-name | 鑒權模式下的會話名字。 |
|
--token-timeout | 表示Token的有效時間,單位為秒,預設值為3600。 |
|
--ecs-role-name | EcsRamRole鑒權模式下的角色名稱。 |
|
更多選項配置,請參見通用選項。
配置訪問憑證
您可以使用多種方式,通過設定檔或者命令列選項配置訪問憑證。
使用存取金鑰訪問
以杭州地區名稱為example-bucket的Bucket為例進行說明。
通過設定檔
產生如下的設定檔,並儲存在~/.myossutilconfig。
[Credentials] endpoint = oss-cn-hangzhou.aliyuncs.com accessKeyID = LTAI4Fw2NbDUCV8zYUzA**** accessKeySecret = 67DLVBkH7EamOjy2W5RVAHUY9H****
通過如下命令查詢Bucket中的對象。
ossutil64 -c ~/.myossutilconfig ls oss://example-bucket
通過命令列選項
您也可以直接將存取金鑰通過命令列參數傳入,範例程式碼如下:
ossutil64 -e oss-cn-hangzhou.aliyuncs.com -i LTAI4Fw2NbDUCV8zYUzA**** -k 67DLVBkH7EamOjy2W5RVAHUY9H**** ls oss://example-bucket
重要通過命令列參數需要傳入存取金鑰,可能會被日誌系統記錄,存在密鑰泄露的風險,請謹慎使用。
使用臨時Token訪問
以杭州地區名稱為example-bucket的Bucket為例進行說明。
通過設定檔
產生如下的設定檔,並儲存在~/.myossutilconfig。
[Credentials] endpoint = oss-cn-hangzhou.aliyuncs.com accessKeyID = STS.LTAI4Fw2NbDUCV8zYUzA**** accessKeySecret = 67DLVBkH7EamOjy2W5RVAHUY9H**** stsToken = yourSecurityToken
通過如下命令查詢Bucket中的對象。
ossutil64 -c ~/.myossutilconfig ls oss://example-bucket
通過命令列選項
您也可以直接將存取金鑰通過命令列參數傳入,範例程式碼如下:
ossutil64 -e oss-cn-hangzhou.aliyuncs.com -i STS.LTAI4Fw2NbDUCV8zYUzA**** -k 67DLVBkH7EamOjy2W5RVAHUY9H**** -t yourSecurityToken ls oss://example-bucket
說明通過命令列參數需要傳入存取金鑰,可能會被日誌系統記錄,存在密鑰泄露的風險,請謹慎使用。
使用RAM角色訪問
以杭州地區名稱為example-bucket的Bucket,需要扮演的角色為ramRoleArnExample為例進行說明。
通過設定檔
產生如下的設定檔,並儲存在~/.myossutilconfig。
[Credentials] endpoint = oss-cn-hangzhou.aliyuncs.com accessKeyID = LTAI4Fw2NbDUCV8zYUzA**** accessKeySecret = 67DLVBkH7EamOjy2W5RVAHUY9H**** mode = RamRoleArn ramRoleArn = acs:ram::137918634953****:role/Alice roleSessionName = session_name_example (可以不設定) tokenTimeout = 1800 (可以不設定)
通過如下命令查詢Bucket中的對象。
ossutil64 -c ~/.myossutilconfig ls oss://example-bucket
通過命令列選項
您也可以直接將存取金鑰通過命令列參數傳入,範例程式碼如下:
ossutil64 -e oss-cn-hangzhou.aliyuncs.com -i LTAI4Fw2NbDUCV8zYUzA**** -k 67DLVBkH7EamOjy2W5RVAHUY9H**** --mode RamRoleArn --ram-role-arn acs:ram::137918634953****:role/Alice ls oss://example-bucket
說明通過命令列參數需要傳入存取金鑰,可能會被日誌系統記錄,存在密鑰泄露的風險,請謹慎使用。
使用執行個體RAM角色訪問
在Elastic Compute Service上,您還可以通過執行個體RAM角色的方式來配置ossutil訪問憑證。執行個體RAM角色允許您將一個角色關聯到雲端服務器執行個體,在執行個體內部基於臨時憑證STS使用ossutil。臨時憑證由系統自動產生和更新,應用程式可以使用指定的執行個體中繼資料URL擷取臨時憑證,無需特別管理。藉助於RAM,一方面保證AccessKey安全,另一方面實現許可權的精細化控制和管理。
使用前請先在ECS上建立執行個體RAM角色。更多資訊,請參見概述。
以杭州地區名稱為example-bucket的Bucket、ECS上建立的角色名稱為EcsRamRoleOss為例進行說明。
通過設定檔
產生如下的設定檔,並儲存在~/.myossutilconfig。
[Credentials] endpoint = oss-cn-hangzhou.aliyuncs.com mode = EcsRamRole ecsRoleName = EcsRamRoleOss
通過如下命令查詢Bucket中的對象。
ossutil64 -c ~/.myossutilconfig ls oss://example-bucket
通過命令列選項
您也可以直接將存取金鑰通過命令列參數傳入,範例程式碼如下:
ossutil64 -e oss-cn-hangzhou.aliyuncs.com --mode EcsRamRole --ecs-role-name EcsRamRoleOss ls oss://example-bucket
為Bucket單獨配置Endpoint
在使用ossutil的過程中,您需要管理多個Bucket,此時需要對Bucket單獨配置Endpoint。您可以通過如下兩種方式進行配置:
通過設定檔
在設定檔裡,增加一個[Bucket-Endpoint]配置段,為每個指定的Bucket單獨配置Endpoint,格式如下:
[Bucket-Endpoint] bucket1 = endpoint1 bucket2 = endpoint2 ...
以杭州地區Bucket(example-bucket-hz)、北京地區Bucket(example-bucket-bj)、上海地區Bucket(example-bucket-sh)為例進行說明。
產生如下的設定檔,並儲存在~/.myossutilconfig。
[Credentials] endpoint = oss-cn-hangzhou.aliyuncs.com accessKeyID = LTAI4Fw2NbDUCV8zYUzA**** accessKeySecret = LTAI4Fw2NbDUCV8zYUzA**** [Bucket-Endpoint] example-bucket-hz=oss-cn-hangzhou.aliyuncs.com example-bucket-bj=oss-cn-beijing.aliyuncs.com example-bucket-sh=oss-cn-shanghai.aliyuncs.com
通過如下命令查詢Bucket中的對象。
ossutil64 -c ~/.myossutilconfig ls oss://example-bucket-hz ossutil64 -c ~/.myossutilconfig ls oss://example-bucket-bj ossutil64 -c ~/.myossutilconfig ls oss://example-bucket-sh
通過命令列選項
以杭州地區Bucket(example-bucket-hz)、北京地區Bucket(example-bucket-bj)、上海地區Bucket(example-bucket-sh)為例進行說明。
將帳號資訊配置在~/.myossutilconfig中。
[Credentials] endpoint = oss-cn-hangzhou.aliyuncs.com accessKeyID = LTAI4Fw2NbDUCV8zYUzA**** accessKeySecret = 67DLVBkH7EamOjy2W5RVAHUY9H****
通過-e參數指定Endpoint。
ossutil64 -c ~/.myossutilconfig ls oss://example-bucket-hz ossutil64 -c ~/.myossutilconfig -e oss-cn-beijing.aliyuncs.com ls oss://example-bucket-bj ossutil64 -c ~/.myossutilconfig -e oss-cn-shanghai.aliyuncs.com ls oss://example-bucket-sh
配置自訂網域名
ossutil支援通過自訂網域名來訪問OSS資源。在使用之前,需要通過設定檔設定Bucket和自訂網域名的映射關係。
在設定檔裡,增加一個[Bucket-Cname]
配置段,為每個指定的Bucket單獨配置Endpoint,格式如下:
[Bucket-Cname]
bucket1 = cname1
bucket2 = cname2
...
以杭州地區名稱為example-bucket的Bucket、通過cname.example-***.com自訂網域名訪問為例進行說明。
產生如下的設定檔,並儲存在~/.myossutilconfig。
[Credentials]
accessKeyID = LTAI4Fw2NbDUCV8zYUzA****
accessKeySecret = 67DLVBkH7EamOjy2W5RVAHUY9H****
[Bucket-Cname]
example-bucket=cname.example-***.com
通過如下命令查詢Bucket中的對象。
ossutil64 -c ~/.myossutilconfig ls oss://example-bucket