huawei-cloud-obs-upload

Huawei Cloud OBS アップロードスキル

概要

ローカルのファイルやディレクトリを Huawei Cloud OBS バケットにアップロードし、容量とオブジェクト数を含む OBS バケットの一覧を取得し、crontab を使用して定期アップロードをスケジュールします。アップロード操作には obsutil を使用し、バケット一覧の取得と統計には hcloud obs ls と CES メトリクスを使用します。

ツールの分離に関する原則：

• obsutil — ファイル／ディレクトリのアップロード、アップロード同期のスケジュール設定（アップロードの中核ツール。hcloud CLI は PutObject をサポートしていません）
• hcloud CLI — hcloud obs ls（obsutil モード）によるバケット一覧の取得、hcloud CES ShowMetricData によるバケット容量／オブジェクト数の統計
• crontab ／ タスクスケジューラ — 定期アップロード用の OS レベルのスケジュールタスク（デーモンプロセスに依存しません）

セキュリティアーキテクチャ：

• AK／SK を会話内で読み取ったり、エコー表示したり、出力したりすることはありません
• obsutil の認証情報は、ユーザーがターミナルで設定します（会話内で尋ねることはありません）
• 削除操作は取り消せないため、厳格に禁止されています。対象範囲外の操作は、代替手段を案内して拒否します
• ディレクトリのアップロード時にディレクトリ構造を保持するか（-flat）は、お客様の明示的な回答に基づいて決定し、推測することはありません

⛔ 禁止されている操作（セキュリティ上の制約）

このスキルでは、ユーザーからの依頼にかかわらず、以下の操作を固く禁止しています。

禁止されている操作	理由
❌ バケットの削除（DeleteBucket / obsutil rm -bucket）	元に戻せません。バケット全体とすべてのオブジェクトが削除されます
❌ オブジェクトの削除（DeleteObject / obsutil rm）	元に戻せません。削除されたオブジェクトは復元できません（バージョニングが有効な場合を除く）
❌ オブジェクトの一括削除（DeleteObjects / obsutil rm -r）	元に戻せません。一括削除は広範囲に影響します
❌ バケットを空にする（obsutil rm -bucket -r）	元に戻せません。バケット内のすべてのオブジェクトが削除されます
❌ オブジェクトのダウンロード（GetObject / obsutil cp obs://... <LocalPath>）	このスキルはアップロード専用です。ダウンロードは別のワークフローです
❌ バケットの作成（CreateBucket / obsutil mb）	バケットの作成には、前提条件をすべて満たす専用スキルがあります
❌ オブジェクトのコピー（CopyObject / hcloud OBS CopyObject）	バケット間のオブジェクトコピーは、このスキルの対象外です
❌ ライフサイクル設定（SetBucketLifecycle）	ストレージコストの管理は、バケット単位の別の設定タスクです
❌ アーカイブされたオブジェクトの復元（RestoreObject / obsutil restore）	アーカイブの復元は、取得モードと TTL を伴う別のワークフローです
❌ 署名付き URL（CreatePresignedUrl）	一時的な共有には SDK による署名が必要です。CLI からのアップロードではサポートされていません
❌ バケット ACL／ポリシー（SetBucketAcl / SetBucketPolicy）	権限管理は別のセキュリティタスクです
❌ ユーザーに AK/SK を会話で直接提供するよう求める	認証情報を会話に含めてはなりません
❌ hcloud の設定ファイルから AK/SK を抽出する	認証情報は暗号化されており、直接使用できません
❌ OBS 操作の前に obsutil の認証情報を確認せずに進める	認証情報が設定されていない場合、操作は失敗します
❌ 顧客に確認せず、ディレクトリのアップロードに -flat を使用する	-flat はディレクトリ構造を破棄します。顧客の明示的な回答に従う必要があります
❌ ローカルパス、バケット名、または対象プレフィックスを推測する	必須パラメーターはユーザーから提供される必要があります

ユーザーから削除操作を依頼された場合は、拒否し、次のように伝えてください。 「セキュリティ上の制約により、このスキルでは削除操作（バケット／オブジェクトの削除、一括削除、バケットを空にする操作）は許可されていません。Huawei Cloud OBS コンソールまたは obsutil を手動で使用してください。」

対象外の操作をユーザーから依頼された場合は、実行しないでください。以下の表に記載された推奨代替手段をユーザーに案内してください。

操作	推奨される代替手段
オブジェクトのダウンロード	obsutil cp obs://<Bucket>/<Key> <LocalPath> を手動で実行するか、OBS コンソールを使用します
バケットの作成	専用スキル huawei-cloud-obs-bucket-create または OBS コンソールを使用します
オブジェクトのコピー	hcloud OBS CopyObject を手動で実行するか、OBS コンソールを使用します
ライフサイクル設定	OBS コンソール（Bucket > Lifecycle）または hcloud OBS SetBucketLifecycle を使用します
アーカイブされたオブジェクトの復元	obsutil restore obs://<Bucket>/<Key> を手動で実行するか、OBS コンソールを使用します
署名付き URL	Huawei Cloud SDK（Java／Python／Go）を使用して署名付き URL を生成するか、OBS コンソールを使用します
バケット ACL／ポリシー	OBS コンソール（Bucket > Permissions）または hcloud OBS SetBucketAcl／SetBucketPolicy を使用します

アーキテクチャ

Huawei Cloud OBS Upload Management
├── Task 1: ListBucketsWithStats   (List buckets with capacity and object count)
│   ├── 1a. hcloud obs ls: list all buckets
│   ├── 1b. CES metrics / OBS API: query bucket capacity and object count
│   └── 1c. Report bucket stats table to user
├── Task 2: UploadFile             (Upload local file or directory to target bucket)
│   ├── 2a. Confirm local path + bucket name + target prefix with user
│   ├── 2b. For directory: ask customer whether to preserve directory structure (decide -flat)
│   ├── 2c. obsutil cp: single file (-flat) or directory (-r, optional -flat by customer answer)
│   └── 2d. Verify upload result
└── Task 3: ScheduledUpload       (Schedule periodic upload of local directory to target bucket)
    ├── 3a. Confirm local dir + bucket + prefix + schedule period with user
    ├── 3b. Ask customer whether to preserve directory structure (decide -flat)
    ├── 3c. Generate obsutil upload script (with/without -flat per customer answer)
    ├── 3d. Set crontab / Task Scheduler scheduled task
    └── 3e. Verify scheduled task is set

前提条件

前提条件の確認 1/3：Huawei Cloud CLI（hcloud / KooCLI）>= 3.2.0 が必要です hcloud version を実行して、バージョンが 3.2.0 以上であることを確認してください。インストールされていない場合、またはバージョンが古い場合は、 インストール方法について references/cli-installation-guide.md を参照してください。

hcloud version

前提条件の確認 2/3：obsutil >= 5.5.0 が必要です（アップロード機能を使用する場合） ファイル／ディレクトリのアップロードには、Huawei Cloud obsutil CLI ツールが必要です。 obsutil version を実行して、バージョンが 5.5.0 以上であることを確認してください。インストールされていない場合は、 インストール方法について references/cli-installation-guide.md を参照してください。

obsutil version

前提条件の確認 3/3：obsutil の認証情報の設定が必要です

hcloud の obs モジュールは内部で obsutil に対応しており、AK/SK とエンドポイントを別途設定する必要があります。 OBS 操作を行う前に、obsutil の認証情報が設定されているか必ず確認してください：

hcloud obs ls -limit=1

応答が Please set ak, sk and endpoint in the configuration file! または InvalidAccessKeyId の場合、obsutil の認証情報が設定されていません。

解決方法：次のコマンド例を提示し、ユーザーにターミナルで設定してもらってください（会話中に AK/SK を直接尋ねないでください）：

obsutil の認証情報が設定されていません。ターミナルで次のコマンドを実行して設定してください（AK/SK は Huawei Cloud コンソールの「My Credentials」ページで取得できます）：

  hcloud obs config -i=<YourAK> -k=<YourSK> -e=obs.<Region>.myhuaweicloud.com

例（広州リージョン）：
  hcloud obs config -i=<YourAK> -k=<YourSK> -e=obs.cn-south-1.myhuaweicloud.com

一般的なエンドポイント：
  cn-north-4  → obs.cn-north-4.myhuaweicloud.com
  cn-east-3   → obs.cn-east-3.myhuaweicloud.com
  cn-south-1  → obs.cn-south-1.myhuaweicloud.com
  cn-southwest-2 → obs.cn-southwest-2.myhuaweicloud.com

設定が完了したら、再試行してください。

⚠️ hcloud のパラメーター形式に関する要件

hcloud（KooCLI）のクラウドサービス API コマンド（モジュール名が大文字のもの。例：hcloud CES ShowMetricData）では、--param=value 形式（等号で接続）を使用する必要があります。スペース区切り形式はサポートされていません。

✅ 正しい例：hcloud CES ShowMetricData --region=cn-south-1 --namespace=SYS.OBS

❌ 誤った例：hcloud CES ShowMetricData --region cn-south-1

注： hcloud obs（小文字、obsutil モード）は obsutil コマンドに直接対応し、obsutil のパラメーター形式を使用します（例：hcloud obs ls、hcloud obs config -i=...）。--param=value のルールは適用されません。hcloud OBS ListBuckets コマンドはありません。バケットの一覧表示には hcloud obs ls を使用してください。

---

認証

セキュリティルール（必ず遵守してください）：

• AK/SK の値を読み取る、復唱する、または出力することを禁止します
• 会話内で AK/SK を直接入力するようユーザーに求めることを禁止します
• hcloud configure set を使って、認証情報の平文の値を渡すことを禁止します
• 会話内でユーザーから直接提供された AK/SK を受け取ることを禁止します
• 環境変数または設定済みの CLI 設定ファイルから認証情報を読み取ることのみ許可します

⚠️ 重要：ユーザーから提供された認証情報の取り扱い

ユーザーが AK/SK を直接提供しようとした場合（例：「私の AK は xxx、SK は yyy です」）：

1. 直ちに停止します — コマンドを実行しないでください
2. 丁寧に拒否し、次のメッセージを返してください：

   アカウントのセキュリティ保護のため、Huawei Cloud Access Key ID と Access Key Secret を会話内で直接提供しないでください。
   
   認証情報の設定には、次のいずれかの安全な方法を使用してください。
   
   方法 1：対話型設定（推奨）
       hcloud configure
       # プロンプトに従って AK/SK を入力してください。認証情報はローカル設定ファイルに安全に保存されます
   
   方法 2：環境変数による設定
       export HW_ACCESS_KEY=<your-access-key-id>
       export HW_SECRET_KEY=<your-access-key-secret>
   
   設定が完了したら、もう一度リクエストしてください。
   

3. 認証情報が設定されるまで、Huawei Cloud の操作を続行しないでください

CLI 設定を確認する：

   hcloud configure list

出力に有効な設定（AK/SK、IAM など）が含まれているか確認してください。

有効な認証情報がない場合は、ここで停止してください。

---

IAM 権限ポリシー

IAM ユーザーに必要な権限があることを確認してください。権限の一覧については、references/iam-policies.md を参照してください。

最低限必要な権限：

• obs:bucket:list — バケットの一覧表示
• obs:bucket:get — バケット属性（容量、オブジェクト数）の取得
• obs:object:get — オブジェクト情報の読み取り
• obs:object:put — オブジェクトのアップロード

権限の境界：

• スコープの制約：ユーザーが指定したバケットにのみアップロードおよび一覧表示を行います。バケットレベルの設定は削除または変更しないでください。
• 次の場合は必ず停止してください：認証情報がない、または無効な場合、ユーザーが確認を拒否した場合、対象のバケットが存在しない場合、またはローカルパスが存在しない場合。
• 禁止される操作：削除操作、上記のスコープ外の操作、ユーザーが指定したバケット以外のリソースへのアクセス。

---

主なワークフロー

タスク 1：容量とオブジェクト数を含むバケット一覧の表示

obsutil でバケットを一覧表示し、CES の容量メトリクスまたは OBS API を使って、バケットの容量とオブジェクト数を照会します。

⚠️ ツールの使い分け：一覧表示には hcloud obs ls、統計情報には hcloud CES ShowMetricData を使用

• hcloud obs ls：すべてのバケットを一覧表示します（obsutil モード。--region パラメーターは不要です。リージョンは hcloud obs config -e=... で設定します）
• hcloud CES ShowMetricData / OBS API：各バケットの容量とオブジェクト数を照会します

📄 詳細な手順 → references/task-list-buckets-with-stats.md

サブタスク：

1. 1a. バケットの一覧表示 — hcloud obs ls（または obsutil ls）
2. 1b. バケット統計情報の照会 — CES の容量メトリクスまたは OBS API で容量とオブジェクト数を取得します
3. 1c. 統計情報の報告 — バケット名、容量、オブジェクト数を表で示します

タスク 2：ローカルのファイルまたはディレクトリを対象バケットにアップロードする

obsutil を使用して、指定した OBS バケットにファイルまたはディレクトリをアップロードします。単一ファイルとディレクトリのアップロードに対応しています。

⚠️ アップロード操作には hcloud ではなく obsutil が必要です

hcloud CLI は OBS オブジェクトのアップロード操作に対応していません（PutObject／UploadPart の CLI コマンドはありません）。ファイル／ディレクトリのアップロードには、必ず obsutil を使用してください。

⚠️ ディレクトリをアップロードする場合、ソースのディレクトリ構造を保持するかどうかを必ず先に顧客に確認し、その明示的な回答に基づいて -flat を使用するかどうかを決めてください。既定の判断はしないでください。

📄 詳細な手順 → references/task-upload-file.md

サブタスク：

1. 2a. パラメーターを確認する — ローカルパス、対象バケット名、対象プレフィックス（任意）をユーザーに確認します
2. 2b. -flat を決める — 単一ファイルの場合は確認せずに -flat を使用します。ディレクトリの場合は、ディレクトリ構造を保持するかどうかを顧客に確認します
3. 2c. アップロードを実行する — 単一ファイルまたはディレクトリに対して obsutil cp を実行します（顧客の回答に応じて -flat を使用、または使用しません）
4. 2d. 結果を検証する — アップロードの終了コードを確認し、バケット内にオブジェクトが存在することを確認します

タスク 3：ローカルディレクトリから対象バケットへの定期アップロードをスケジュールする

crontab のスケジュールタスクを使用して、ローカルディレクトリを指定した OBS バケットに定期的に増分アップロードします。

⚠️ スケジュールアップロードは OS レベルのスケジュールタスク機構（Linux／macOS：crontab、Windows：Task Scheduler）を使用し、デーモンプロセスには依存しません。

⚠️ スケジュールアップロードスクリプトを生成する前に、ソースのディレクトリ構造を保持するかどうかを必ず先に顧客に確認し、その明示的な回答に基づいて -flat を使用するかどうかを決めてください。既定の判断はしないでください。

📄 詳細な手順 → references/task-scheduled-upload.md

サブタスク：

1. 3a. パラメーターを確認する — ローカルディレクトリ、バケット、プレフィックス、スケジュールの間隔をユーザーに確認します
2. 3b. -flat を決める — ディレクトリ構造を保持するかどうかを顧客に確認します
3. 3c. アップロードスクリプトを生成する — $HOME/obs-scheduled-upload-<BucketName>.sh（顧客の回答に応じて -flat を使用、または使用しません）
4. 3d. スケジュールタスクを設定する — crontab（Linux／macOS）または Task Scheduler（Windows）
5. 3e. 検証する — crontab -l または schtasks /query を実行して、タスクが設定されていることを確認します

---

コアコマンド

obsutil（アップロードの中核 — hcloud に PutObject はありません）

# Upload a single file
obsutil cp <LocalFilePath> obs://<BucketName>/<ObjectKey> -flat

# Upload directory, preserve structure (customer chose "Yes")
obsutil cp <LocalDirPath> obs://<BucketName>/<Prefix> -r

# Upload directory, flatten files (customer chose "No")
obsutil cp <LocalDirPath> obs://<BucketName>/<Prefix> -r -flat

# Scheduled incremental upload, preserve structure
obsutil cp <LocalDirPath> obs://<BucketName>/<Prefix> -r -f -u

# Scheduled incremental upload, flatten files
obsutil cp <LocalDirPath> obs://<BucketName>/<Prefix> -r -flat -f -u

# List buckets
obsutil ls

hcloud CLI（バケット一覧＋統計情報）

# List all buckets (obsutil mode; no --region parameter)
hcloud obs ls

# Check obsutil credential configuration
hcloud obs ls -limit=1

# Configure obsutil credentials (user runs in terminal)
hcloud obs config -i=<AK> -k=<SK> -e=<Endpoint>

# Query bucket capacity/object count stats (cloud-service API mode, --param=value format)
hcloud CES ShowMetricData \
  --region=cn-south-1 \
  --namespace=SYS.OBS \
  --metric_name=capacity_total \
  --dim.0=bucket_name,my-bucket \
  --period=86400 \
  --filter=average \
  --from=1746057600000 \
  --to=1747612800000

⚠️ コアコマンドに関する重要な制約：

• アップロード：必ず obsutil cp を使用してください — hcloud CLI は PutObject に対応していません
• バケット一覧：必ず hcloud obs ls を使用してください — hcloud OBS ListBuckets コマンドはありません
• ディレクトリのアップロード時の -flat：顧客の明示的な回答に必ず従ってください。既定の判断はしないでください
• hcloud クラウドサービス API パラメーター（大文字のモジュール名、例：hcloud CES ...）：必ず --param=value 形式を使用してください。hcloud obs（obsutil モード）では obsutil のパラメーター形式を使用します
• AK／SK：会話に含めてはいけません。ユーザーは端末で obsutil の認証情報を設定します

---

パラメーターの確認

タスクを実行する前に、以下のパラメーターをユーザーに確認する必要があります。推測は禁止されています。

パラメーター	必須／任意	説明	デフォルト
リージョン	必須	Huawei Cloud のリージョン（例：cn-south-1、cn-north-4）。ユーザーが明示的に選択する必要があります	-
ローカルファイル／ディレクトリのパス	必須（タスク 2／3）	アップロードするローカルパス。存在し、読み取り可能である必要があります	-
ターゲットバケット名	必須（タスク 2／3）	アップロード先の OBS バケット名	-
ターゲットパスのプレフィックス	任意（タスク 2／3）	バケット内のターゲットパスのプレフィックス	バケットのルート
ディレクトリ構造を維持する	必須（ディレクトリのアップロード）	ユーザーに「はい」か「いいえ」を確認します。「はい」の場合は -flat を付けません。「いいえ」の場合は -flat を付けます	-（確認が必要）
スケジュールの期間	必須（タスク 3）	実行期間（例：1 時間ごと、毎日 8:00、30 分ごと）	-
Crontab 式	任意（タスク 3）	cron 式に詳しい場合は、ユーザーが直接指定できます	-

注：会話内で AK／SK パラメーターを確認する必要はありません。認証情報は、ユーザーがターミナルで hcloud obs config を実行して設定します。

---

検証方法

詳細については、references/verification-method.md を参照してください。よくある問題と解決方法については、references/troubleshooting.md を参照してください。

クイック検証：

hcloud version && obsutil version && hcloud obs ls -limit=1

アップロード後の検証： obsutil ls obs://<BucketName>/<Prefix> を実行して、アップロードしたオブジェクトが存在することを確認します。

---

参考資料

ドキュメント	説明
task-list-buckets-with-stats.md	タスク 1：容量とオブジェクト数を含むバケットの一覧表示
task-upload-file.md	タスク 2：ファイルまたはディレクトリのアップロード
task-scheduled-upload.md	タスク 3：スケジュールされたアップロード
related-apis.md	API と CLI コマンドの詳細
iam-policies.md	IAM 権限ポリシー
obs-metrics.md	OBS CES モニタリングメトリクスのリファレンス
verification-method.md	検証手順
acceptance-criteria.md	正常／エラーパターンの比較
cli-installation-guide.md	CLI インストールガイド
troubleshooting.md	トラブルシューティングと実践的な知見