alicloud-storage-oss-ossutil

Category: tool

OSS（ossutil 2.0）CLI スキル

検証

python skills/storage/oss/alicloud-storage-oss-ossutil/scripts/check_ossutil.py --output output/alicloud-storage-oss-ossutil/validate.txt

合格条件：コマンドが終了コード 0 で終了し、output/alicloud-storage-oss-ossutil/validate.txt が生成されること。

出力と証拠

• コマンド出力、オブジェクト一覧、同期ログを output/alicloud-storage-oss-ossutil/ に保存します。
• 証拠として、アップロードまたは一覧表示の結果を少なくとも 1 つ保持します。

目標

• ossutil 2.0 を使用して、OSS のアップロード、ダウンロード、同期、リソース管理を行います。
• インストール、設定、認証情報、リージョン／エンドポイントの処理に対応する統一された CLI ワークフローを提供します。

クイックスタートの流れ

1. ossutil 2.0 をインストールします。
2. AK/SK とデフォルトのリージョンを設定します（ossutil config または設定ファイルを使用）。
3. ossutil ls を実行してバケットを一覧表示し、バケットのリージョンを使ってオブジェクトを一覧表示します。
4. アップロード、ダウンロード、同期、または API レベルのコマンドを実行します。

ossutil 2.0 をインストールする

• プラットフォームごとのインストール手順については、references/install.md を参照してください。

ossutil を設定する

• 対話型の設定：

ossutil config

• デフォルトの設定ファイルパス：
  • Linux/macOS：~/.ossutilconfig
  • Windows：C:\Users\issuser\.ossutilconfig

主な設定項目は次のとおりです。

• AccessKey ID
• AccessKey Secret
• Region（デフォルトの例は cn-hangzhou です。最適なリージョンが不明な場合はユーザーに確認してください）
• Endpoint（任意。省略した場合はリージョンから自動的に導出されます）

AccessKey の設定に関する注意事項

最小権限の RAM ユーザー／ロールを使用し、コマンドラインに AK を平文で渡さないでください。

推奨方法（環境変数）：

export ALICLOUD_ACCESS_KEY_ID="<your-ak>"
export ALICLOUD_ACCESS_KEY_SECRET="<your-sk>"
export ALICLOUD_REGION_ID="cn-beijing"

ALICLOUD_REGION_ID をデフォルトのリージョンとして使用できます。未設定の場合は最も妥当なリージョンを選択し、不明な場合はユーザーに確認してください。

または、標準の共有認証情報ファイルを使用します。

~/.alibabacloud/credentials

[default]
type = access_key
access_key_id = <your-ak>
access_key_secret = <your-sk>

コマンド構成（2.0）

• 高レベルコマンドの例：ossutil config
• API レベルコマンドの例：ossutil api put-bucket-acl

よく使うコマンドの例

ossutil ls
ossutil ls oss://your-bucket -r --short-format --region cn-shanghai -e https://oss-cn-shanghai.aliyuncs.com
ossutil cp ./local.txt oss://your-bucket/path/local.txt
ossutil cp oss://your-bucket/path/remote.txt ./remote.txt
ossutil sync ./local-dir oss://your-bucket/path/ --delete

推奨される実行手順（先にバケットを一覧表示し、次にオブジェクトを一覧表示）

1. すべてのバケットを一覧表示します

ossutil ls

2. 出力から対象バケットのリージョン（例：oss-cn-shanghai）を取得し、--region 形式（cn-shanghai）に変換します。

3. オブジェクトを一覧表示する際は、リージョンをまたぐ署名／エンドポイントのエラーを避けるため、--region と -e を明示的に指定します。

ossutil ls oss://your-bucket \
  -r --short-format \
  --region cn-shanghai \
  -e https://oss-cn-shanghai.aliyuncs.com

4. 非常に大きなバケットでは、最初に出力サイズを制限します。

ossutil ls oss://your-bucket --limited-num 100
ossutil ls oss://your-bucket/some-prefix/ -r --short-format --region cn-shanghai -e https://oss-cn-shanghai.aliyuncs.com

よくあるエラーと対処方法

• Error: region must be set in sign version 4.

  • 原因：リージョンが設定されていません。
  • 対処方法：設定ファイルに region を追加するか、--region cn-xxx を渡します。

• The bucket you are attempting to access must be addressed using the specified endpoint

  • 原因：リクエストのエンドポイントがバケットのリージョンと一致していません。
  • 対処方法：バケットのリージョンのエンドポイントを使用します。例：-e https://oss-cn-hongkong.aliyuncs.com。

• Invalid signing region in Authorization header

  • 原因：署名リージョンがバケットのリージョンと一致していません。
  • 対処方法：--region と -e の両方を修正します。どちらもバケットのリージョンに一致させる必要があります。

認証情報とセキュリティに関するガイダンス

• アクセス制御には RAM ユーザーの AK を優先して使用してください。
• CLI オプションは設定ファイルより優先されますが、コマンドラインでシークレットを渡すと漏えいするリスクがあります。
• 本番環境では、設定ファイルまたは環境変数を使用してシークレットを管理してください。

確認事項（不明な場合に質問する）

1. 対象はバケットですか、それともオブジェクトですか？
2. アップロード／ダウンロード／同期が必要ですか、それとも ACL／ライフサイクル／CORS などの管理操作が必要ですか？
3. 対象のリージョンとエンドポイントは何ですか？
4. 同じリージョンの ECS から OSS にアクセスしていますか（イントラネットエンドポイントが適している場合があります）？

参考資料

• OSSUTIL 2.0 の概要とインストール／設定：

  • https://help.aliyun.com/zh/oss/developer-reference/ossutil-overview

• 公式ソース一覧：references/sources.md

前提条件

• 実行前に、最小権限の Alibaba Cloud 認証情報を設定してください。
• 環境変数を優先して使用してください：ALICLOUD_ACCESS_KEY_ID、ALICLOUD_ACCESS_KEY_SECRET、任意の ALICLOUD_REGION_ID。
• リージョンが不明な場合は、変更を伴う操作を実行する前にユーザーに確認してください。

ワークフロー

1. ユーザーの意図、リージョン、識別子、および操作が読み取り専用か変更を伴うものかを確認します。
2. 接続と権限を検証するため、まず最小限の読み取り専用クエリを1つ実行します。
3. 明示的なパラメーターと限定された範囲を指定して、対象の操作を実行します。
4. 結果を検証し、出力ファイルと証拠ファイルを保存します。