huawei-cloud-obs-stats

Huawei Cloud OBS 統計スキル

概要

Huawei Cloud OBS（Object Storage Service）の統計情報を照会します。容量とオブジェクト数を含むバケット一覧の取得、外部ネットワーク／内部ネットワークのダウンロードトラフィックの前月比付き照会、合計リクエスト数の前月比付き照会を行います。

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

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

禁止されている操作	API／コマンド	理由
❌ バケットの削除	DeleteBucket / obsutil rm -bucket	元に戻せません。バケット全体とすべてのオブジェクトが破棄されます
❌ オブジェクトの削除	DeleteObject / obsutil rm	元に戻せません。削除されたオブジェクトは復元できません（バージョニングが有効な場合を除く）
❌ オブジェクトの一括削除	DeleteObjects / obsutil rm -r	元に戻せません。一括削除は広範囲に影響します
❌ バケットを空にする	obsutil rm -bucket -r	元に戻せません。バケット内のすべてのオブジェクトが削除されます

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

アーキテクチャ

Huawei Cloud OBS Statistics
├── ListBucketsWithStats  (List buckets with capacity and object counts)
├── GetTraffic           (Query extranet/intranet download traffic with MoM comparison)
└── GetRequests           (Query total requests with MoM comparison)

前提条件

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

hcloud version

前提条件の確認 2/3：OBS バケットの一覧表示には obsutil 5.5.0 以上が必要です hcloud の OBS モジュールは内部で obsutil を使用します。バケットの一覧表示には 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

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

禁止事項：

• ❌ 会話内で AK/SK を直接ユーザーに尋ねないでください
• ❌ hcloud の設定ファイルから AK/SK を取り出さないでください（認証情報は暗号化されており、そのまま使用できません）
• ❌ OBS 操作を実行する前の認証情報の確認を省略しないでください

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

hcloud（KooCLI）では、すべてのパラメーターを --param=value 形式（等号で接続）にする必要があります。スペースで区切る形式はサポートされていません。

✅ 正しい例：hcloud OBS ListBuckets --region=cn-south-1

❌ 誤った例：hcloud OBS ListBuckets --region cn-south-1

［条件付き］CLI User-Agent — hcloud の OBS モジュールのコマンドには User-Agent ヘッダーを含められる場合がありますが、CES モジュールはこのパラメーターをサポートしていません：

• ✅ OBS モジュール：hcloud obs ls
• ❌ CES モジュール：hcloud CES ShowMetricData は --User-Agent をサポートしていません。追加すると「Invalid parameter: User-Agent」が発生します。

---

認証

前提条件の確認：Huawei Cloud の認証情報が必要です

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

• 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 HUAWEICLOUD_SDK_AK=<your-access-key-id>
       export HUAWEICLOUD_SDK_SK=<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 — オブジェクト情報の読み取り
• ces:metric:get — CES 監視メトリクスの照会（容量、オブジェクト数、トラフィック、リクエスト数）

---

主なワークフロー

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

obsutil 経由でバケットを一覧表示し、次に CES 経由でバケットの容量とオブジェクト数を照会します。容量には CES の capacity_total メトリクス、オブジェクト数には CES の object_num_all メトリクスを優先してください（バッチ照会に効率的で、収集間隔は 30 分です）。GetBucketStorageInfo は使用しないでください（hcloud OBS モジュールではサポートされていません）。

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

タスク 2：インターネット／イントラネットのダウンロードトラフィックを照会（前月比比較）

CES ShowMetricData 経由でダウンロードトラフィック（インターネット＋イントラネット）を照会し、前月比で比較します。

📄 詳細な手順 → references/task-query-traffic.md

タスク 3：総リクエスト数を照会（前月比比較）

CES ShowMetricData 経由で総リクエスト数（GET／PUT／POST／DELETE／HEAD の合計）を照会し、前月比で比較します。

📄 詳細な手順 → references/task-query-requests.md

---

コアコマンド

コマンド	説明
hcloud obs ls	すべてのバケットを一覧表示します（obsutil モード）。grep でリージョンを絞り込みます
hcloud CES ShowMetricData --region=<R> --namespace=SYS.OBS --metric_name=<M> --dim.0=bucket_name,<B> --period=86400 --filter=<F> --from=<ms> --to=<ms>	CES のメトリックデータを照会します（容量、オブジェクト数、トラフィック、リクエスト）
python3 scripts/obs_traffic_stats.py --region <R> --bucket <B> (--period <P> | --from <D> --to <D>) [--direction download|upload|both]	前月比を含むトラフィック統計
python3 scripts/obs_request_stats.py --region <R> --bucket <B> (--period <P> | --from <D> --to <D>) [--include-errors]	前月比を含むリクエスト統計

⚠️ CES の ShowMetricData は --User-Agent に対応していません。追加するとエラーになります。

よく使う CES メトリック：

メトリック	--metric_name	--filter
バケット容量（推奨）	capacity_total	average
バケットのオブジェクト数（推奨）	object_num_all	average
エクストラネットのダウンロードトラフィック	download_traffic_extranet	sum
イントラネットのダウンロードトラフィック	download_traffic_intranet	sum
GET / PUT / POST / DELETE / HEAD リクエスト	get_request_count / put_request_count / post_request_count / delete_request_count / head_request_count	sum

---

パラメーターの確認

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

パラメーター	必須／任意	説明	デフォルト
--region	必須	Huawei Cloud のリージョン（例：cn-south-1、cn-north-4）。ユーザーが明示的に指定する必要があります	-
バケット名	必須	OBS バケット名。ディメンション形式：--dim.0=bucket_name,<BucketName>	-
期間	必須	ユーザーの表現に正確に合わせる必要があります。「今月」≠「過去30日間」（下表を参照）	-
obsutil の認証情報	必須	OBS 操作の前に hcloud obs ls -limit=1 で確認します	-
--direction	任意	トラフィックの方向：download / upload / both	download
--include-errors	任意	4xx／5xx のエラーリクエスト数も照会します	false
--compare	任意	比較期間と前月比の変化を表示します。デフォルトでは無効です。ユーザーが比較／前月比を明示的に求めた場合のみ有効にします	false
--metric	任意	表示する行を限定する、カンマ区切りのメトリックキーです。obs_request_stats.py：total,get,put,post,delete,head,4xx,5xx、obs_traffic_stats.py：extranet,intranet,total。大文字と小文字は区別されません。4xx／5xx を指定すると、エラー照会が自動的に有効になります。例：--metric 4xx,5xx、--metric intranet	-

期間の解釈：

ユーザーの表現	期間
"今月"	今月1日 00:00:00 ～ 現在
"過去30日間" / "過去1か月"	現在の30日前 ～ 現在
"先月"	先月1日 00:00:00 ～ 先月末日 23:59:59
特定の日付範囲	ユーザーが指定した開始時刻と終了時刻

---

スクリプトツール

このスキルでは、トラフィックとリクエストの統計情報に関するベストプラクティスをまとめた、以下の Python スクリプトを提供します。

スクリプト	説明
obs_traffic_stats.py	前月比と併せてダウンロード／アップロードのトラフィック統計を取得します。オプション：--direction、--compare、--metric。比較はデフォルトで無効です。使用方法については、上記のコアコマンドを参照してください。
obs_request_stats.py	前月比と併せて合計リクエスト（GET/PUT/POST/DELETE/HEAD）の統計を取得します。オプション：--include-errors、--compare、--metric。比較はデフォルトで無効です。使用方法については、上記のコアコマンドを参照してください。

使用例：

# Traffic: last 30 days download traffic
python3 scripts/obs_traffic_stats.py --region <Region> --bucket <BucketName> --period last_30d

# Traffic: this month download + upload traffic
python3 scripts/obs_traffic_stats.py --region <Region> --bucket <BucketName> --period this_month --direction both

# Requests: last 30 days request count
python3 scripts/obs_request_stats.py --region <Region> --bucket <BucketName> --period last_30d

# Requests: this month request count (with 4xx/5xx error stats)
python3 scripts/obs_request_stats.py --region <Region> --bucket <BucketName> --period this_month --include-errors

# Custom date range
python3 scripts/obs_request_stats.py --region <Region> --bucket <BucketName> --from <FromDate> --to <ToDate>

これらのスクリプトには、トラフィックと帯域幅のメトリクスの違い、hcloud のディメンションパラメーターの形式、正確な時間範囲の一致、OBS には単一の request_count メトリクスがないことなど、重要な知見が反映されています。

---

検証方法

詳細については、references/verification-method.md を参照してください。

簡易検証：

# Check OBS bucket list (using obsutil)
hcloud obs ls -limit=1

# Check obsutil configuration
obsutil ls -limit=1

# Validate traffic stats script
python3 scripts/obs_traffic_stats.py --region <Region> --bucket <BucketName> --period last_30d

# Validate request stats script
python3 scripts/obs_request_stats.py --region <Region> --bucket <BucketName> --period last_30d

---

参考資料

ドキュメント	説明
task-list-buckets-with-stats.md	タスク 1：容量とオブジェクト数を含むバケット一覧の取得
task-query-traffic.md	タスク 2：前月比を含むダウンロードトラフィックの取得
task-query-requests.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	トラブルシューティングと実践的な知見
obs_traffic_stats.py	トラフィック統計スクリプト
obs_request_stats.py	リクエスト統計スクリプト