Object Storage Service:ossutil コマンドラインインターフェイス 2.0

クイックインテグレーション

ossutil 2.0 コマンドラインインターフェイスを使い始めるには、以下の手順に従ってください：

ossutil の設定

設定漏れによる操作の失敗を防ぐため、`ossutil config` コマンドウィザードを使用して、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.478659s elapsed

   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"

アクセス認証情報の設定

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

STS トークンの使用

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

[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 への認可されたアクセスを必要とする場合、RAMRoleARN で認証情報プロバイダーを初期化できます。この方法は STS トークンに基づいています。RAM ロールの Alibaba Cloud Resource Name (ARN) を指定することで、認証情報ツールは STS サービスから STS トークンをリクエストし、AssumeRole 操作を呼び出して現在のセッションが有効期限切れになる前に新しい 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

EcsRamRole の使用

アプリケーションが ECS インスタンス、ECI インスタンス、または Container Service for Kubernetes (ACK) のワーカーノードで実行される場合、EcsRamRole で認証情報プロバイダーを初期化することをお勧めします。この方法は STS トークンに基づいています。EcsRamRole を使用すると、ロールを ECS インスタンス、ECI インスタンス、または ACK のワーカーノードに関連付けて、インスタンス内で STS トークンを自動的にリフレッシュできます。この方法では、AccessKey ペアや STS トークンを提供する必要がなく、手動メンテナンスのリスクが排除されます。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 Service for Kubernetes (ACK) のワーカーノードに RAM ロールを設定した後、それらのノード上の Pod 内のアプリケーションは、ECS インスタンスにデプロイされたアプリケーションと同様に、メタデータサーバーを介して関連付けられたロールの STS トークンを取得できます。ただし、クラスターに信頼できないアプリケーション (例えば、未検証のコードを持つ顧客から提出されたアプリケーション) をデプロイする場合、それらがワーカーノードに関連付けられたインスタンス RAM ロールの STS トークンにアクセスできないようにしたい場合があります。これらの信頼できないアプリケーションが必要な STS トークンを安全に取得し、アプリケーションレベルの権限最小化を達成しながらクラウドリソースを保護するために、RAM Roles for Service Accounts (RRSA) 機能を使用できます。この方法は STS トークンに基づいています。Alibaba Cloud コンテナークラスターは、異なるアプリケーション Pod に対して対応するサービスアカウント OIDC トークンファイルを作成およびマウントし、関連する設定情報を環境変数に注入します。認証情報ツールは、環境変数からこの設定を取得し、STS の `AssumeRoleWithOIDC` 操作を呼び出して、OIDC トークンをバインドされたロールの STS トークンと交換します。この方法により、AccessKey ペアや STS トークンを手動で維持するリスクが排除されます。詳細については、「RRSA に基づく Pod の権限分離」をご参照ください。

以下の設定ファイルを作成し、~/.ossutilconfig として保存します。この方法は、環境変数やコマンドラインオプションではサポートされていません。

[default]
mode = oidcRoleArn
# OIDCプロバイダーのAlibaba Cloudリソースネーム (ARN) を指定します。 フォーマットは acs:ram::account-id:oidc-provider/provider-name です。
OIDCProviderArn=acs:ram::113511544585****:oidc-provider/TestOidcProvider
# OIDCトークンのファイルパスを指定します。
OIDCTokenFilePath=OIDCTokenFilePath
# 偽装するロールのARNを入力します。 フォーマットは 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 に返します。外部プロセスを使用して認証情報を取得できます。

外部コマンドは、以下のフォーマットで長期または一時的な認証情報を返すことができます。

{
  "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 レベルのコマンド、ヘルパーコマンドの 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 が設定されていませんでした。

解決策：ossutil を使用する際に設定項目が欠落していることによる操作の失敗を防ぐため、必要な基本項目 (AccessKey ID、AccessKey Secret、リージョン ID) を必ず設定してください。署名が V4 にアップグレードされたため、リージョン ID は特に重要であり、必須項目となっています。リージョン ID の取得方法の詳細については、「リージョンとエンドポイント」をご参照ください。