WAF 3.0 Billing Query and Local Backup

Read-only Skill: This Skill only invokes Describe/List read-only APIs. Any Create/Modify/Delete/Release operation is strictly prohibited.

Query Alibaba Cloud WAF 3.0 billing data via OpenAPI. This Skill supports:

• Retrieving WAF instance ID and region information
• Querying daily bill summaries for pay-as-you-go instances (SeCU / Credit / cost)
• Drilling down into hourly function fees, traffic processing fees, and Credit usage details
• Querying elastic postpaid bills for prepaid instances (optional)
• Exporting raw data and summary reports as local JSON / CSV backups

---

Prerequisites

1. Dependency Check

Verify the aliyun-cli version:

aliyun version

Version >= 3.3.3 is required. If it is not installed or the version is too low, refer to references/cli-installation-guide.md.

2. Credential Configuration Check

Security rules:

• Never read, echo, or print AK/SK values
• Never read or cat credential files (e.g., ~/.aliyun/config.json)
• Never ask users to enter AK/SK directly in conversation or on the command line
• Never use aliyun configure set with plaintext credential values
• Only aliyun configure list is allowed to check credential status

aliyun configure list

If no valid configuration exists, prompt the user to configure credentials before retrying. Reference: https://help.aliyun.com/zh/cli/configure-credentials

3. RAM Permissions

This Skill requires read-only WAF permissions. See references/ram-policies.md for the full minimum RAM policy.

4. CLI Global Parameters

All aliyun commands must include:

--version 2021-10-01 --force --read-timeout 30 --connect-timeout 10 --user-agent AlibabaCloud-Agent-Skills

---

Core Workflow

Step 1: Retrieve WAF Instance Information

aliyun waf-openapi describe-instance \
  --version 2021-10-01 --force \
  --region cn-hangzhou \
  --read-timeout 30 --connect-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills

Extract from the returned JSON:

• InstanceId: WAF instance ID
• RegionId: instance region (cn-hangzhou for Mainland China, ap-southeast-1 for outside Mainland China)

Region selection rules:

1. If the user explicitly provides a region (e.g., "my instance is in ap-southeast-1"), use that region first.
2. If no region is given, first try --region cn-hangzhou.
3. If cn-hangzhou returns an empty instance, retry with --region ap-southeast-1.
4. If the user asks to check a specific region first and the instance is not found there, retry the other region.

Always record the final RegionId actually used for subsequent bill queries.

Step 2: Determine Instance Billing Type and Query Time Range

Determine the instance type from the PayType field returned by describe-instance:

• POSTPAY: pay-as-you-go instance; use describe-postpay-bills / describe-elastic-bills
• PREPAY: subscription instance; for elastic postpaid bills use describe-prepay-daily-bills

Default time-range rules:

• If not specified, query the last 7 days
• For "today's estimated bill", use 00:00:00 today to the last complete hour

Important reminder: WAF 3.0 pay-as-you-go bills are settled on a T+1 basis. If the query range includes today, only the estimated bill up to the last complete hour can be retrieved. The final bill for today will be generated on the next day. Before execution, inform the user: "Data for today is an estimated bill; the final bill is subject to T+1 actual settlement."

T+1 auto-adjustment rule: If the user's request is about "today" or the natural query range ends on today, you must adjust the bill query to yesterday (00:00:00 yesterday to 23:59:59 yesterday) and clearly state: "Because WAF 3.0 pay-as-you-go bills are settled on a T+1 basis, today's final bill is not yet available. I have adjusted the query to yesterday's final bill." Do not query today's data as the final answer unless the user explicitly asks for an estimated bill.

Calculate Unix timestamps (seconds, UTC):

# Last 7 days
START_TS=$(date -u -v-7d +%s)
END_TS=$(date -u +%s)

# Specific date (macOS)
START_TS=$(date -u -j -f '%Y-%m-%d %H:%M:%S' '2026-08-23 00:00:00' +%s)
END_TS=$(date -u -j -f '%Y-%m-%d %H:%M:%S' '2026-08-23 23:59:59' +%s)

# Linux alternative
# START_TS=$(date -u -d '2026-08-23 00:00:00' +%s)
# END_TS=$(date -u -d '2026-08-23 23:59:59' +%s)

Step 3: Query Daily Bill Summary

Suitable for the "bill list" view. For daily granularity, do not pass PeriodType; the API defaults to daily aggregation:

aliyun waf-openapi describe-postpay-bills \
  --version 2021-10-01 --force \
  --region <RegionId> \
  --InstanceId <InstanceId> \
  --StartTime <START_TS> \
  --EndTime <END_TS> \
  --MaxResults 100 \
  --read-timeout 30 --connect-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills

The returned BillDetail array contains daily Cu, TrafficCu, FunctionCu, Credit, ChargeData, etc.

Step 4: Query Hourly Function Fee / Credit Details

Corresponds to the console "View Details → Hourly Cost Details". You must explicitly pass --PeriodType hour to retrieve hourly breakdowns. Omitting this parameter may return daily data instead of hourly data:

aliyun waf-openapi describe-postpay-bills \
  --version 2021-10-01 --force \
  --region <RegionId> \
  --InstanceId <InstanceId> \
  --StartTime <START_TS> \
  --EndTime <END_TS> \
  --PeriodType hour \
  --MaxResults 24 \
  --read-timeout 30 --connect-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills

Important: Always invoke this as a separate call from the daily summary query. The daily summary (Step 3) and the hourly details (Step 4) must be two distinct aliyun commands. The only difference from Step 3 is the addition of --PeriodType hour. Do not rely on the API default granularity for hourly details; explicitly pass --PeriodType hour every time hourly breakdown is required.

For each returned record:

1. Parse ChargeData (JSON string) to obtain SeCU function/traffic usage details
2. Parse CreditChargeData (JSON string) to obtain Credit usage details
3. Convert usage to cost according to pricing rules

Step 5: Cost Conversion

| Metering Unit | Unit Price | | --- | --- | | SeCU | 0.05 CNY / SeCU | | Credit | 100 Credit = 1 CNY |

Cost for a single record:

Cost(CNY) = Cu * 0.05 + Credit * 0.01

Except for the WAF instance fee, SeCU is counted per full hour and rounded up. The WAF instance fee is billed at the actual rate of 0.5 SeCU/hour.

Step 6: Local Backup

Backup directories are organized in a year/month/day hierarchy for long-term archiving:

waf-billing-backups/
├── 2026/
│   ├── 08/
│   │   ├── 23/
│   │   │   ├── waf-billing-raw-20260823-2047.json
│   │   │   ├── waf-billing-daily-20260823-2047.csv
│   │   │   ├── waf-billing-hourly-20260823-2047.csv
│   │   │   └── waf-billing-chargedata-20260823-2047.csv
│   │   └── 24/
│   │       └── ...

Example of generating directories and saving files (macOS/Linux):

# Directory hierarchy based on the query end date
BACKUP_YEAR=$(date -u -r <END_TS> +%Y)
BACKUP_MONTH=$(date -u -r <END_TS> +%m)
BACKUP_DAY=$(date -u -r <END_TS> +%d)
BACKUP_DIR="./waf-billing-backups/${BACKUP_YEAR}/${BACKUP_MONTH}/${BACKUP_DAY}"
mkdir -p "$BACKUP_DIR"

# File name timestamp
TIMESTAMP=$(date -u +%Y%m%d-%H%M)

# Save raw API response
aliyun ... > "${BACKUP_DIR}/waf-billing-raw-${TIMESTAMP}.json"

# Summary CSV example columns
# date,hour,cu,traffic_cu,function_cu,credit,traffic_credit,function_credit,cost_rmb

Linux alternative: date -u -d @<END_TS> +%Y/%m/%d

Backup file naming convention:

• Raw response: waf-billing-raw-{YYYYMMDD-HHMM}.json
• Daily summary: waf-billing-daily-{YYYYMMDD-HHMM}.csv
• Hourly details: waf-billing-hourly-{YYYYMMDD-HHMM}.csv
• Function fee details: waf-billing-chargedata-{YYYYMMDD-HHMM}.csv

---

Output Format

Terminal Summary

Output a Markdown summary to the user:

## WAF 3.0 Billing Summary

- **Instance ID**: {InstanceId}
- **Query Range**: {START} ~ {END}
- **Total SeCU**: {total_cu}
- **Total Credit**: {total_credit}
- **Estimated Total Cost**: {total_cost} CNY

### Daily Summary

| Date | SeCU | Credit | Cost(CNY) |
| --- | --- | --- | --- |
| 2026-08-23 | 1184 | 0 | 59.20 |
| ... | ... | ... | ... |

### Local Backup Files

- `waf-billing-raw-20260824-2047.json`
- `waf-billing-daily-20260824-2047.csv`
- `waf-billing-hourly-20260824-2047.csv`

Error Handling

| Scenario | Detection | Handling | | --- | --- | --- | | Missing/invalid credentials | InvalidAccessKeyId.NotFound, SignatureDoesNotMatch | Prompt user to check aliyun configure list | | Insufficient RAM permissions | Forbidden.RAM, NoPermission | Prompt user to add permissions from references/ram-policies.md | | Instance does not exist | Empty InstanceId returned | Retry with another --region or confirm the instance is activated | | Invalid time range | InvalidParameter | Check StartTime / EndTime are Unix timestamps in seconds | | Query range includes today | EndTime >= 00:00:00 today | Inform user: "Today is an estimated bill; the final bill is subject to T+1 settlement" | | Throttling | Throttling | Wait 2 seconds and retry, up to 3 times |

---

Observability

All aliyun CLI commands invoked by this Skill must include the following User-Agent header template:

--user-agent AlibabaCloud-Agent-Skills/{SKILL_NAME}/{session-id}

At runtime, replace the placeholders:

• {SKILL_NAME} → alibabacloud-waf-billing-backup
• {session-id} → a unique 32-character hexadecimal identifier for the current Skill execution session

Session-ID Rules

• Format: strictly a 32-character hexadecimal string (e.g., a1b2c3d4e5f678901234567890123456).
• Generation: generate exactly once per Skill execution session using a cryptographically secure random source.
• Consistency: the same session-id must be reused across all API calls within a single Skill execution.
• Scope: do not reuse a session-id across different Skill executions.
• Security: do not include any user identity, AK/SK, or sensitive metadata in the UA string.

---

References

| Reference | Description | | --- | --- | | references/cli-installation-guide.md | aliyun-cli installation and configuration guide | | references/ram-policies.md | Minimum RAM permissions required | | references/billing-fields-reference.md | Billing field and cost item mapping | | related_apis.yaml | OpenAPI list invoked by this Skill |