Object Storage Service：命令列工具ossutil 2.0

快速接入

接入命令列工具ossutil 2.0的流程如下：

配置ossutil

為避免因配置缺失導致操作失敗，推薦使用 ossutil config 命令的設定精靈快速完成 AccessKey ID、AccessKey Secret 和地區 ID 的配置。若還需管理進階配置，可參考配置指南進行手動配置訪問憑證等。

以使用 RAM 使用者的 AccessKey 配置為訪問憑證為樣本，結合設定精靈快速完成配置。

運行命令

1. 建立Bucket。

   ossutil mb oss://examplebucket

   以下輸出結果表明已成功建立examplebucket。

   0.668238(s) elapsed

2. 上傳檔案到Bucket。

   1. 建立本地檔案uploadFile.txt。

      echo 'Hello, OSS!' > uploadFile.txt

   2. 上傳檔案到儲存空間examplebucket。

      ossutil cp uploadFile.txt oss://examplebucket

      以下輸出結果表明檔案已成功上傳至examplebucket。

      Success: Total 1 file, size 12 B, Upload done:(1 objects, 12 B), avg 44 B/s
      
      0.271779(s) elapsed

3. 下載檔案。

   將已上傳的樣本檔案uploadFile.txt從examplebucket下載至本地localfolder檔案夾下。

   ossutil cp oss://examplebucket/uploadFile.txt localfolder/

   以下輸出結果表明檔案已成功下載至本地localfolder檔案夾下。

   Success: Total 1 object, size 12 B, Download done:(1 files, 12 B), avg 74 B/s
   
   0.162447(s) elapsed

4. 列舉examplebucket下的檔案。

   ossutil ls oss://examplebucket

   以下輸出結果表明已成功列舉examplebucket下的檔案。

   LastModifiedTime                   Size(B)  StorageClass   ETAG                                  ObjectName
   2024-11-26 14:35:29 +0800 CST           12      Standard   1103F650EB2C292D179A032D2A97B0F5      oss://examplebucket/uploadFile.txt
   Object Number is: 1
   
   0.124679(s) elapsed

5. 刪除examplebucket下的uploadFile.txt。

   ossutil rm oss://examplebucket/uploadFile.txt

   以下輸出結果表明已成功刪除examplebucket下的uploadFile.txt。

   0.295530(s) elapsed

6. 刪除examplebucket。

   ossutil rb oss://examplebucket

   以下輸出結果表明已成功刪除examplebucket。

   0.478659(s) elapsed

配置指南

ossutil 支援通過設定檔、環境變數和命令列選項進行配置，靈活性高。

配置的優先順序

ossutil 按以下順序讀取配置：

命令列選項 (如 -i, -k, -e) > 環境變數 (如 OSS_ACCESS_KEY_ID) > 設定檔 (~/.ossutilconfig)

設定檔

可以利用設定檔（預設路徑為 ~/.ossutilconfig，或通過 -c 選項指定自訂路徑）配置 ossutil。如果使用預設設定檔，則不需要額外指定設定檔路徑。直接運行 ossutil 命令即可，例如：

ossutil ls oss://examplebucket

如果使用自訂設定檔路徑，例如 /path/yourconfig，則需要通過 -c 選項指定設定檔路徑。例如：

ossutil -c /path/yourconfig ls oss://examplebucket

[default]
accessKeyID = "your-access-key-id"
accessKeySecret = "your-access-key-secret"

[buckets name]
bucket-name = 
  key=value

[buckets dev-bucket]
bucket-hz-01 = 
  region=cn-hangzhou
bucket-hz-02 = 
  region=cn-hangzhou
  endpoint=test.com
  addressing-style=cname
bucket-bj-01 = 
  region=cn-beijing

配置環境變數

可以參照以下步驟配置環境變數。

當前支援配置的環境變數如下：

配置命令列選項

ossutil提供了多個命令列選項，支援配置全域命令列選項。命令列選項的優先順序最高，可以覆蓋設定檔設定或環境變數設定的參數。

ossutil ls oss://examplebucket -i "your-access-key-id" -k "your-access-key-secret"

訪問憑證配置

使用 RAM 使用者的 AK

如果應用程式部署運行在安全、穩定且不易受外部攻擊的環境中，需要長期訪問的OSS，且不能頻繁輪轉憑證時，可以使用阿里雲主帳號或RAM使用者的AK（Access Key ID、Access Key Secret）初始化憑證提供者。需要注意的是，該方式需要手動維護一個AK，存在安全性風險和維護複雜度增加的風險。

[default]
accessKeyID = yourAccessKeyID
accessKeySecret = yourAccessKeySecret
region=ap-southeast-1

ossutil ls oss://examplebucket -c ~/.ossutilconfig

export OSS_ACCESS_KEY_ID=yourAccessKeyID
export OSS_ACCESS_KEY_SECRET=yourAccessKeySecret
ossutil ls oss://examplebucket

ossutil ls oss://examplebucket -i yourAccessKeyID -k yourAccessKeySecret

使用STS臨時訪問憑證

如果應用程式需要臨時訪問OSS，可以使用通過STS服務擷取的臨時身份憑證（Access Key ID、Access Key Secret和Security Token）初始化憑證提供者。需要注意的是，該方式需要手動維護一個STS Token，存在安全性風險和維護複雜度增加的風險。此外，如果需要多次臨時訪問OSS，需要手動重新整理STS Token。

[default]
accessKeyID = yourSTSAccessKeyID
accessKeySecret = yourSTSAccessKeySecret
stsToken = yourSecurityToken
region=ap-southeast-1

ossutil ls oss://examplebucket -c ~/.ossutilconfig

export OSS_ACCESS_KEY_ID=yourSTSAccessKeyID
export OSS_ACCESS_KEY_SECRET=yourSTSAccessKeySecret
export OSS_SESSION_TOKEN=yourSecurityToken
ossutil ls oss://examplebucket

ossutil ls oss://examplebucket -i yourSTSAccessKeyID -k yourSTSAccessKeySecret -t yourSecurityToken

使用RAMRoleARN

如果應用程式需要授權訪問OSS，例如跨阿里雲帳號訪問OSS，可以使用RAMRoleARN初始化憑證提供者。該方式底層實現是STS Token。通過指定RAM角色的ARN（Alibabacloud Resource Name），Credentials工具會前往STS服務擷取STS Token，並在會話到期前調用AssumeRole介面申請新的STS Token。此外，還可以通過為policy賦值來限制RAM角色到一個更小的許可權集合。

產生如下設定檔，並儲存在~/.ossutilconfig。不支援通過環境變數或者命令列選項方式設定。

[default]
accessKeyID = yourAccessKeyID
accessKeySecret = yourAccessKeySecret
mode = RamRoleArn
roleArn = acs:ram::137918634953****:role/Alice
roleSessionName = session_name_example
region=ap-southeast-1

通過如下命令查詢examplebucket中的對象。

ossutil ls oss://examplebucket -c ~/.ossutilconfig

使用ECSRAMRole

如果應用程式運行在ECS執行個體、ECI執行個體、Container ServiceKubernetes版的Worker節點中，建議使用ECSRAMRole初始化憑證提供者。該方式底層實現是STS Token。ECSRAMRole允許將一個角色關聯到ECS執行個體、ECI執行個體或Container Service Kubernetes 版的Worker節點，實現在執行個體內部自動重新整理STS Token。該方式無需提供一個AK或STS Token，消除了手動維護AK或STS Token的風險。如何擷取ECSRAMRole，請參見CreateRole - 建立角色。

[default]
mode = EcsRamRole
# ecsRoleName可以不設定，當不設定時，自動擷取。
ecsRoleName = EcsRamRoleOss 
region=ap-southeast-1

ossutil ls oss://examplebucket -c ~/.ossutilconfig

ossutil ls oss://examplebucket --mode EcsRamRole

使用OIDCRoleARN

在Container ServiceKubernetes版中設定了Worker節點RAM角色後，對應節點內的Pod中的應用也就可以像ECS上部署的應用一樣，通過中繼資料服務（Meta Data Server）擷取關聯角色的STS Token。但如果容器叢集上部署的是不可信的應用（比如部署的客戶提交的應用，代碼也沒有對開放），可能並不希望它們能通過中繼資料服務擷取Worker節點關聯執行個體RAM角色的STS Token。為了避免影響雲上資源的安全，同時又能讓這些不可信的應用安全地擷取所需的STS Token，實現應用層級的許可權最小化，可以使用RRSA（RAM Roles for Service Account）功能。該方式底層實現是STS Token。阿里雲容器叢集會為不同的應用Pod建立和掛載相應的服務賬戶OIDC Token檔案，並將相關配置資訊注入到環境變數中，Credentials工具通過擷取環境變數的配置資訊，調用STS服務的AssumeRoleWithOIDC介面換取綁定角色的STS Token。該方式無需提供一個AK或STS Token，消除了手動維護AK或STS Token的風險。詳情請參見基於RRSA的Pod許可權隔離。

產生如下的設定檔，並儲存在~/.ossutilconfig。不支援通過環境變數或者命令列選項方式設定。

[default]
mode = oidcRoleArn
#指定 OIDC 提供者的 ARN（Aliyun Resource Name），格式為 acs:ram::account-id:oidc-provider/provider-name。
OIDCProviderArn=acs:ram::113511544585****:oidc-provider/TestOidcProvider
#指定 OIDC 令牌的檔案路徑，用於儲存 OIDC 令牌
OIDCTokenFilePath=OIDCTokenFilePath
#填寫角色的ARN資訊，即需要扮演的角色ID。格式為acs:ram::113511544585****:oidc-provider/TestOidcProvider
roleArn=acs:ram::113511544585****:role/testoidc
# 自訂角色會話名稱，用於區分不同的令牌。
roleSessionName= TestOidcAssumedRoleSession
region=ap-southeast-1

通過如下命令查詢examplebucket中的對象。

ossutil ls oss://examplebucket -c ~/.ossutilconfig

外部進程擷取憑證

ossutil通過外部命令啟動一個進程，該進程與ossutil進程是獨立的，稱為外部進程。外部進程執行後，通過標準輸出把結果返回給進程的啟動者，即ossutil。可以通過外部進程擷取憑證。

外部命令返回的憑證，支援長期憑證和臨時憑證，格式如下。

{
  "AccessKeyId" : "ak",
  "AccessKeySecret" : "sk",
}

{
  "AccessKeyId" : "ak",
  "AccessKeySecret" : "sk",
  "Expiration" : "2023-12-29T07:45:02Z",
  "SecurityToken" : "token",
}

產生如下設定檔，並儲存在~/.ossutilconfig。不支援通過環境變數或者命令列選項方式設定。

[default]
mode = Process
credentialProcess = user-cmd
region=ap-southeast-1

通過如下命令查詢examplebucket中的對象。

ossutil ls oss://examplebucket -c ~/.ossutilconfig

匿名訪問

如果只需要訪問公用讀取許可權的OSS資源，可以使用匿名訪問方式，無需提供任何憑證。

ossutil cat oss://bucket/public-object --mode Anonymous

命令參考

ossutil提供了進階命令、API級命令、輔助命令等三類命令。

ossutil command [argument] [flags]  

ossutil command subcommond [argument] [flags]  

ossutil topic

{
  "CORSRule": {
    "AllowedOrigin": ["www.aliyun.com"],
    "AllowedMethod": ["PUT","GET"],
    "MaxAgeSeconds": 10000
  }
}

ossutil api put-bucket-cors --bucket examplebucket --cors-configuration file://cors-configuration.json

{"CORSRule":{"AllowedOrigin":["www.aliyun.com"],"AllowedMethod":["PUT","GET"],"MaxAgeSeconds":10000}}

ossutil api put-bucket-cors --bucket examplebucket --cors-configuration  "{\"CORSRule\":{\"AllowedOrigin\":[\"www.aliyun.com\"],\"AllowedMethod\":[\"PUT\",\"GET\"],\"MaxAgeSeconds\":10000}}"

cat cors-configuration.json | ossutil api put-bucket-cors --bucket examplebucket --cors-configuration -

ossutil api get-bucket-cors --bucket bucketexample
<?xml version="1.0" encoding="UTF-8"?>
<CORSConfiguration>
  <CORSRule>
    <AllowedOrigin>www.aliyun.com</AllowedOrigin>
    <AllowedMethod>PUT</AllowedMethod>
    <AllowedMethod>GET</AllowedMethod>
    <MaxAgeSeconds>10000</MaxAgeSeconds>
  </CORSRule>
  <ResponseVary>false</ResponseVary>
</CORSConfiguration>

ossutil api get-bucket-cors --bucket bucketexample --output-format json
{
  "CORSRule": {
    "AllowedMethod": [
      "PUT",
      "GET"
    ],
    "AllowedOrigin": "www.aliyun.com",
    "MaxAgeSeconds": "10000"
  },
  "ResponseVary": "false"
}

ossutil api get-bucket-cors --bucket bucketexample --output-query CORSRule.AllowedMethod --output-format json
[
  "PUT",
  "GET"
]

ossutil stat oss://bucketexample
ACL                         : private
AccessMonitor               : Disabled
ArchiveObjectCount          : 2
ArchiveRealStorage          : 10
ArchiveStorage              : 131072
...
StandardObjectCount         : 119212
StandardStorage             : 66756852803
Storage                     : 66756852813
StorageClass                : Standard
TransferAcceleration        : Disabled

ossutil stat oss://bucketexample --human-readable
ACL                         : private
AccessMonitor               : Disabled
ArchiveObjectCount          : 2
ArchiveRealStorage          : 10
ArchiveStorage              : 131.072k
...
StandardObjectCount         : 119.212k
StandardStorage             : 66.757G
Storage                     : 66.757G
StorageClass                : Standard
TransferAcceleration        : Disabled

命令列選項

在命令列操作中，部分命令需要附加參數以指定操作對象或設定選項，而其他命令則不需要參數。對於帶參數的命令，可以根據具體要求提供適當的參數值，以實現預期功能，例如，帶參數的命令如：

ossutil ls --profile dev

ossutil ls --profile dev允許使用者通過參數值dev指定特定的設定檔。帶參數的選項通常需要通過空格或等號（=）將選項名稱與參數值分隔，例如--profile dev或--profile=dev。當參數值包含空格時，必須使用雙引號將整個參數值括起來，以確保命令正確解析，例如 --description "OSS bucket list"。

常見問題

使用ossutil執行相關命令時，報錯region must be set in sign version 4

問題原因：在配置ossutil2.0時沒有配置地區ID項。

解決方案：為避免在使用ossutil時因配置項缺失導致操作失敗，請確保按照以下步驟配置必要的基礎項：AccessKey ID、AccessKey Secret、地區ID。特別是地區ID，由於簽名已升級到V4版本，因此成為必需項。關於如何擷取地區ID，請參見地區和Endpoint。