Use when managing Alibaba Cloud ESA — deploy HTML/static sites via Pages, manage Edge Routines (ER) for serverless edge functions, use Edge KV for distributed key-value storage, configure Origin Rules for CDN proxy and origin routing, handle site management, DNS records, cache rules, and query traffic analytics via OpenAPI/SDK. Use when working with ESA, edge deployment, edge functions, Pages, ER, KV storage, DNS, cache, origin rules, CDN proxy, site configuration, traffic analytics, bandwidth trends, or top-N rankings.
Category: service
Use Alibaba Cloud OpenAPI (RPC) with official Python SDK to manage all ESA capabilities.
Alibaba Cloud ESA provides five core capabilities:
Use Python SDK uniformly to call ESA OpenAPI.
pip install alibabacloud_esa20240910 alibabacloud_tea_openapi alibabacloud_credentialsfrom 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 is a quick deployment flow based on Edge Routine, deploying HTML or static directories to the edge.
CreateRoutine → GetRoutineStagingCodeUploadInfo → Upload code to OSS
→ CommitRoutineStagingCode → PublishRoutineCodeVersion(staging)
→ PublishRoutineCodeVersion(production) → GetRoutine(get access URL)
CreateRoutine → CreateRoutineWithAssetsCodeVersion → Package zip and upload to OSS
→ Poll GetRoutineCodeVersionInfo(wait for available)
→ CreateRoutineCodeDeployment(staging) → CreateRoutineCodeDeployment(production)
→ GetRoutine(get access URL)
The zip package structure depends on EDGE_ROUTINE_TYPE (automatically determined by checkEdgeRoutineType based on whether entry file and assets directory exist):
routine/index.js (bundled with esbuild or --no-bundle to read source files directly)assets/, maintaining original directory structureroutine/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.
defaultRelatedRecord via GetRoutine as access domainFor 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)
Manage the complete lifecycle of serverless edge functions via Python SDK.
CreateRoutine → GetRoutineStagingCodeUploadInfo → Upload code to OSS
→ CommitRoutineStagingCode → PublishRoutineCodeVersion
→ (CreateRoutineRoute) → GetRoutine
CreateRoutine, DeleteRoutine, GetRoutine, GetRoutineUserInfo, ListUserRoutinesGetRoutineStagingCodeUploadInfo, CommitRoutineStagingCode, PublishRoutineCodeVersion, DeleteRoutineCodeVersionCreateRoutineRoute, UpdateRoutineRoute, DeleteRoutineRoute, GetRoutineRoute, ListRoutineRoutes, ListSiteRoutesCreateRoutineRelatedRecord, DeleteRoutineRelatedRecord, ListRoutineRelatedRecordsexport default {
async fetch(request) {
return new Response("Hello", {
headers: { "content-type": "text/html;charset=UTF-8" },
});
},
};
Detailed reference: references/er.md
Distributed edge key-value storage, readable and writable in Edge Routine, also manageable via OpenAPI/SDK.
Expiration (Unix timestamp) or ExpirationTtl (seconds)CreateKvNamespace, DeleteKvNamespace, GetKvNamespace, GetKvAccount, DescribeKvAccountStatusPutKv, GetKv, GetKvDetail, DeleteKv, PutKvWithHighCapacityBatchPutKv, BatchDeleteKv, BatchPutKvWithHighCapacity, BatchDeleteKvWithHighCapacity, ListKvsclient = 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
Use Python SDK to manage ESA sites, DNS records, cache rules, etc.
PageNumber + PageSize.ListSites returns sites across all regions; no need to iterate regions.pending; complete access verification via VerifySite to activate.UpdateSiteAccessType can switch between CNAME and NS, but switching to CNAME may fail if incompatible DNS records exist.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).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).references/api_overview.md.scripts/ and write outputs under output/aliyun-esa-manage/.scripts/list_sites.pyscripts/summary_sites_by_plan.pyscripts/check_site_status.pyscripts/list_dns_records.pyQuery and analyze ESA site traffic data using DescribeSiteTimeSeriesData and DescribeSiteTopData APIs.
Query traffic trends over time, returning aggregated data points.
Time Granularity Rules:
| Time Range | Interval | Interval Value |
|---|---|---|
| <= 3 hours | 1 minute | 60 |
| 3-12 hours | 5 minutes | 300 |
| 12 hours - 1 day | 15 minutes | 900 |
| 1-10 days | 1 hour | 3600 |
| 10-31 days | 1 day | 86400 |
Query Top-N ranking data by various dimensions.
Limit Options: 5, 10, 150
| Field | Type | Description |
|---|---|---|
Traffic | int | Response traffic from ESA to client (bytes) |
Requests | int | Number of requests |
RequestTraffic | int | Client request traffic (bytes) |
PageView | int | Page views |
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
| HTTP Code | Error Code | Description |
|---|---|---|
| 400 | InvalidParameter.TimeRange | Time range exceeded (max 31 days) |
| 400 | InvalidEndTime.Mismatch | EndTime earlier than StartTime |
| 400 | InvalidParameter.Field | Invalid field name |
| 400 | InvalidParameter.Dimension | Invalid dimension |
| 400 | InvalidTime.Malformed | Time format error (use yyyy-MM-ddTHH:mm:ssZ) |
Detailed reference: references/time-series.md, references/top-data.md, references/fields.md
Origin Rules 控制 ESA CDN 如何回源到源站。当需要将子域名通过 ESA CDN 代理到后端服务器时使用。
CreateRecord(A, proxied=true) → ApplyCertificate → CreateOriginRule → 验证
CreateOriginRule, ListOriginRules, GetOriginRule, UpdateOriginRule, DeleteOriginRule| 参数 | 说明 |
|---|---|
rule | 匹配条件,如 (http.host eq "sub.example.com") |
origin_scheme | 回源协议:http 或 https(默认 https) |
origin_port | 回源端口 |
dns_record | 回源目标 DNS 记录名(必须是 ESA DNS 记录名,不能是 IP) |
dns_record 必须是 ESA DNS 记录名(如 agent.example.com),不能用原始 IP(如 1.2.3.4),否则报 destination_not_found。origin_scheme 默认 HTTPS:源站只监听 HTTP 时必须显式设为 http,否则 502。Detailed reference: references/origin-rules.md
CreateSiteListSites (supports SiteName, Status, AccessType, Coverage filters)GetSiteDeleteSiteCheckSiteNameVerifySiteUpdateSiteAccessTypeUpdateSiteCoverageGetSiteCurrentNSUpdateSiteVanityNSUpdateSitePause, GetSitePauseUpdateSiteNameExclusive, GetSiteNameExclusiveActivateVersionManagement, DeactivateVersionManagementGetIPv6, UpdateIPv6NS access: full record type support. CNAME access: only CNAME and A/AAAA, proxy must stay enabled.
CreateRecordListRecords (supports Type, RecordName, Proxied filters)GetRecordUpdateRecordDeleteRecordBatchCreateRecordsExportRecordsCreateCacheRuleListCacheRulesGetCacheRuleUpdateCacheRuleDeleteCacheRuleCache rule expression notes (important):
CreateCacheRule parameters are flat, not a nested JSON Rule object.Rule parameter is a match condition expression string. See Rule Expression Syntax section below.ends_with()/starts_with() must use function-call style; matches (regex) requires standard plan or above.--EdgeCacheMode override_origin --EdgeCacheTtl <seconds>.ESA uses a unified rule engine expression syntax across multiple features (cache rules, WAF custom rules, rate limiting, URL rewrite, header modification, etc.).
Use this syntax for the Rule parameter in any ESA API that accepts a match condition expression:
CreateCacheRule / UpdateCacheRule - Cache rulesCreateWafRule / UpdateWafRule - WAF custom rulesCreateRatePlanRule - Rate limiting rulesCreateRewriteUrlRule / UpdateRewriteUrlRule - URL rewrite rules(condition)
(condition1 and condition2)
(condition1) or (condition2)
Max nesting depth: 2 levels.
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")
# 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"})'
ends_with and starts_with must use function-call syntax, NOT infix.matches (regex) requires standard plan or above; basic plan returns RuleRegexQuotaCheckFailed.contains with URI must include path separator: "/test" is correct; "test" alone causes CompileRuleError.in operator are space-separated inside braces: {"a.com" "b.com"}.ne for "not equal", never use not...eq.not...in for negating set membership (not before field), not not in.| Plan | eq/ne/in/starts_with/ends_with | contains | matches (regex) |
|---|---|---|---|
| Basic | Supported | Supported | Not supported |
| Standard | Supported | Supported | Supported |
| Enterprise | Supported | Supported | Supported |
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.~/.alibabacloud/credentials (region still from env)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
ESA2024-09-10https://api.aliyun.com/meta/v1/products/ESA/versions/2024-09-10/api-docs.jsonIf you need to save responses or generated artifacts, write them under:
output/aliyun-esa-manage/
references/pages.mdreferences/er.mdreferences/kv.mdreferences/origin-rules.mdreferences/api_overview.mdreferences/endpoints.mdreferences/sites.mdreferences/dns-records.mdreferences/cache.mdreferences/sources.mdreferences/rule-generation-guide.mdreferences/rule-match-fields.mdreferences/rule-operators.mdreferences/rule-examples.mdreferences/time-series.mdreferences/top-data.mdreferences/fields.md