Object Storage Service:ossutil 2.0 CLI

クイックスタート

ossutil 2.0 コマンドラインインターフェイスを使用するには、以下を行う必要があります。

ossutil の設定

設定漏れによるエラーを避けるため、ossutil 設定ウィザードを使用して AccessKey ID、AccessKey Secret、リージョン ID を迅速に設定することを推奨します。高度なオプションについては、「設定ガイド」を参照して手動でアクセス認証情報を設定してください。

この例では、設定ウィザードを使用して RAM ユーザーの AccessKey ペアをアクセス認証情報として迅速に設定する方法を示します。

コマンドの実行

1. バケットを作成します。

   ossutil mb oss://examplebucket

   次の出力は、バケット examplebucket が作成されたことを示します。

   0.668238(s) elapsed

2. ファイルをバケットにアップロードします。

   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. ファイルをダウンロードします。

   examplebucket バケットから localfolder ディレクトリに uploadFile.txt ファイルをダウンロードします。

   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

   次の出力は、uploadFile.txt が examplebucket バケットから正常に削除されたことを示します。

   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)

設定ファイル

ossutil は設定ファイルを使用して設定できます。デフォルトのパスは ~/.ossutilconfig ですが、-c フラグを使用してカスタムパスを指定することもできます。デフォルトの設定ファイルを使用する場合、ファイルパスを指定せずに 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" --region cn-hangzhou

アクセス認証情報

RAM ユーザーの AccessKey ペア

アプリケーションが安全な環境で実行され、OSS への長期的なアクセスが必要で、認証情報を頻繁にローテーションできない場合、Alibaba Cloud アカウントまたは RAM ユーザーの AccessKey ペア (AccessKey ID と AccessKey Secret) で認証情報プロバイダーを初期化できます。この方法では、AccessKey ペアを手動でメンテナンスする必要があり、セキュリティリスクとメンテナンスのオーバーヘッドが増加します。

[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

一時的なセキュリティ認証情報

アプリケーションが OSS への一時的なアクセスを必要とする場合、Security Token Service (STS) から取得した一時的なセキュリティ認証情報 (AccessKey ID、AccessKey Secret、およびセキュリティトークン) で認証情報プロバイダーを初期化できます。この方法では、セキュリティトークンを手動でメンテナンスする必要があり、セキュリティリスクと複雑さが増します。また、繰り返しの一時的なアクセスのためにトークンを手動でリフレッシュする必要があります。

[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 --region cn-hangzhou

RAM ロールの ARN

アプリケーションで、Alibaba Cloud アカウントをまたいだ OSS へのアクセスなど、OSS への承認されたアクセスが必要な場合は、RAMRoleARN を使用して認証情報プロバイダーを初期化できます。このメソッドは内部的に STS トークンを使用します。RAM ロールの ARN (Alibaba Cloud リソースネーム) を指定することで、認証情報ツールは STS サービスから STS トークンを取得し、セッションの有効期限が切れる前に AssumeRole API を呼び出して新しい STS トークンをリクエストします。また、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

ECS インスタンスの RAM ロール

アプリケーションが ECS インスタンス、ECI インスタンス、または Container Service for Kubernetes (ACK) のワーカーノードで実行される場合、ECSRAMRole を使用して認証情報プロバイダーを初期化することを推奨します。この方法は、その基盤となる実装で STS トークンを使用します。ECSRAMRole を使用すると、ロールを ECS インスタンス、ECI インスタンス、または ACK のワーカーノードに関連付けて、インスタンス内で STS トークンを自動的にリフレッシュできます。この方法では、AccessKey (AK) や STS トークンを提供する必要がなくなり、手動メンテナンスに関連するリスクが排除されます。ECSRAMRole の取得方法の詳細については、「ロールの作成」をご参照ください。

EcsRamRole モード

[default]
mode = EcsRamRole
# ecsRoleName パラメーターはオプションです。設定しない場合、ロールは自動的に取得されます。
ecsRoleName = EcsRamRoleOss 
region=ap-southeast-1

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

ossutil ls oss://examplebucket --mode EcsRamRole

EcsRamRole IMDSv2 モード

[default]
mode = Ali-EcsRamRole
# ecsRoleName パラメーターはオプションです。設定しない場合、ロールは自動的に取得されます。
ecsRoleName = EcsRamRoleOss 
region=ap-southeast-1

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

ossutil ls oss://examplebucket --mode Ali-EcsRamRole

OIDC ロールの ARN

Container Service for Kubernetes (ACK) でワーカーノードの RAM ロールを設定した後、そのノード上の Pod 内のアプリケーションは、ECS インスタンスにデプロイされたアプリケーションと同様に、メタデータサービスを通じて関連付けられたロールの STS トークンを取得できます。ただし、信頼できないアプリケーション (たとえば、クローズドソースコードを持つ顧客から提出されたアプリケーション) がコンテナクラスターにデプロイされている場合、それらのアプリケーションがワーカーノードインスタンスに関連付けられた RAM ロールの STS トークンをメタデータサービスを通じて取得することを望まないかもしれません。これらの信頼できないアプリケーションが、必要な STS トークンを安全に取得し、アプリケーションレベルの最小権限を実装しながら、クラウドリソースのセキュリティを損なわないようにするために、RRSA (RAM Roles for Service Account) 機能を使用できます。この方法は STS トークンに基づいています。Alibaba Cloud コンテナクラスターは、各アプリケーション Pod に対応するサービスアカウント OIDC トークンファイルを作成してマウントし、関連する設定情報を環境変数に注入します。その後、認証情報ツールが環境変数から設定情報を取得し、STS サービスの AssumeRoleWithOIDC API を呼び出して、OIDC トークンをロールに関連付けられた STS トークンと交換します。この方法では、Access Key (AK) や STS トークンを提供する必要がなく、AK や STS トークンの手動メンテナンスに関連するリスクが排除されます。詳細については、「RRSA を使用して ServiceAccount の RAM 権限を設定し、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 トークンが格納されているファイルパスを指定します。
OIDCTokenFilePath=OIDCTokenFilePath
# 偽装するロールの ARN を指定します。 フォーマットは acs:ram::account-id:role/role-name です。
roleArn=acs:ram::113511544585****:role/testoidc
# 異なるトークンを区別するためのカスタムロールセッション名。
roleSessionName= TestOidcAssumedRoleSession
region=ap-southeast-1

examplebucket 内のオブジェクトをクエリするには、次のコマンドを実行します：

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

外部プロセス認証情報

ossutil は認証情報を取得するために外部コマンドを実行できます。外部プロセスは標準出力 (stdout) を通じて認証情報を 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

匿名アクセス

public-read 権限の OSS リソースへのアクセスのみが必要な場合は、認証情報を提供せずに匿名アクセスを使用できます。

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

コマンドリファレンス

ossutil は、高レベルコマンド、API レベルのコマンド、ヘルパーコマンドの 3 種類のコマンドを提供します。

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

原因：ossutil 2.0 の設定時にリージョン ID を指定しませんでした。

解決策：エラーを防ぐために、次の必須項目を設定してください：AccessKey ID、AccessKey Secret、およびリージョン ID。署名バージョンが V4 にアップグレードされたため、リージョン ID は必須です。リージョン ID の取得方法の詳細については、「リージョンとエンドポイント」をご参照ください。