huawei-cloud-maas-tokens-usage

Huawei Cloud MaaS トークン使用状況監視スキル

概要

ShowStatistics API を使用して、Huawei Cloud MaaS（Model as a Service）の使用状況統計を照会します。合計トークン数、プロンプトトークン数、生成トークン数、合計リクエスト数、合計エラー数などを取得できます。過去 7 日間、14 日間、30 日間、またはカスタム期間を指定して照会できます。デフォルトの照会タイプは MaaS プリセットサービスです。AK/SK が Python プロセスのメモリ外に出ることはありません。

ツール分離の原則：

• Python SDK による署名 — AK/SK の署名には huaweicloudsdkcore.signer.Signer を使用します（認証情報が Python プロセスのメモリ外に出ることはなく、ps -ef に表示されることもありません）。
• Python requests — MaaS ShowStatistics エンドポイントに HTTP POST します（署名済みリクエストは Python プロセスからのみ送信されます）。
• hcloud CLI は使用しません — MaaS ShowStatistics は KooCLI の対象外です。純粋な Python REST と SDK による署名を使用します。

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

• AK/SK は Python スクリプトによって環境変数（HW_ACCESS_KEY／HW_SECRET_KEY）または認証情報ファイルから読み取られます（会話中にユーザーが入力することはなく、CLI 引数として渡されることも、シェルにエクスポートされることもありません）。
• 一時的な認証情報では HW_SECURITY_TOKEN を追加します（SDK 署名ツールが X-Security-Token ヘッダーとして渡します）。
• 署名は Python プロセス内で huaweicloudsdkcore.Signer によって実行されます。署名済みの Authorization ヘッダーは MaaS エンドポイントにのみ送信されます。
• AK/SK が出力、ログ、ps -ef、会話に表示されることはありません。
• KMS への依存、hcloud CLI への依存、サードパーティ製スキルへの依存はありません。

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

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

禁止されている操作	理由
❌ 会話中に AK/SK を直接入力するようユーザーに求める	認証情報を会話中に表示してはなりません
❌ 会話中にユーザーから直接提供された AK/SK を受け入れる	認証情報を会話中に表示してはなりません
❌ AK/SK をスクリプトやコマンドライン引数にハードコードする	認証情報が漏えいするリスクがあります
❌ 平文の AK/SK 値を渡すために hcloud configure set を使用する	認証情報がコマンド履歴に記録されます
❌ AK/SK の値を出力またはログに記録する	認証情報は Python プロセスのメモリ内にのみ保持する必要があります
❌ スクリプトによって AK/SK をシェル変数または標準出力にエクスポートする	認証情報は Python プロセス内に保持し、統計結果のみを出力する必要があります
❌ SDK-HMAC-SHA256 署名を手動で実装する	エラーが発生しやすいため、huaweicloudsdkcore.Signer を使用する必要があります
❌ カスタムエンドポイントに service_type=3 を使用する	API がサポートするのは [1, 2, 4] のみで、400 エラーが返されます
❌ タイムゾーンを CST または Asia/Shanghai にハードコードする	OS のローカルタイムゾーンを自動検出する必要があります
❌ 期間分割せずに 30 日を超える期間を照会する	API に保持されるデータは 30 日分のみです。スクリプトで自動的に期間を分割する必要があります
❌ cn-southwest-2 以外のリージョンを使用する	MaaS ShowStatistics がサポートするのは Southwest-Guiyang-1 のみです
❌ maas_rest_usage_stats.py を使わずに新しい照会スクリプトを作成する	scripts/ ディレクトリ内のスクリプトを使用する必要があります

ユーザーから禁止されている操作を要求された場合は、拒否し、セキュリティ上の制約を説明してください。

🚫 非対応の操作（機能の範囲）

このスキルが対応しているのは、ShowStatistics による集計統計クエリのみです。MaaS の監視 API ファミリーには 10 個の API がありますが、残りの 9 個はこのスキルの機能範囲外であり、実装されていません。

非対応の API	目的	対応していない理由
ListServiceStatistics	サービスごとの統計を一覧表示する	このスキルはサービスごとの内訳ではなく、トークン使用量の集計に特化しています
ShowDetailChart	詳細なグラフデータを表示する	このスキルが返すのは概要テーブルであり、グラフの系列データではありません
ListErrors	エラーの詳細を一覧表示する	このスキルが報告するのはエラー数とエラー率のみであり、エラーの詳細レコードではありません
ListServices	サービスを一覧表示する	このスキルが取得するのは統計情報であり、サービスの一覧ではありません
ListSourceIps	送信元 IP を一覧表示する	このスキルは呼び出し元 IP の分布を追跡しません
GetServiceDetailMetricData	サービスの詳細メトリクスを取得する	このスキルが提供するのは集計メトリクスであり、サービスごとの詳細情報ではありません
ListVersionStatistics	バージョン統計を一覧表示する	このスキルはモデルのバージョンごとに分類しません
GetGenerationSupportedMetrics	対応するメトリクスを取得する	このスキルは ShowStatistics の応答に含まれる固定のメトリクスセットを使用します
ShowErrorCodeChart	エラーコードのグラフを表示する	このスキルが報告するのはエラー率であり、エラーコードの分布ではありません

ユーザーから上記の API、またはその基盤となる機能（サービスごとの内訳、エラーの詳細、グラフデータ、送信元 IP の一覧、バージョン統計、エラーコードの分布など）を求められた場合は、必ず断り、このスキルが対応しているのは ShowStatistics による集計統計クエリ（合計／プロンプト／生成トークン数、リクエスト数、エラー数、エラー率）のみであることを説明してください。

アーキテクチャ

Huawei Cloud MaaS Tokens Usage Monitoring
├── Task 1: Query MaaS Tokens Usage Statistics (via MaaS ShowStatistics API)
│   ├── 1a. Load credentials    (env vars or --credentials-file, in Python memory only)
│   ├── 1b. Resolve time range  (last 7/14/30 days, this month, or custom YYYY-MM-DD)
│   ├── 1c. Auto-segment        (split ranges > 30 days, aggregate results)
│   ├── 1d. SDK sign request    (huaweicloudsdkcore.Signer, AK/SK in process memory)
│   ├── 1e. POST ShowStatistics (modelarts.{region}.myhuaweicloud.com)
│   ├── 1f. Aggregate & convert (token unit: thousand → M tokens)
│   └── 1g. Print table         (Total/Prompt/Completion Tokens, Requests, Errors, Error Rate)
└── Task 2: Verify & Report     (compare with console, check error rate)

前提条件

前提条件の確認 1/3：Python 3.8 以降と huaweicloudsdkcore が必要です

MaaS ShowStatistics クエリスクリプトは、AK/SK をプロセスのメモリ内だけに保持するために Python を使用します。 必要なパッケージをインストールします。

# システムのタイムゾーンが UTC+8 の場合は中国国内向けミラーを自動的に使用します（中国地域で高速化。Python で自動検出）
PIP_INDEX=$(python3 -c "import time;print('-i https://mirrors.huaweicloud.com/repository/pypi/simple' if -(time.timezone)//3600==8 else '')")
pip install $PIP_INDEX huaweicloudsdkcore requests

SDK のインストールを確認します。

python3 --version                          # 期待値：>= 3.8
python3 -c "import huaweicloudsdkcore; print('SDK OK')"
python3 -c "import requests; print('requests OK')"

前提条件の確認 2/3：Python SDK の認証情報に関する環境変数（最優先）

クエリスクリプト（maas_rest_usage_stats.py）は、環境変数または認証情報ファイルから認証情報を読み込みます。スクリプトを実行する前に、次の環境変数を必ず設定してください（--credentials-file を使用する場合を除く）。

変数	必須	説明
HW_ACCESS_KEY	はい	Huawei Cloud のアクセスキー ID（AK）
HW_SECRET_KEY	はい	Huawei Cloud のシークレットアクセスキー（SK）
HW_SECURITY_TOKEN	いいえ	一時セキュリティトークン（一時的な AK/SK の場合のみ）

# Linux — HW_ACCESS_KEY / HW_SECRET_KEY が設定されていることを確認します（値は表示されません）
python3 -c 'import os,sys;ak=os.environ.get("HW_ACCESS_KEY","");sk=os.environ.get("HW_SECRET_KEY","");ok=bool(ak) and bool(sk);print("AK/SK configured OK" if ok else "ERROR: HW_ACCESS_KEY/HW_SECRET_KEY not set");sys.exit(0 if ok else 1)'
# Windows（cmd / PowerShell）
python -c "import os,sys;ak=os.environ.get('HW_ACCESS_KEY','');sk=os.environ.get('HW_SECRET_KEY','');ok=bool(ak) and bool(sk);print('AK/SK configured OK' if ok else 'ERROR: HW_ACCESS_KEY/HW_SECRET_KEY not set');sys.exit(0 if ok else 1)"

確認結果に ERROR（変数が未設定）が表示された場合は、次の手順で設定してください。

• Linux：シェルのプロファイル（~/.bashrc、~/.zshrc）またはシークレットマネージャーに export HW_ACCESS_KEY=... / export HW_SECRET_KEY=... を追加し、プロファイルを source で読み込みます。
• Windows：GUI からシステム環境変数を設定します（システムのプロパティ → 詳細設定 → 環境変数 → システム環境変数 → 新規）。手順については、references/cli-installation-guide.md の「Windows GUI Setup」を参照してください。認証情報がコマンド履歴に記録されるため、setx は使用しないでください。

⚠️ これらの変数を会話内で設定したり、スクリプトにハードコードしたりしないでください。 設定後、ターミナルまたは Python プロセスを再起動し、上記の確認をもう一度実行してください。

前提条件の確認 3/3：MaaS サービスのリージョン制限

• リージョン：cn-southwest-2（Southwest-Guiyang-1）— MaaS ShowStatistics API がサポートする唯一のリージョン
• API の保持期間：統計データは 30 日間保持されます
• レート制限：リクエスト総数 ≤ 1000/分、ユーザーごと ≤ 200/分

---

認証

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

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

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

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

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

   アカウントのセキュリティを守るため、Huawei Cloud の Access Key ID と Access Key Secret を会話中に直接提供しないでください。
   
   次のいずれかの安全な方法で認証情報を設定してください：
   
   方法 1：環境変数（永続的な AK/SK）
       export HW_ACCESS_KEY=<your-access-key-id>
       export HW_SECRET_KEY=<your-access-key-secret>
   
   方法 2：環境変数（一時的な AK/SK + Security Token）
       export HW_ACCESS_KEY=<your-temp-access-key-id>
       export HW_SECRET_KEY=<your-temp-access-key-secret>
       export HW_SECURITY_TOKEN=<your-security-token>
   
   方法 3：認証情報ファイル
       AK を 1 行目、SK を 2 行目、一時的な認証情報を使用する場合は Security Token を 3 行目に記載したファイル（例：~/aksk.txt）を作成します。
       次に、--credentials-file ~/aksk.txt を使用します。
   
   設定が完了したら、リクエストを再試行してください。
   

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

---

IAM 権限ポリシー

IAM ユーザーに必要な権限（ModelArts の監視 + IAM の読み取り。MaaS クエリのワークフローのみに範囲を限定）を付与してください。権限の全表と推奨される IAM ポリシー JSON については、references/iam-policies.md を参照してください。

権限の境界：

• 範囲の制約：MaaS の統計データのクエリのみ（読み取り専用）。MaaS のサービス、エンドポイント、設定を変更または削除しないでください。
• 必ず停止する条件：認証情報がない、または無効な場合、ユーザーが確認を拒否した場合、API が 403/401 を返した場合、または期間が 30 日を超え、分割に失敗した場合。
• 禁止される操作：MaaS サービスの変更、API キーの削除、IAM ポリシーの変更、MaaS クエリのワークフロー以外のリソースへのアクセス、このスキルに記載されていないコマンドの実行。

---

主なワークフロー

タスク 1：MaaS トークン使用統計の照会

ShowStatistics API を使用して MaaS の使用統計を照会します。データは Huawei Cloud コンソールと一致します。

⚠️ ツールの分離：Python SDK による署名 + Python requests

• Python SDK（huaweicloudsdkcore.Signer）：AK/SK を使用してリクエストに署名します。認証情報が Python プロセスのメモリから外に出ることはありません。
• Python requests：署名済みの HTTP POST を MaaS エンドポイントに送信します。CLI、シェル変数、ps -ef による漏えいはありません。

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

サブタスク：

1. 1a. 認証情報を読み込む — env vars から HW_ACCESS_KEY / HW_SECRET_KEY / HW_SECURITY_TOKEN を読み込むか、--credentials-file から読み込みます（1 行に 1 つ、カンマ区切り、KEY=VALUE 形式に対応）
2. 1b. 時間範囲を解決する — --from / --to（YYYY-MM-DD）を解析するか、ユーザーの表現（「過去 7 日間」／「過去 14 日間」／「過去 30 日間」／「今月」）をローリング期間または暦上の期間に変換します
3. 1c. 自動分割する — 時間範囲が 30 日を超える場合、複数の 30 日以下の区間に分割し、結果を集計します
4. 1d. SDK でリクエストに署名する — Signer(_Creds(ak, sk)).sign(sdk_request) — AK/SK は Python プロセスのメモリ内にのみ保持されます
5. 1e. ShowStatistics に POST する — requests.post("https://modelarts.{region}.myhuaweicloud.com/v1/{project_id}/maas/monitoring/show-statistics", headers=signed_headers, data=body_bytes)
6. 1f. 集計して変換する — 各区間の結果を合計し、トークン単位を千単位から M tokens に変換します（実際の値 = value × 1000）
7. 1g. テーブルを出力する — Total Tokens / Prompt Tokens / Completion Tokens / Total Requests / Total Errors / Error Rate + Period を出力します

タスク 2：検証と報告

API の結果を Huawei Cloud コンソールと比較し、エラー率を報告します。

📄 合格基準 → references/acceptance-criteria.md

⚠️ わずかな差異は正常です。 時間境界のわずかな違いにより、API とコンソールの値に 0.1% 未満の差が生じる場合があります。データは信頼できます。

---

コアコマンド

Python スクリプト（SDK による署名 + requests — AK/SK は ps -ef に表示されません）

コマンド	説明
pip install huaweicloudsdkcore requests	Python SDK の署名ライブラリ + HTTP クライアントをインストールします（UTC+8 の場合は -i https://mirrors.huaweicloud.com/repository/pypi/simple を追加）
python3 scripts/maas_rest_usage_stats.py --from 2026-05-08 --to 2026-05-21	指定した日付範囲のプリセットサービスの使用状況を照会します（デフォルトは --service-type 2）
python3 scripts/maas_rest_usage_stats.py --from 2026-05-08 --to 2026-05-21 --service-type 1	My Service の使用状況を照会します
python3 scripts/maas_rest_usage_stats.py --from 2026-05-08 --to 2026-05-21 --service-type 4	Custom Endpoint の使用状況を照会します
python3 scripts/maas_rest_usage_stats.py --from 2026-05-08 --to 2026-05-21 --infer-type batch	バッチ推論の使用状況を照会します（デフォルトは real_time）
python3 scripts/maas_rest_usage_stats.py --from 2026-05-08 --to 2026-05-21 --api-keys key1 key2	API Key のリストで絞り込みます
python3 scripts/maas_rest_usage_stats.py --from 2026-05-08 --to 2026-05-21 --credentials-file /path/to/aksk.txt	env vars の代わりに認証情報ファイルを使用します
python3 scripts/maas_rest_usage_stats.py --from 2026-05-08 --to 2026-05-21 --raw	API の生のレスポンスを表示します（デバッグ用）

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

• MaaS の照会：必ず scripts/maas_rest_usage_stats.py を使用してください — AK/SK は ps -ef に表示されません
• 認証情報：必ず env vars または --credentials-file を使用してください — ハードコードしたり、CLI 引数で渡したりしないでください
• --service-type：1、2、4 のいずれかにしてください — 3 は使用しないでください（API は 400 を返します）
• --region：必ず cn-southwest-2 にしてください（デフォルト）— 対応している唯一のリージョンです
• 時間範囲：ユーザーの表現と正確に一致させてください — 「過去 7 日間」≠「今月」

---

パラメーターの確認

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

パラメーター	必須／任意	説明	デフォルト
期間	必須	--from / --to（YYYY-MM-DD）、またはユーザー指定の表現（「過去7日間」、「過去14日間」、「過去30日間」、「今月」）	過去7日間
サービスタイプ	任意	--service-type：1=マイサービス、2=プリセットサービス、4=カスタムエンドポイント	2（プリセットサービス）
推論タイプ	任意	--infer-type：real_time（オンライン）または batch	real_time
リージョン	任意	Huawei Cloud のリージョン（cn-southwest-2 のみサポートされています）	cn-southwest-2
API キーのフィルター	任意	特定のキーをフィルターする --api-keys リスト	すべてのキー
認証情報ファイル	任意	--credentials-file のパス（環境変数の代わりに使用）	-
生のレスポンス	任意	API の生のレスポンスを表示する --raw フラグ	オフ

注：AK/SK パラメーターは不要です。認証情報は、Python スクリプトによって環境変数または認証情報ファイルから読み取られます。AK/SK が Python プロセスからエクスポートされることはありません。

---

スクリプトツール

スクリプト	説明
maas_rest_usage_stats.py	MaaS ShowStatistics API クエリースクリプト（SDK 署名 + requests。AK/SK は ps -ef に表示されません）。30 日を超える期間を自動で分割し、OS のローカルタイムゾーンを自動検出します。永続／一時 AK/SK と認証情報ファイルに対応しています。使用方法については、上記の主要コマンドを参照してください。

⚠️ スクリプトの使用ルール：

• 既存のスクリプトを使用してください。代わりとなる新しいクエリースクリプトを作成しないでください
• スクリプトの内部ロジックを個別の curl／HTTP コマンドに分割しないでください
• SDK-HMAC-SHA256 署名を手動で実装しないでください。必ず huaweicloudsdkcore.Signer を使用してください

---

検証方法

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

クイック検証（永続 AK/SK）：

python3 -c 'import os,sys;ak=os.environ.get("HW_ACCESS_KEY","");sk=os.environ.get("HW_SECRET_KEY","");ok=bool(ak) and bool(sk);print("AK/SK configured OK" if ok else "ERROR: HW_ACCESS_KEY/HW_SECRET_KEY not set");sys.exit(0 if ok else 1)'
python3 scripts/maas_rest_usage_stats.py --from 2026-05-08 --to 2026-05-21

クイック検証（一時 AK/SK + セキュリティトークン）：

python3 -c 'import os,sys;ak=os.environ.get("HW_ACCESS_KEY","");sk=os.environ.get("HW_SECRET_KEY","");st=os.environ.get("HW_SECURITY_TOKEN","");ok=bool(ak) and bool(sk) and bool(st);print("Temp AK/SK + Token configured OK" if ok else "ERROR: HW_ACCESS_KEY/HW_SECRET_KEY/HW_SECURITY_TOKEN not set");sys.exit(0 if ok else 1)'
python3 scripts/maas_rest_usage_stats.py --from 2026-05-08 --to 2026-05-21

⚠️ 認証情報に関する注意： AK/SK は、Python スクリプトによって環境変数または認証情報ファイルから読み取られます。認証情報の設定が必要な場合は、references/cli-installation-guide.md を参照してください。

---

セキュリティ設計

セキュリティアーキテクチャでは、AK/SK を Python プロセスのメモリ内にのみ保持します。ps -ef、シェル変数、環境変数（読み取り専用アクセス）、または会話に表示されることはありません。ツールを分離し、AK/SK 認証には Python SDK による署名、MaaS エンドポイントへの HTTP POST には Python requests を使用します。認証情報が表示、記録、エクスポートされることはありません。一時的な認証情報では、SDK 署名機能を通じて HW_SECURITY_TOKEN が X-Security-Token ヘッダーに追加されます。

📄 詳細（ツール分離表、認証情報漏えいリスクの排除、認証情報のライフサイクル）→ references/security-design.md

---

参考資料

ドキュメント	説明
cli-installation-guide.md	前提条件 + Python SDK + 認証情報の設定 + Windows GUI の環境変数設定
task-query-tokens-usage.md	タスク 1：トークン使用統計のクエリ手順の詳細
related-apis.md	MaaS ShowStatistics API とパラメーターの詳細
maas-metrics.md	MaaS モニタリング指標のリファレンス
iam-policies.md	必要な IAM 権限
verification-method.md	クエリ結果の検証方法
acceptance-criteria.md	正常なパターンとエラーパターンの比較
troubleshooting.md	よくあるクエリの問題と解決方法
security-design.md	セキュリティ設計：ツールの分離、認証情報のライフサイクル
maas_rest_usage_stats.py	ShowStatistics API の使用統計スクリプト（AK/SK が ps -ef に表示されることはありません）