alibabacloud-waf-billing-backup

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:

bashaliyun 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.

1. 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

bashaliyun configure list

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

1. RAM Permissions

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

1. CLI Global Parameters

All aliyun commands must include:

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

Core Workflow

Step 1: Retrieve WAF Instance Information

bashaliyun 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:

If the user explicitly provides a region (e.g., "my instance is in ap-southeast-1"), use that region first.

If no region is given, first try --region cn-hangzhou .

If cn-hangzhou returns an empty instance, retry with --region ap-southeast-1 .

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):

bash# 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:

bashaliyun waf-openapi describe-postpay-bills
--version 2021-10-01 --force
--region
--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:

bashaliyun waf-openapi describe-postpay-bills
--version 2021-10-01 --force
--region
--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:

Parse ChargeData (JSON string) to obtain SeCU function/traffic usage details

Parse CreditChargeData (JSON string) to obtain Credit usage details

Convert usage to cost according to pricing rules

Step 5: Cost Conversion

Metering UnitUnit Price SeCU0.05 CNY / SeCU Credit100 Credit = 1 CNY

Cost for a single record:

textCost(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:

textwaf-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):

bash# 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:

markdown## 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 | C