huawei-cloud-cdn-universal-query

CDN Query Reference

Overview

This skill is a comprehensive reference for all 44 GET read-only CDN APIs available via hcloud CLI. It serves as a fallback skill for agents to look up the correct command syntax, required parameters, and known pitfalls when querying any CDN information.

Key Features:

Complete coverage of 44 GET CDN APIs (all validated end-to-end)
Organized by 4 functional categories: Domain Management (14), Statistics & Analytics (12), Refresh/Log/Export (8), Template/Rule/Tag/Account (10)
Command templates with parameter guidance
12 validated pitfalls and troubleshooting notes
Test domain references for validation
Explicit declaration of all 55 prohibited non-GET operations (see references/prohibited-operations.md)

Tool: hcloud CLI (KooCLI v7.2.12) Scope: Read-only GET operations only Region: Recommended to use --cli-region=<region> for CDN APIs

Triggers

Chinese triggers: CDN query, CDN API, CDN CLI, domain name query, domain name configuration, traffic statistics, bandwidth query, refresh preheat, log download, certificate query, origin configuration, cache rules, domain name ownership English triggers: CDN query, CDN API reference, CDN CLI usage, domain config, traffic statistics, bandwidth query, refresh preheat, log download, certificate query, origin config

Example user phrases (中/EN):

"Check the CDN configuration of my domain" / "Check the CDN configuration of my domain"
"Show yesterday's traffic and bandwidth" / "Show yesterday's traffic and bandwidth"
"Refresh/preheat task history" / "List refresh/preheat task history"
"Help me download CDN logs / export statistics reports" / "Download CDN logs or export statistics"
"Does this IP belong to a Huawei Cloud CDN node?" / "Check if this IP belongs to Huawei Cloud CDN"
"Check the account's CDN quota" / "Query the CDN account quota"

Near-miss / Do NOT Use

Fallback skill: this is a read-only CDN query reference — prefer a dedicated skill when one covers the scenario (cdn-traffic-anomaly-analysis, cdn-502-troubleshooting, or any other applicable CDN skill).

Do NOT use for:

Scenario	Action
Create/modify/delete CDN resources (POST/PUT/DELETE)	Refuse — strictly read-only (see references/prohibited-operations.md)
Non-CDN Huawei Cloud queries (ECS, OBS, VPC, etc.)	Use the corresponding service skill
CDN console operations / account management	Direct the user to the Huawei Cloud CDN console
Queries beyond read-only reference	Out of scope; query reference only

Near-miss handling: requests that sound like queries but are actually writes (e.g., "create a refresh task", "update cache rules", "delete a domain") are prohibited — refuse and inform, never construct or simulate the command.

⛔ Prohibited Operations (Security Constraints)

This skill is strictly read-only. All non-GET operations (POST/PUT/DELETE) are prohibited regardless of user request. The skill must refuse and direct the user to the Huawei Cloud CDN console or manual hcloud CLI for any write/modify/delete operation.

Total: 55 prohibited operations (24 POST + 25 PUT + 6 DELETE).

For the complete list of all prohibited non-GET operations with risk descriptions, see references/prohibited-operations.md.

Representative prohibited operations (full list in the reference doc):

Prohibited Operation	API/Command	Reason
❌ Create domain	`CreateDomain` (v1/v2), `CreateDomainByDuplicate`	Write operation; requires explicit authorization
❌ Delete domain	`DeleteDomain` (v1/v2)	Irreversible; removes domain from CDN
❌ Modify domain config	`UpdateDomainFullConfig` (v1/v2), `UpdateDomainOrigin`, `UpdateCacheRules`, etc.	Write operations; may affect production traffic
❌ Enable/Disable domain	`EnableDomain` (v1/v2), `DisableDomain` (v1/v2)	Affects production traffic
❌ Modify billing mode	`SetChargeModes`	Financial impact; requires explicit authorization
❌ Create refresh/preheat tasks	`CreateRefreshTasks` (v1/v2), `CreatePreheatingTasks` (v1/v2)	Write operations; affects edge cache
❌ Create/update/delete templates, rules, tags	All write APIs	Write operations; requires explicit authorization
❌ Batch copy domain	`BatchCopyDomain`	POST operation; misclassified in earlier versions as GET — now explicitly prohibited
❌ Verify domain ownership	`VerifyDomainOwner`	POST operation; triggers verification flow
❌ Set statistics config	`SetStatsConfig`	POST operation; affects account-level stats collection

If a user requests a prohibited operation, you must refuse and inform: "Per security constraints, this skill does not allow write/delete/modify operations. This skill is read-only for CDN query reference. Please use the Huawei Cloud CDN console (https://console.huaweicloud.com/cdn) or run the hcloud CLI manually for configuration changes. The complete list of 55 prohibited operations is documented in references/prohibited-operations.md."

Verifying Unlisted Operations

If you need to use a CDN CLI command not listed in this skill, you must verify its HTTP method before execution:

hcloud CDN <Operation> --help

Review the help output and locate the Method: field to determine the HTTP method.

GET → Allowed to execute. Document the command for future reference.
POST / PUT / DELETE → Prohibited. Refuse and inform the user.

Note: Method: and its value appear on separate lines in the help output. Check the line after Method: to find the HTTP method value.

KooCLI Command Format Standard

All hcloud CDN commands follow this standard format:

hcloud CDN <Operation> --cli-region=<region> [--parameter=value ...]

Format Rules:

Service name: CDN (uppercase)
Operation name: PascalCase (e.g., ListDomains v2, ShowDomainDetail, ShowDomainStats v2)
Region parameter: --cli-region=<region> (recommended: cn-north-1 for CDN)
Parameter format: --key=value (equals sign, no space)
Indexed parameters: --key.1=value1 (for array parameters)

Examples:

# Correct
hcloud CDN ListDomains/v2 --cli-region=<region> --page_size=<page_size>
hcloud CDN ShowDomainStats/v2 --cli-region=<region> --domain_name=<your-domain> --stat_type=<stat_type> --interval=<interval> --start_time=<ms> --end_time=<ms> --action=<action>

# Incorrect (space instead of equals sign)
hcloud CDN ListDomains/v2 --cli-region cn-north-1

Prerequisites

Prerequisite check: Huawei Cloud CLI (hcloud / KooCLI) >= 3.2.0 required Run hcloud version to verify version >= 3.2.0. If not installed or version is too low, see references/cli-installation-guide.md for installation guide.

hcloud version

Prerequisite check: hcloud credentials configured

Before performing CDN operations, you must verify hcloud credentials are configured:
hcloud configure list
If no valid credentials exist, stop and guide the user to configure credentials.

⚠️ hcloud parameter format requirements

hcloud (KooCLI) all parameters must use the --param=value format (connected with equals sign); space-separated format is not supported.

✅ Correct: hcloud CDN ListDomains/v2 --cli-region=<region>

❌ Incorrect: hcloud CDN ListDomains/v2 --cli-region cn-north-1

⚠️ CDN API region requirements

CDN APIs only support two regions: cn-north-1 (Beijing) and ap-southeast-1 (Singapore). Query results are region-independent (CDN is a global service). Recommended: use cn-north-1.

Authentication

Prerequisite check: Huawei Cloud credentials required

Security rules (must be followed):

Prohibited from reading, echoing, or printing AK/SK values

Prohibited from asking the user to input AK/SK directly in the conversation

Prohibited from using hcloud configure set to pass plaintext credential values

Prohibited from accepting AK/SK directly provided by the user in the conversation

Only allowed to read credentials from environment variables or configured CLI config files

⚠️ Important: Handling user-provided credentials

If a user attempts to provide AK/SK directly (e.g., "my AK is xxx, SK is yyy"):
Stop immediately - Do not execute any commands
Politely refuse and return the following message:
For account security, please do not provide Huawei Cloud Access Key ID and Access Key Secret directly in the conversation.

Please use one of the following secure methods to configure credentials:

Method 1: Interactive configuration (recommended)
    hcloud configure
    # Enter AK/SK as prompted, credentials will be securely stored in a local config file

Method 2: Environment variable configuration
    export HUAWEICLOUD_SDK_AK=<your-access-key-id>
    export HUAWEICLOUD_SDK_SK=<your-secret-key>

After configuration is complete, please retry your request.
Do not continue executing any Huawei Cloud operations until credentials are configured
Check CLI configuration:
   hcloud configure list
Check whether the output contains valid configuration (AK/SK, IAM, etc.).

If no valid credentials exist, stop here.

IAM Permission Policies

Ensure the IAM user has the required permissions. See references/iam-policies.md for details.

Minimum required permissions for read-only queries:

cdn:*:query* — All CDN query-class actions used by this skill (the 45 GET APIs)
cdn:configuration:queryDomains — List CDN domains (listed explicitly alongside the wildcard)
cdn:configuration:queryChargeMode — Query the billing mode (listed explicitly alongside the wildcard)
cdn:log:* — CDN log query and download scope
cdn:statistics:downloadExcel — Statistics Excel export

Core Commands

Quick reference for all 44 GET CDN commands organized by category.

Category 1: Domain Management (14 APIs)

Command	Purpose	Key Parameters
`hcloud CDN ListDomains/v2 --cli-region=<region> --page_size=<page_size>`	List all CDN domains	`--page_size`, `--page_number`, `--domain_status`, `--service_area`, `--show_tags`
`hcloud CDN ShowDomainDetail --cli-region=<region> --domain_id=<id>`	Get domain details by ID	`--domain_id` (required)
`hcloud CDN ShowDomainDetailByName --cli-region=<region> --domain_name=<domain>`	Get domain details by name	`--domain_name` (required); returns `domain_id`
`hcloud CDN ShowDomainFullConfig/v2 --cli-region=<region> --domain_name=<domain>`	Get full domain configuration	`--domain_name`; includes HTTPS/TLS, origin, cache, etc.
`hcloud CDN ShowOriginHost --cli-region=<region> --domain_id=<id>`	Get origin host configuration	`--domain_id`
`hcloud CDN ShowCacheRules --cli-region=<region> --domain_id=<id>`	Get cache rules	`--domain_id`
`hcloud CDN ShowResponseHeader --cli-region=<region> --domain_id=<id>`	Get response header rules	`--domain_id`
`hcloud CDN ShowRefer --cli-region=<region> --domain_id=<id>`	Get referer validation config	`--domain_id`
`hcloud CDN ShowHttpInfo --cli-region=<region> --domain_id=<id>`	Get HTTPS certificate details	`--domain_id`
`hcloud CDN ShowCertificatesHttpsInfo/v2 --cli-region=<region> --domain_name=<domain>`	Get HTTPS cert binding info	`--domain_name`
`hcloud CDN ShowBlackWhiteList --cli-region=<region> --domain_id=<id>`	Get IP black/white list	`--domain_id`
`hcloud CDN ShowVerifyDomainOwnerInfo --cli-region=<region> --domain_name=<domain>`	Get domain ownership verification	`--domain_name`
`hcloud CDN ListDomainConfigs --cli-region=<region> --item=<item> --domain_names=<domain>`	Get specific config items	`--item`, `--domain_names`
`hcloud CDN ShowTags/v2 --cli-region=<region> --resource_id=<domain_id>`	Get tags for a specific domain	`--resource_id` (required, domain_id)

📄 Detailed usage → references/api-domain-management.md

Category 2: Statistics & Analytics (12 APIs)

Command	Purpose	Key Parameters
`hcloud CDN ShowChargeModes --cli-region=<region> --product_type=<product_type>`	Get account billing mode	`--product_type` (required), `--service_area`
`hcloud CDN ShowDomainStats/v2 --cli-region=<region> --domain_name=<domain> --stat_type=<stat_type> --interval=<interval> --start_time=<ms> --end_time=<ms> --action=<action>`	Get domain statistics	`--domain_name`, `--stat_type`, `--interval`, `--start_time`, `--end_time`, `--action` (REQUIRED)
`hcloud CDN ShowBandwidthCalc --cli-region=<region> --calc_type=<calc_type> --domain_name=<domain> --start_time=<ms> --end_time=<ms>`	Get bandwidth calculation	`--calc_type`, `--domain_name`, `--start_time`, `--end_time`; max 31-day range
`hcloud CDN ShowTopDomainNames --cli-region=<region> --stat_type=<stat_type> --start_time=<ms> --end_time=<ms> --limit=10`	Get top domains by metric	`--stat_type`, `--start_time`, `--end_time`, `--limit`; max 1-day span
`hcloud CDN ListCdnDomainTopIps --cli-region=<region> --domain_name=<domain> --stat_type=<stat_type> --start_time=<ms> --end_time=<ms>`	Get top IPs	`--domain_name`, `--stat_type`, `--start_time`, `--end_time`
`hcloud CDN ListCdnDomainTopPath --cli-region=<region> --domain_name=<domain> --stat_type=<stat_type> --start_time=<ms> --end_time=<ms>`	Get top URL paths	`--domain_name`, `--stat_type`, `--start_time`, `--end_time`
`hcloud CDN ListCdnDomainTopUas --cli-region=<region> --domain_name=<domain> --stat_type=<stat_type> --start_time=<ms> --end_time=<ms>`	Get top User-Agents	`--domain_name`, `--stat_type`, `--start_time`, `--end_time`
`hcloud CDN ListCdnDomainTopRefers --cli-region=<region> --domain_name=<domain> --stat_type=<stat_type> --start_time=<ms> --end_time=<ms>`	Get top Referers	`--domain_name`, `--stat_type`, `--start_time`, `--end_time`; max 2 calls/s
`hcloud CDN ListCdnDomainTopOriginUrl --cli-region=<region> --domain_name=<domain> --stat_type=<stat_type> --start_time=<ms> --end_time=<ms>`	Get top origin URLs	`--domain_name`, `--stat_type`, `--start_time`, `--end_time`
`hcloud CDN ShowTopUrl/v2 --cli-region=<region> --domain_name=<domain> --stat_type=<stat_type> --start_time=<ms> --end_time=<ms>`	Get top URLs (v2)	`--domain_name`, `--stat_type`, `--start_time`, `--end_time`
`hcloud CDN ShowDomainLocationStats/v2 --cli-region=<region> --domain_name=<domain> --stat_type=<stat_type> --start_time=<ms> --end_time=<ms> --action=<action> --group_by=<group_by>`	Get geo/ISP stats	`--domain_name`, `--stat_type`, `--start_time`, `--end_time`, `--action`, `--group_by`, `--ip_version` (IPv4/IPv6)
`hcloud CDN ShowDomainCountryStat --cli-region=<region> --domain_name=<domain> --stat_type=<stat_type> --start_time=<ms> --end_time=<ms> --action=<action> --group_by=<group_by> --country=<country>`	Get country stats	`--domain_name`, `--stat_type`, `--start_time`, `--end_time`, `--action`, `--group_by`, `--country`; may return empty

📄 Detailed usage → references/api-statistics.md

Category 3: Refresh / Log / Export (8 APIs)

Command	Purpose	Key Parameters
`hcloud CDN ShowHistoryTasks/v2 --cli-region=<region> --page_number=<page_number> --page_size=<page_size>`	Get refresh/preheat task history	`--page_number`, `--page_size` (MUST pass together)
`hcloud CDN ShowHistoryTaskDetails/v2 --cli-region=<region> --history_tasks_id=<id>`	Get task details	`--history_tasks_id` (required)
`hcloud CDN ShowUrlTaskInfo/v2 --cli-region=<region> --start_time=<ms> --end_time=<ms> --limit=10`	Get URL task info	`--start_time`, `--end_time`, `--limit`; time span ≤ 24 hours
`hcloud CDN ListBanUrl --cli-region=<region> [--start_time=<ms> --end_time=<ms> --url=<url> --page_number=<n> --page_size=<n>]`	Get banned URL list	All 5 filter params optional: `--start_time`, `--end_time`, `--url`, `--page_number`, `--page_size`
`hcloud CDN ShowLogs/v2 --cli-region=<region> --domain_name=<domain> --start_time=<ms> --end_time=<ms>`	Get CDN logs	`--domain_name`, `--start_time`, `--end_time`; domain must NOT belong to enterprise project
`hcloud CDN ListExportTasks --cli-region=<region> --task_id=<id> --task_name=<name> --limit=10`	Get export task list	`--task_id`, `--task_name` (both required); `--limit`, `--offset`
`hcloud CDN DownloadStatisticsExcel --cli-region=<region> --domain_name=<domain> --start_time=<ms> --end_time=<ms> --excel_type=<type> --cli-read-timeout=60`	Download statistics Excel	`--domain_name`, `--start_time`, `--end_time`, `--excel_type` (required: `excel_type_usage`/`excel_type_access`/`excel_type_origin`/`excel_type_http_code`); `--enterprise_project_id`, `--excel_language`, `--interval`, `--service_area` (optional); binary Excel (xlsx); needs `--cli-read-timeout=60`
`hcloud CDN DownloadRegionCarrierExcel --cli-region=<region> --domain_name=<domain> --start_time=<ms> --end_time=<ms> --excel_type=<type> --cli-read-timeout=60`	Download region/carrier Excel	`--domain_name`, `--start_time`, `--end_time`, `--excel_type` (required: `excel_type_usage`/`excel_type_access`/`excel_type_region`/`excel_type_carrier`/`excel_type_country`/`excel_type_top_url`); `--carrier`, `--country`, `--region`, `--enterprise_project_id`, `--excel_language`, `--interval` (optional, with dependency rules); binary Excel; needs `--cli-read-timeout=60`

📄 Detailed usage → references/api-refresh-log-export.md

Category 4: Template / Rule / Tag / Account (10 APIs)

Command	Purpose	Key Parameters
`hcloud CDN ShowDomainTemplate --cli-region=<region> --tml_type=<tml_type> --limit=10`	Get domain templates	`--tml_type` (INTEGER: 1=system, 2=user), `--limit`
`hcloud CDN ShowAppliedTemplateRecord --cli-region=<region> --limit=10`	Get applied template records	`--limit`, `--offset`, `--tml_id`, `--tml_name`, `--operator_id` (all optional)
`hcloud CDN ListRuleDetails --cli-region=<region> --domain_name=<domain>`	Get rule details	`--domain_name`
`hcloud CDN ListShareCacheGroups --cli-region=<region> --limit=10`	Get shared cache groups	`--limit`
`hcloud CDN ListSubscriptionTasks --cli-region=<region> --limit=10`	Get subscription tasks	`--limit`
`hcloud CDN ShowIpInfo/v2 --cli-region=<region> --ips=<ip1,ip2,...>`	Check if IPs belong to Huawei Cloud CDN	`--ips` (≤20 IPs, comma-separated)
`hcloud CDN ShowQuota/v2 --cli-region=<region>`	Get account quota	None
`hcloud CDN ShowSpecialUser --cli-region=<region>`	Get special user config	None
`hcloud CDN ListSpecialConfiguration --cli-region=<region> --domain_name=<domain>`	Get special configurations	`--domain_name` (required); `--page_number`, `--page_size` (optional)
`hcloud CDN ShowStatsConfigs --cli-region=<region> --config_type=<type> --limit=10`	Get statistics config	`--config_type` (required, INTEGER: 0=hotspot statistics, 1=CES reporting); `--limit`, `--offset`

📄 Detailed usage → references/api-template-rule-tag-account.md

Parameter Confirmation

Before executing queries, confirm the following parameters with the user:

Parameter	Required	Description	Default	Example
`domain_name`	Depends on API	Target CDN domain	None	`<your-domain>`
`domain_id`	Depends on API	Domain ID (get from `ShowDomainDetailByName`)	None	`<domain_id>`
`start_time`	Depends on API	Start timestamp (millisecond UTC)	None	`<ms>`
`end_time`	Depends on API	End timestamp (millisecond UTC)	None	`<ms>`
`stat_type`	Depends on API	Statistics type	None	`<stat_type>`
`interval`	Depends on API	Time interval (seconds)	None	`<interval>`
`action`	Depends on API	Action parameter (REQUIRED for some APIs)	None	`<action>`
`--cli-region`	Yes	Huawei Cloud region	`cn-north-1`	`cn-north-1`

User Confirmation Checklist:

Target domain name or ID provided (if needed)
Time range confirmed (if needed)
Statistics type confirmed (if needed)
User understands this is a read-only query operation

Core Workflows

Workflow 1: Query Domain Configuration

When you need to inspect a domain's full configuration:

# Step 1: Get domain_id from domain name
hcloud CDN ShowDomainDetailByName --cli-region=<region> --domain_name=<your-domain>

# Step 2: Get full configuration
hcloud CDN ShowDomainFullConfig/v2 --cli-region=<region> --domain_name=<your-domain>

# Step 3: Get specific configurations (using domain_id from Step 1)
hcloud CDN ShowOriginHost --cli-region=<region> --domain_id=<id>
hcloud CDN ShowCacheRules --cli-region=<region> --domain_id=<id>
hcloud CDN ShowResponseHeader --cli-region=<region> --domain_id=<id>
hcloud CDN ShowRefer --cli-region=<region> --domain_id=<id>
hcloud CDN ShowHttpInfo --cli-region=<region> --domain_id=<id>
hcloud CDN ShowBlackWhiteList --cli-region=<region> --domain_id=<id>

📄 Detailed steps → references/workflow-domain-config.md

Workflow 2: Query Traffic Statistics

When you need to analyze domain traffic:

# Step 1: Query account billing mode
hcloud CDN ShowChargeModes --cli-region=<region> --product_type=<product_type>

# Step 2: Query daily traffic (flux) for past 7 days
hcloud CDN ShowDomainStats/v2 --cli-region=<region> --domain_name=<your-domain> --stat_type=<stat_type> --interval=<interval> --start_time=<ms> --end_time=<ms> --action=<action>

# Step 3: Query daily peak bandwidth (bw) for past 7 days
hcloud CDN ShowDomainStats/v2 --cli-region=<region> --domain_name=<your-domain> --stat_type=<stat_type> --interval=<interval> --start_time=<ms> --end_time=<ms> --action=<action>

# Step 4: Query 95th percentile bandwidth (bw_95) for a single day
hcloud CDN ShowBandwidthCalc --cli-region=<region> --calc_type=<calc_type> --domain_name=<your-domain> --start_time=<ms> --end_time=<ms>

📄 Detailed steps → references/workflow-traffic-stats.md

Workflow 3: Traffic Anomaly Drill-Down

When you detect traffic anomaly and need to drill down:

# Step 1: Get top domains by traffic (single day)
hcloud CDN ShowTopDomainNames --cli-region=<region> --stat_type=<stat_type> --start_time=<ms> --end_time=<ms> --limit=10

# Step 2: For the anomalous domain, drill down multiple dimensions in parallel
hcloud CDN ListCdnDomainTopIps --cli-region=<region> --domain_name=<domain> --stat_type=<stat_type> --start_time=<ms> --end_time=<ms>
hcloud CDN ListCdnDomainTopPath --cli-region=<region> --domain_name=<domain> --stat_type=<stat_type> --start_time=<ms> --end_time=<ms>
hcloud CDN ListCdnDomainTopUas --cli-region=<region> --domain_name=<domain> --stat_type=<stat_type> --start_time=<ms> --end_time=<ms>
hcloud CDN ListCdnDomainTopRefers --cli-region=<region> --domain_name=<domain> --stat_type=<stat_type> --start_time=<ms> --end_time=<ms>
hcloud CDN ListCdnDomainTopOriginUrl --cli-region=<region> --domain_name=<domain> --stat_type=<stat_type> --start_time=<ms> --end_time=<ms>
# action for ShowDomainLocationStats/v2: location_summary (汇总) / location_detail (详情)
hcloud CDN ShowDomainLocationStats/v2 --cli-region=<region> --domain_name=<domain> --stat_type=<stat_type> --start_time=<ms> --end_time=<ms> --action=<action> --group_by=<group_by>

📄 Detailed steps → references/workflow-traffic-drilldown.md

Workflow 4: Download Logs and Reports

When you need to download CDN logs or export reports:

# Step 1: Query CDN logs (domain must NOT belong to enterprise project)
hcloud CDN ShowLogs/v2 --cli-region=<region> --domain_name=<your-domain> --start_time=<ms> --end_time=<ms>

# Step 2: Download statistics Excel (binary xlsx file)
# excel_type: excel_type_usage / excel_type_access / excel_type_origin / excel_type_http_code
hcloud CDN DownloadStatisticsExcel --cli-region=<region> --domain_name=<domain> --start_time=<ms> --end_time=<ms> --excel_type=<excel_type> --cli-read-timeout=60

# Step 3: Download region/carrier Excel (binary xlsx file)
# excel_type: excel_type_usage / excel_type_access / excel_type_region / excel_type_carrier / excel_type_country / excel_type_top_url
# Note: excel_type_region requires --country=cn
hcloud CDN DownloadRegionCarrierExcel --cli-region=<region> --domain_name=<domain> --start_time=<ms> --end_time=<ms> --excel_type=<excel_type> --country=<country> --cli-read-timeout=60

📄 Detailed steps → references/workflow-logs-reports.md

Workflow 5: Diagnose Domain Issues

When you need to diagnose DNS, certificate, origin, or ownership issues:

# Step 1: Get domain_id
hcloud CDN ShowDomainDetailByName --cli-region=<region> --domain_name=<your-domain>

# Step 2: Check domain ownership
hcloud CDN ShowVerifyDomainOwnerInfo --cli-region=<region> --domain_name=<your-domain>
hcloud CDN ListDomainConfigs --cli-region=<region> --item=<item> --domain_names=<your-domain>

# Step 3: Check DNS (if IPs belong to Huawei Cloud CDN)
hcloud CDN ShowIpInfo/v2 --cli-region=<region> --ips=<ip1>,<ip2>

# Step 4: Check certificate
hcloud CDN ShowCertificatesHttpsInfo/v2 --cli-region=<region> --domain_name=<your-domain>
hcloud CDN ShowHttpInfo --cli-region=<region> --domain_id=<id>

# Step 5: Check origin configuration
hcloud CDN ShowOriginHost --cli-region=<region> --domain_id=<id>
hcloud CDN ShowBlackWhiteList --cli-region=<region> --domain_id=<id>

📄 Detailed steps → references/workflow-domain-diagnosis.md

Timestamp Calculation

All CDN APIs that accept time range parameters require millisecond-precision UTC timestamps.

Key rules:

Timestamps must be in milliseconds (e.g., <ms>)
When interval=86400, timestamps must be aligned to UTC+8 midnight
Different APIs have different time range limits:
- ShowDomainStats (v2): interval=86400 max 31-32 days (33 days+ returns CDN.0203); interval=3600 max 7 days; interval=300 max 2 days
- ShowBandwidthCalc: max 31 days
- ShowTopDomainNames: max 1 day
- ShowUrlTaskInfo (v2): max 24 hours

Use the built-in script to calculate timestamps:

# Past 3 days (default) — outputs JSON with start_time and end_time
python scripts/cdn_timestamp.py --days 3

# Past 7 days
python scripts/cdn_timestamp.py --days 7

# Last full month
python scripts/cdn_timestamp.py --month

# Current month (1st to today)
python scripts/cdn_timestamp.py --cur-month

# Specific date
python scripts/cdn_timestamp.py --date 2026-08-11

Script options: --days N (default 3), --month, --cur-month, --date YYYY-MM-DD

Usage flow: Run the script first to get the timestamp values, then manually fill them into the --start_time and --end_time parameters of the hcloud command.

📄 Detailed steps → references/task-timestamp-calculation.md

FAQ (Common Questions)

#	Question	Answer (detail: Pitfall #N in references/troubleshooting.md)
Q1	`ShowTopDomainNames` returns `CDN.0202`?	Max time span is 1 day — split into per-day queries (Pitfall #1)
Q2	Excel download times out / binary output?	Add `--cli-read-timeout=60`; output is binary xlsx/zip (`PK` header), do not parse as text (Pitfall #7)
Q3	`ShowDomainStats/v2` missing `action`?	`--action` is required (`detail`/`summary`) (Pitfall #12)
Q4	`ShowLogs/v2` fails with `user has no enterprise project id`?	Domain belongs to an enterprise project — use a non-EP domain (Pitfall #6)
Q5	`ShowTags/v2` requires `--resource_id`?	Not a list-all API; pass `domain_id` as `--resource_id` (Pitfall #13)
Q6	`ShowDomainTemplate --tml_type=system` fails?	`--tml_type` is INTEGER (1=system, 2=user), not a string (Pitfall #8)
Q7	Location/Country stats report missing `stat_type`?	Both APIs require `--stat_type` in addition to `--action`/`--group_by` (Pitfall #14)

Full 14 validated pitfalls with correct/incorrect command pairs: references/troubleshooting.md.

Failure Modes

Failure Mode	Symptom / Error	Recovery
Time range exceeds API limit	`CDN.0202` / `CDN.0203`	Split into smaller ranges per API limits (see Timestamp Calculation)
Invalid parameter combo / value	`CDN.0001` / `ip version name is incorrect: v4`	Use documented enum values (Pitfalls #2/#3/#4)
Missing required parameter	`缺少必填参数:action` etc.	Add required param (Pitfalls #12/#13/#14)
Enterprise project restriction	`user has no enterprise project id:{0}`	Use a non-EP domain (Pitfall #6)
Export timeout / binary output	Timeout / unreadable output	`--cli-read-timeout=60`; treat as binary (Pitfall #7)
Credentials not configured	`hcloud configure list` empty	Stop, guide credential config (see Authentication)
Permission denied	IAM authorization error	Check references/iam-policies.md; contact admin
Rate limiting	`ListCdnDomainTopRefers` 2 calls/s	Throttle between calls
Empty results	e.g., `ShowDomainCountryStat` empty	Confirm params; try an alternative query API

Failure handling protocol:

Look up the error in troubleshooting.md or the table above.
Apply the documented fix and retry once.
If still failing, stop and report the exact error — never fabricate results.
After each query, self-check against references/verification-method.md.

Output Format

hcloud CLI returns JSON; follow this contract when presenting results.

Key output fields:

ListDomains/v2 → total, domains[] (id, domain_name, domain_status, service_area, business_type)
ShowDomainStats/v2 → start_time, end_time, stat_type, action, interval, result.<stat_type>[]
ShowBandwidthCalc → bandwidth_calc.value (bit/s), .calc_type, .time_point

Full JSON examples and validation: references/verification-method.md.

Key enums:

stat_type: flux/bw/req_num/bs_bw/bs_flux/hit_num/bs_num/bs_fail_num/hit_flux/http_code_2xx..5xx
interval: 300/3600/86400 · action: detail/summary (location: location_detail/location_summary) · calc_type: bw_95/bw_peak/bw_95_average
domain_status: online/offline/configuring/configuring_failed · ip_version: IPv4/IPv6 (NOT v4/v6)
tml_type: INTEGER 1=system, 2=user · config_type: INTEGER 0=hotspot statistics, 1=CES reporting

Units: traffic Bytes, bandwidth bit/s, timestamps ms (UTC; UTC+8 midnight when interval=86400).

Prohibited content: never include AK/SK, plaintext credentials, or other tenants' data in any output.

Agent answer template: metric + unit + time range + data source command, e.g.:

Traffic of <domain> from <start> to <end> (UTC+8): <value> Bytes (source: hcloud CDN ShowDomainStats/v2 ...).

References

Document	Description
api-domain-management.md	Category 1: Domain Management APIs (14 APIs)
api-statistics.md	Category 2: Statistics & Analytics APIs (12 APIs)
api-refresh-log-export.md	Category 3: Refresh/Log/Export APIs (8 APIs)
api-template-rule-tag-account.md	Category 4: Template/Rule/Tag/Account APIs (10 APIs)
prohibited-operations.md	All 55 prohibited non-GET operations (POST/PUT/DELETE)
workflow-domain-config.md	Workflow 1: Query domain configuration
workflow-traffic-stats.md	Workflow 2: Query traffic statistics
workflow-traffic-drilldown.md	Workflow 3: Traffic anomaly drill-down
workflow-logs-reports.md	Workflow 4: Download logs and reports
workflow-domain-diagnosis.md	Workflow 5: Diagnose domain issues
task-timestamp-calculation.md	Millisecond timestamp calculation script
troubleshooting.md	12 key pitfalls and troubleshooting
dataflow-diagram.md	Mermaid data flow diagram
iam-policies.md	IAM permission policies
verification-method.md	Output format and verification
cli-installation-guide.md	CLI installation guide
acceptance-criteria.md	Acceptance criteria checklist

Changelog

Version	Date	Owner	Changes
1.0.0	2026-08-31	cdn-ops	Initial release: full coverage of 44 GET CDN APIs (4 categories), 14 validated pitfalls, 55 prohibited non-GET operations, 5 query workflows, `cdn_timestamp.py` timestamp script. Quality revision adds: version metadata, enhanced description with near-miss boundary, Triggers and Near-miss/Do NOT Use sections, FAQ, Failure Modes, and Output Format contract.

Not covered (by design): 13 legacy v1 GET APIs (v2 equivalents documented) and 2 unavailable GET APIs (ListAccessControlTask, ListDomainClientStats) — see Coverage Notes in references/prohibited-operations.md.