Object Storage Service:ossutil 2.0 CLI

クイックスタート

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

ossutil の設定

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

この例では、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 アカウントまたは 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 への一時的なアクセスを必要とする場合は、セキュリティトークンサービス (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 のワーカーノード上で実行されている場合は、ECSRAMRole を使用して認証情報プロバイダーを初期化することを推奨します。この方法では、基盤となる実装で STS トークンを使用します。ECSRAMRole を使用すると、ECS インスタンス、ECI インスタンス、または Container Service for Kubernetes のワーカーノードにロールを関連付けて、インスタンス内で 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 でワーカーノード 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 リソースネーム) を指定します。形式は 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 バケット一覧"。

よくある質問

Ossutil エラー：region must be set in sign version 4

原因：ossutil 2.0 を設定する際にリージョン ID を指定していませんでした。

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