Category: service

Edge Security Acceleration (ESA) - Pages, Edge Routine, KV, Site Management, Analytics & More

Use Alibaba Cloud OpenAPI (RPC) with official Python SDK to manage all ESA capabilities.

Alibaba Cloud ESA provides five core capabilities:

• - Pages — Deploy HTML or static directories to edge nodes (quick deployment flow based on Edge Routine)
• Edge Routine (ER) — Full lifecycle management of serverless edge functions
• Edge KV — Distributed edge key-value storage with Namespace/Key/Value management
• Site Management — Site management, DNS records, cache rules, certificates, etc.
• Analytics — Traffic analysis, time-series trends, Top-N rankings, bandwidth statistics, request metrics

Use Python SDK uniformly to call ESA OpenAPI.

Prerequisites

• - Prepare AccessKey (RAM user/role with least privilege).
• Install Python SDK: INLINECODE0
• ESA OpenAPI is RPC style; prefer SDK or OpenAPI Explorer to avoid manual signing.

SDK quickstart

CODEBLOCK0

Pages — Edge Page Deployment

Pages is a quick deployment flow based on Edge Routine, deploying HTML or static directories to the edge.

HTML Page Deployment Flow

CODEBLOCK1

Static Directory Deployment Flow

CODEBLOCK2

Zip Package Structure

The zip package structure depends on EDGE_ROUTINE_TYPE (automatically determined by checkEdgeRoutineType based on whether entry file and assets directory exist):

• - JSONLY: routine/index.js (bundled with esbuild or --no-bundle to read source files directly)
• ASSETSONLY: All static files under assets/, maintaining original directory structure
• JSANDASSETS: routine/index.js + assets/ static resources (most common)

The assets/ path is relative to assets.directory in configuration. Configuration priority: CLI args > esa.jsonc / esa.toml.

Key Notes

• - Function name rules: lowercase letters/numbers/hyphens, start with lowercase letter, length >= 2
• Same name function: Reuse if exists, deploy new version code
• Deploy to both staging and production by default
• After successful deployment, get defaultRelatedRecord via GetRoutine as access domain

Detailed reference: INLINECODE14

Edge Routine (ER) — Edge Functions

Manage the complete lifecycle of serverless edge functions via Python SDK.

Core Workflow

CODEBLOCK3

API Summary

• - Function Management: CreateRoutine, DeleteRoutine, GetRoutine, GetRoutineUserInfo, INLINECODE19
• Code Version: GetRoutineStagingCodeUploadInfo, CommitRoutineStagingCode, PublishRoutineCodeVersion, INLINECODE23
• Routes: CreateRoutineRoute, UpdateRoutineRoute, DeleteRoutineRoute, GetRoutineRoute, ListRoutineRoutes, INLINECODE29
• Related Records: CreateRoutineRelatedRecord, DeleteRoutineRelatedRecord, INLINECODE32

ER Code Format

CODEBLOCK4

Detailed reference: INLINECODE33

Edge KV — Edge Key-Value Storage

Distributed edge key-value storage, readable and writable in Edge Routine, also manageable via OpenAPI/SDK.

Core Concepts

• - Namespace: Isolation container for KV data, Key max 512 chars, Value max 2MB (high capacity 25MB)
• Supports TTL expiration: Expiration (Unix timestamp) or ExpirationTtl (seconds)

API Summary

• - Namespace: CreateKvNamespace, DeleteKvNamespace, GetKvNamespace, GetKvAccount, INLINECODE40
• Single Key Operations: PutKv, GetKv, GetKvDetail, DeleteKv, INLINECODE45
• Batch Operations: BatchPutKv, BatchDeleteKv, BatchPutKvWithHighCapacity, BatchDeleteKvWithHighCapacity, INLINECODE50

Quick Start

CODEBLOCK5

Detailed reference: INLINECODE51

Site Management — Site Management

Use Python SDK to manage ESA sites, DNS records, cache rules, etc.

API behavior notes

• - Most list APIs support pagination via PageNumber + PageSize.
• INLINECODE54 returns sites across all regions; no need to iterate regions.
• Newly created sites start as pending; complete access verification via VerifySite to activate.
• Deleting a site removes all associated configuration.
• INLINECODE57 can switch between CNAME and NS, but switching to CNAME may fail if incompatible DNS records exist.
• DNS record APIs (CreateRecord, ListRecords, etc.) work for both NS and CNAME connected sites. CNAME sites are limited to CNAME and A/AAAA types only, and records cannot disable acceleration (proxy must stay enabled).
• DNS record Type parameter must be exact: use A/AAAA (not A), CNAME, MX, TXT, NS, SRV, CAA.
• INLINECODE71 supports two config types: global (site-wide default) and rule (conditional rule with match expression).

Workflow

1) Confirm target site ID, access type (CNAME/NS), and desired action.
2) Find API group and exact operation name in references/api_overview.md.
3) Call API with Python SDK (preferred) or OpenAPI Explorer.
4) Verify results with describe/list APIs.
5) If you need repeatable inventory or summaries, use scripts/ and write outputs under output/aliyun-esa-manage/.

SDK priority

1) Python SDK (preferred)
2) OpenAPI Explorer
3) Other SDKs (only if Python is not feasible)

Python SDK scripts (recommended for inventory)

• - List all ESA sites: INLINECODE77
• Summarize sites by plan: INLINECODE78
• Check site status: INLINECODE79
• List DNS records for a site: INLINECODE80

Analytics — Traffic Analysis

Query and analyze ESA site traffic data using DescribeSiteTimeSeriesData and DescribeSiteTopData APIs.

Core Features

• - Time-Series Data: Query traffic trends with configurable time granularity
• Top-N Rankings: Get rankings by country/IP/host/path/status code dimensions
• Multiple Metrics: Traffic, Requests, RequestTraffic, PageView
• Rich Dimensions: Country, province, ISP, browser, device, host, path, status code, etc.

Two Main APIs

1. DescribeSiteTimeSeriesData - Time-Series Trends

Query traffic trends over time, returning aggregated data points.

Time Granularity Rules:

2. DescribeSiteTopData - Top-N Rankings

Query Top-N ranking data by various dimensions.

Limit Options: 5, 10, INLINECODE90

Available Metrics (FieldName)

Available Dimensions

Geographic Dimensions: ClientCountryCode (country), ClientProvinceCode (province), ClientISP (ISP), INLINECODE98

Client Info: ClientIP, ClientIPVersion, ClientBrowser, ClientDevice, INLINECODE103

Request Details: ClientRequestHost, ClientRequestMethod, ClientRequestPath, ClientRequestProtocol, ClientRequestQuery, ClientRequestReferer, INLINECODE110

Response/Cache: EdgeCacheStatus, EdgeResponseStatusCode, EdgeResponseContentType, INLINECODE114

Others: ALL (aggregated), SiteId (account-level query), Version, ClientSSLProtocol, INLINECODE119

Error Handling

Detailed reference: references/time-series.md, references/top-data.md, INLINECODE127

Common operation mapping

Site Management

• - Create site: INLINECODE128
• List sites: ListSites (supports SiteName, Status, AccessType, Coverage filters)
• Get site details: INLINECODE134
• Delete site: INLINECODE135
• Check site name availability: INLINECODE136
• Verify site ownership: INLINECODE137
• Update access type: INLINECODE138
• Update coverage: INLINECODE139
• Get current nameservers: INLINECODE140
• Update custom nameservers: INLINECODE141
• Pause/resume site: UpdateSitePause, INLINECODE143
• Site exclusivity: UpdateSiteNameExclusive, INLINECODE145
• Version management: ActivateVersionManagement, INLINECODE147

Site Configuration

• - IPv6: GetIPv6, INLINECODE149

DNS Records

NS access: full record type support. CNAME access: only CNAME and A/AAAA, proxy must stay enabled.

• - Create record: INLINECODE152
• List records: ListRecords (supports Type, RecordName, Proxied filters)
• Get record: INLINECODE157
• Update record: INLINECODE158
• Delete record: INLINECODE159
• Batch create: INLINECODE160
• Export records: INLINECODE161

Cache Rules

• - Create cache rule: INLINECODE162
• List cache rules: INLINECODE163
• Get cache rule: INLINECODE164
• Update cache rule: INLINECODE165
• Delete cache rule: INLINECODE166

Cache rule expression notes (important):

• - CreateCacheRule parameters are flat, not a nested JSON Rule object.
• The Rule parameter is a match condition expression string. See Rule Expression Syntax section below.
• Quick reminders: ends_with()/starts_with() must use function-call style; matches (regex) requires standard plan or above.
• Set edge cache TTL with --EdgeCacheMode override_origin --EdgeCacheTtl <seconds>.

Rule Expression Syntax

ESA uses a unified rule engine expression syntax across multiple features (cache rules, WAF custom rules, rate limiting, URL rewrite, header modification, etc.).

When to use

Use this syntax for the Rule parameter in any ESA API that accepts a match condition expression:

• - CreateCacheRule / UpdateCacheRule - Cache rules
• INLINECODE177 / UpdateWafRule - WAF custom rules
• INLINECODE179 - Rate limiting rules
• INLINECODE180 / UpdateRewriteUrlRule - URL rewrite rules
• Origin rules, redirect rules, header modification rules, etc.

Expression format

CODEBLOCK6

Max nesting depth: 2 levels.

Operator syntax - two styles

Infix style (operator between field and value):
CODEBLOCK7

Function style (operator wraps field):
CODEBLOCK8

Common patterns

CODEBLOCK9

Key Gotchas

1. 1. ends_with and starts_with must use function-call syntax, NOT infix.
2. INLINECODE184 (regex) requires standard plan or above; basic plan returns RuleRegexQuotaCheckFailed.
3. INLINECODE186 with URI must include path separator: "/test" is correct; "test" alone causes CompileRuleError.
4. List values in in operator are space-separated inside braces: {"a.com" "b.com"}.
5. Outer parentheses are optional for single conditions.
6. Use ne for "not equal", never use not...eq.
7. Use not...in for negating set membership (not before field), not not in.

Plan Limitations

AccessKey priority (must follow, align with README)

1) Environment variables: ALICLOUD_ACCESS_KEY_ID / ALICLOUD_ACCESS_KEY_SECRET / ALICLOUD_REGION_ID
Region policy: ALICLOUD_REGION_ID is an optional default. If unset, decide the most reasonable region for the task; if unclear, ask the user.
2) Shared config file: ~/.alibabacloud/credentials (region still from env)

Auth setup (README-aligned)

Environment variables:

CODEBLOCK10

Also supported by the Alibaba Cloud SDKs:

CODEBLOCK11

Shared config file:

INLINECODE201

CODEBLOCK12

API discovery

• - Product code: INLINECODE202
• Default API version: INLINECODE203
• Metadata endpoint: INLINECODE204
• Use OpenAPI metadata endpoints to list APIs and get schemas (see references).

Output policy

If you need to save responses or generated artifacts, write them under:
INLINECODE205

References

Pages, ER & KV

• - Pages Deployment Reference: INLINECODE206
• Edge Routine Reference: INLINECODE207
• Edge KV Storage Reference: INLINECODE208

Site Management

• - API overview: INLINECODE209
• Endpoints: INLINECODE210
• Sites: INLINECODE211
• DNS records: INLINECODE212
• Cache: INLINECODE213
• Sources: INLINECODE214
• Rule expression - generation guide: INLINECODE215
• Rule expression - match fields: INLINECODE216
• Rule expression - operators: INLINECODE217
• Rule expression - examples: INLINECODE218

Analytics

• - Time-Series Data API: INLINECODE219
• Top-N Data API: INLINECODE220
• Metrics and Dimensions Reference: INLINECODE221