aliyun-oss-ossutil

Category: tool

OSS（ossutil 2.0）CLI スキル

検証

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

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

出力と証拠

• コマンドの出力、オブジェクト一覧、同期ログは output/aliyun-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 ALIBABACLOUD_ACCESS_KEY_ID="<your-ak>"
export ALIBABACLOUD_ACCESS_KEY_SECRET="<your-sk>"
export ALIBABACLOUD_REGION_ID="cn-beijing"

ALIBABACLOUD_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. 対象は Bucket ですか、それとも Object ですか？
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 認証情報を設定してください。
• 環境変数を優先してください：ALIBABACLOUD_ACCESS_KEY_ID、ALIBABACLOUD_ACCESS_KEY_SECRET、任意で ALIBABACLOUD_REGION_ID。
• リージョンが不明な場合は、変更を伴う操作を実行する前にユーザーに確認してください。

ワークフロー

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