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 バケットから uploadFile.txt ファイルを 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

   次の出力は、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 アカウント (root ユーザー) または 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

アプリケーションが OSS への承認済みアクセスを必要とする場合 (たとえば、Alibaba Cloud アカウント間で 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

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 (Alibaba Cloud リソースネーム) を指定します。フォーマットは 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 の取得方法の詳細については、「リージョンとエンドポイント」をご参照ください。