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

SDK quickstart

from alibabacloud_esa20240910.client import Client as Esa20240910Client
from alibabacloud_esa20240910 import models as esa_models
from alibabacloud_tea_openapi import models as open_api_models


def create_client(region_id: str = "cn-hangzhou") -> Esa20240910Client:
    config = open_api_models.Config(
        region_id=region_id,
        endpoint="esa.cn-hangzhou.aliyuncs.com",
    )
    return Esa20240910Client(config)

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

CreateRoutine → GetRoutineStagingCodeUploadInfo → Upload code to OSS
→ CommitRoutineStagingCode → PublishRoutineCodeVersion(staging)
→ PublishRoutineCodeVersion(production) → GetRoutine(get access URL)

Static Directory Deployment Flow

CreateRoutine → CreateRoutineWithAssetsCodeVersion → Package zip and upload to OSS
→ Poll GetRoutineCodeVersionInfo(wait for available)
→ CreateRoutineCodeDeployment(staging) → CreateRoutineCodeDeployment(production)
→ GetRoutine(get access URL)

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

• JS_ONLY: routine/index.js (bundled with esbuild or --no-bundle to read source files directly)
• ASSETS_ONLY: All static files under assets/, maintaining original directory structure
• JS_AND_ASSETS: 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

Bind Custom Domain (CNAME-Access Sites)

For CNAME-access sites, binding a custom domain to a Pages/ER routine requires:

1. CreateRecord(A/AAAA, proxied=true)     → Register domain in ESA CDN
2. CreateRoutineRoute(rule expression)     → Route traffic to Edge Routine
3. External DNS: CNAME → record_cname      → Point domain to ESA CDN
4. ApplyCertificate(lets_encrypt)          → Provision SSL certificate

Critical: Do NOT use CreateRoutineRelatedRecord for CNAME-access sites — it doesn't create a visible DNS record, causing CDN to fall back to origin. Use A/AAAA record + Route instead.

SDK note: CreateRoutineRoute parameter is rule (ESA rule expression like (http.host eq "domain")), NOT route.

Detailed reference: references/pages.md (section: Bind Custom Domain)

Edge Routine (ER) — Edge Functions

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

Core Workflow

CreateRoutine → GetRoutineStagingCodeUploadInfo → Upload code to OSS
→ CommitRoutineStagingCode → PublishRoutineCodeVersion
→ (CreateRoutineRoute) → GetRoutine

API Summary

• Function Management: CreateRoutine, DeleteRoutine, GetRoutine, GetRoutineUserInfo, ListUserRoutines
• Code Version: GetRoutineStagingCodeUploadInfo, CommitRoutineStagingCode, PublishRoutineCodeVersion, DeleteRoutineCodeVersion
• Routes: CreateRoutineRoute, UpdateRoutineRoute, DeleteRoutineRoute, GetRoutineRoute, ListRoutineRoutes, ListSiteRoutes
• Related Records: CreateRoutineRelatedRecord, DeleteRoutineRelatedRecord, ListRoutineRelatedRecords

ER Code Format

export default {
  async fetch(request) {
    return new Response("Hello", {
      headers: { "content-type": "text/html;charset=UTF-8" },
    });
  },
};

Detailed reference: references/er.md

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, DescribeKvAccountStatus
• Single Key Operations: PutKv, GetKv, GetKvDetail, DeleteKv, PutKvWithHighCapacity
• Batch Operations: BatchPutKv, BatchDeleteKv, BatchPutKvWithHighCapacity, BatchDeleteKvWithHighCapacity, ListKvs

Quick Start

client = create_client()

# Create namespace
client.create_kv_namespace(esa_models.CreateKvNamespaceRequest(namespace="my-ns"))

# Write
client.put_kv(esa_models.PutKvRequest(namespace="my-ns", key="k1", value="v1"))

# Read
resp = client.get_kv(esa_models.GetKvRequest(namespace="my-ns", key="k1"))

Detailed reference: references/kv.md

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.
• ListSites 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.
• UpdateSiteAccessType 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.
• CreateCacheRule 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: scripts/list_sites.py
• Summarize sites by plan: scripts/summary_sites_by_plan.py
• Check site status: scripts/check_site_status.py
• List DNS records for a site: scripts/list_dns_records.py

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, 150

Available Metrics (FieldName)

Available Dimensions

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

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

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

Response/Cache: EdgeCacheStatus, EdgeResponseStatusCode, EdgeResponseContentType, OriginResponseStatusCode

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

Error Handling

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

Origin Rules — CDN 代理回源

Origin Rules 控制 ESA CDN 如何回源到源站。当需要将子域名通过 ESA CDN 代理到后端服务器时使用。

CDN 代理回源工作流

CreateRecord(A, proxied=true) → ApplyCertificate → CreateOriginRule → 验证

API Summary

• Origin Rule 管理: CreateOriginRule, ListOriginRules, GetOriginRule, UpdateOriginRule, DeleteOriginRule

Key Parameters

Critical Gotchas

1. dns_record 必须是 ESA DNS 记录名（如 agent.example.com），不能用原始 IP（如 1.2.3.4），否则报 destination_not_found。
2. origin_scheme 默认 HTTPS：源站只监听 HTTP 时必须显式设为 http，否则 502。
3. DNS 记录必须 proxied=true：否则流量不经 CDN，Origin Rule 不生效。
4. Edge Routine Route 优先级高于 Origin Rule：同域名有 ER route 时会拦截请求，需先删除 route。

Detailed reference: references/origin-rules.md

Common operation mapping

Site Management

• Create site: CreateSite
• List sites: ListSites (supports SiteName, Status, AccessType, Coverage filters)
• Get site details: GetSite
• Delete site: DeleteSite
• Check site name availability: CheckSiteName
• Verify site ownership: VerifySite
• Update access type: UpdateSiteAccessType
• Update coverage: UpdateSiteCoverage
• Get current nameservers: GetSiteCurrentNS
• Update custom nameservers: UpdateSiteVanityNS
• Pause/resume site: UpdateSitePause, GetSitePause
• Site exclusivity: UpdateSiteNameExclusive, GetSiteNameExclusive
• Version management: ActivateVersionManagement, DeactivateVersionManagement

Site Configuration

• IPv6: GetIPv6, UpdateIPv6

DNS Records

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

• Create record: CreateRecord
• List records: ListRecords (supports Type, RecordName, Proxied filters)
• Get record: GetRecord
• Update record: UpdateRecord
• Delete record: DeleteRecord
• Batch create: BatchCreateRecords
• Export records: ExportRecords

Cache Rules

• Create cache rule: CreateCacheRule
• List cache rules: ListCacheRules
• Get cache rule: GetCacheRule
• Update cache rule: UpdateCacheRule
• Delete cache rule: DeleteCacheRule

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
• CreateWafRule / UpdateWafRule - WAF custom rules
• CreateRatePlanRule - Rate limiting rules
• CreateRewriteUrlRule / UpdateRewriteUrlRule - URL rewrite rules
• Origin rules, redirect rules, header modification rules, etc.

Expression format

(condition)
(condition1 and condition2)
(condition1) or (condition2)

Max nesting depth: 2 levels.

Operator syntax - two styles

Infix style (operator between field and value):

(field eq "value")
(field ne "value")
(field contains "value")
(field in {"value1" "value2"})
(field matches "regex")

Function style (operator wraps field):

(starts_with(field, "value"))
(ends_with(field, "value"))
(exists(field))
(len(field) gt 100)
(lower(field) eq "value")

Common patterns

# Match file extension
--Rule '(http.request.uri.path.extension eq "html")'

# Match multiple extensions
--Rule '(http.request.uri.path.extension in {"js" "css" "png" "jpg"})'

# Match URL prefix
--Rule '(starts_with(http.request.uri, "/api/"))'

# Match URL suffix
--Rule '(ends_with(http.request.uri, ".html"))'

# Match URL containing substring (value MUST start with /)
--Rule '(http.request.uri contains "/test")'

# Match specific host
--Rule '(http.host eq "www.example.com")'

# Combined conditions
--Rule '(http.request.uri contains "/test" and ip.geoip.country eq "CN")'

# Match by country
--Rule '(ip.geoip.country eq "CN")'

# Exclude path
--Rule '(not starts_with(http.request.uri, "/admin/"))'

# Negating set membership
--Rule '(not http.host in {"a.com" "b.com"})'

Key Gotchas

1. ends_with and starts_with must use function-call syntax, NOT infix.
2. matches (regex) requires standard plan or above; basic plan returns RuleRegexQuotaCheckFailed.
3. contains 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: ALIBABACLOUD_ACCESS_KEY_ID / ALIBABACLOUD_ACCESS_KEY_SECRET / ALIBABACLOUD_REGION_ID Region policy: ALIBABACLOUD_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:

export ALIBABACLOUD_ACCESS_KEY_ID="your-ak"
export ALIBABACLOUD_ACCESS_KEY_SECRET="your-sk"
export ALIBABACLOUD_REGION_ID="cn-hangzhou"

Also supported by the Alibaba Cloud SDKs:

export ALIBABA_CLOUD_ACCESS_KEY_ID="your-ak"
export ALIBABA_CLOUD_ACCESS_KEY_SECRET="your-sk"

Legacy compatibility:

export ALICLOUD_ACCESS_KEY_ID="your-ak"
export ALICLOUD_ACCESS_KEY_SECRET="your-sk"

Shared config file:

~/.alibabacloud/credentials

[default]
type = access_key
access_key_id = your-ak
access_key_secret = your-sk

API discovery

• Product code: ESA
• Default API version: 2024-09-10
• Metadata endpoint: https://api.aliyun.com/meta/v1/products/ESA/versions/2024-09-10/api-docs.json
• 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: output/aliyun-esa-manage/

References

Pages, ER & KV

• Pages Deployment Reference: references/pages.md
• Edge Routine Reference: references/er.md
• Edge KV Storage Reference: references/kv.md

Origin Rules

• Origin Rule configuration & troubleshooting: references/origin-rules.md

Site Management

• API overview: references/api_overview.md
• Endpoints: references/endpoints.md
• Sites: references/sites.md
• DNS records: references/dns-records.md
• Cache: references/cache.md
• Sources: references/sources.md
• Rule expression - generation guide: references/rule-generation-guide.md
• Rule expression - match fields: references/rule-match-fields.md
• Rule expression - operators: references/rule-operators.md
• Rule expression - examples: references/rule-examples.md

Analytics

• Time-Series Data API: references/time-series.md
• Top-N Data API: references/top-data.md
• Metrics and Dimensions Reference: references/fields.md