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

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

次のフローは、ossutil 2.0 コマンドラインインターフェイスと統合する方法を示しています。

ossutil の構成

構成の欠落による操作の失敗を防ぐために、`ossutil config` コマンドウィザードを使用して、AccessKey ID、AccessKey シークレット、およびリージョン 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. ファイルをダウンロードします。

   サンプルファイル 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

   次の出力は、ファイル 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"

アクセス資格情報の構成

RAM ユーザーの AccessKey ペアを使用する

アプリケーションが安全で安定した環境で実行され、外部からの攻撃に対して脆弱でなく、OSS への長期的なアクセスが必要で、資格情報を頻繁にローテーションできない場合は、Alibaba Cloud アカウントまたは RAM ユーザーの AccessKey ペア (AccessKey ID と AccessKey シークレット) で資格情報プロバイダーを初期化できます。この方法では、AccessKey ペアを手動で維持する必要があり、セキュリティリスクとメンテナンスの複雑さが増します。

[default]
accessKeyID = yourAccessKeyID
accessKeySecret = yourAccessKeySecret
region=cn-hangzhou

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

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 への一時的なアクセスを必要とする場合は、Security Token Service (STS) から取得した一時的な ID 資格情報 (AccessKey ID、AccessKey シークレット、および Security Token Service トークン) で資格情報プロバイダーを初期化できます。この方法では、STS トークンを手動で維持する必要があり、セキュリティリスクとメンテナンスの複雑さが増します。さらに、OSS に複数回一時的にアクセスするには、STS トークンを手動で更新する必要があります。

[default]
accessKeyID = yourSTSAccessKeyID
accessKeySecret = yourSTSAccessKeySecret
stsToken = yourSecurityToken
region=cn-hangzhou

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

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 への承認済みアクセスを必要とする場合は、RAM ロールの ARN を使用して資格情報プロバイダーを初期化できます。この方法は STS トークンを使用します。RAM ロールの ARN を指定すると、資格情報プロバイダーは AssumeRole 操作を呼び出して STS トークンを取得します。プロバイダーは、現在のセッションが期限切れになる前に新しいトークンを自動的に要求します。policy パラメーターに値を指定して、セッションの権限をさらに制限することもできます。

次の設定ファイルを作成し、~/.myossutilconfig として保存します。環境変数またはコマンドラインオプションを使用した構成はサポートされていません。

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

次のコマンドを実行して、バケット examplebucket 内のオブジェクトをクエリします。

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

EcsRamRole の使用

アプリケーションが ECS インスタンス、ECI インスタンス、または Container Service for ACK のワーカーノードで実行される場合は、EcsRamRole で資格情報プロバイダーを初期化することをお勧めします。この方法は STS トークンに基づいて実装されています。EcsRamRole を使用すると、ロールを ECS インスタンス、ECI インスタンス、または Container Service for ACK のワーカーノードに関連付けて、インスタンス内で STS トークンを自動的に更新できます。この方法では、AccessKey ペアや STS トークンを提供する必要がないため、手動メンテナンスのリスクが排除されます。EcsRamRole の取得方法の詳細については、「CreateRole」をご参照ください。

[default]
mode = EcsRamRole
# ecsRoleName はオプションです。設定しない場合は、自動的に取得されます。
ecsRoleName = EcsRamRoleOss 
region=cn-hangzhou

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

ossutil ls oss://examplebucket --mode EcsRamRole

OIDCRoleARN の使用

Container Service for ACK でワーカーノードの RAM ロールを設定すると、そのノード上のポッド内のアプリケーションは、ECS にデプロイされたアプリケーションと同様に、メタデータサービスを通じて関連付けられたロールの STS トークンを取得できます。ただし、信頼できないアプリケーションがコンテナークラスターにデプロイされている場合 (たとえば、レビューされていないコードを持つ顧客から送信されたアプリケーション)、ワーカーノードの関連付けられたインスタンス RAM ロールの STS トークンを取得できないようにしたい場合があります。これらの信頼できないアプリケーションが必要な STS トークンを安全に取得し、アプリケーションレベルの権限分離を実現しながらクラウドリソースを保護するには、RAM Roles for Service Accounts (RRSA) 機能を使用できます。この方法は STS トークンに基づいて実装されています。Alibaba Cloud コンテナークラスターは、各アプリケーションポッドに対応するサービスアカウント OpenID Connect (OIDC) トークンファイルを作成してマウントし、関連する構成情報を環境変数に注入します。資格情報ツールは環境変数から構成を取得し、STS サービスの AssumeRoleWithOIDC 操作を呼び出して、OIDC トークンをバインドされたロールの STS トークンと交換します。この方法では、AccessKey ペアや STS トークンを提供する必要がないため、手動メンテナンスのリスクが排除されます。詳細については、「RRSA に基づくポッド権限の分離」をご参照ください。

次の設定ファイルを生成し、~/.myossutilconfig に保存します。環境変数またはコマンドラインオプションを使用した構成はサポートされていません。

[default]
mode = oidcRoleArn
# OIDC プロバイダーの 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=cn-hangzhou

次のコマンドを実行して、バケット examplebucket 内のオブジェクトをクエリします。

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

外部プロセスからの資格情報の取得

ossutil は、資格情報を取得するために独立した外部プロセスを開始できます。外部プロセスが実行され、標準出力を通じて ossutil に資格情報を返します。

外部コマンドによって返される資格情報は、長期的なものまたは一時的なものがあります。フォーマットは次のとおりです。

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

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

次の設定ファイルを生成し、~/.myossutilconfig に保存します。環境変数またはコマンドラインオプションによる構成はサポートされていません。

[default]
mode = Process
credentialProcess = user-cmd
region=cn-hangzhou

次のコマンドを実行して、バケット examplebucket 内のオブジェクトをクエリします。

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

匿名アクセス

公開読み取りの 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 コマンドでは、ターゲットオブジェクトを指定したり、オプションを設定したりするために追加のパラメーターが必要です。これらのコマンドでは、目的の機能を実現するためにパラメーター値を指定できます。例：

ossutil ls --profile dev

コマンド ossutil ls --profile dev は、--profile パラメーターを使用して 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 シークレット、リージョン ID) を必ず構成してください。署名バージョンが V4 にアップグレードされたため、リージョン ID は必須項目です。リージョン ID の取得方法の詳細については、「OSS のリージョンとエンドポイント」をご参照ください。