All Products
Search
Document Center

Edge Security Acceleration:GetCacheRule

Last Updated:Jun 25, 2026

Queries a single cache rule for a specific site.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

  • Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.

  • API: The API that you can call to perform the action.

  • Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.

  • Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.

    • For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.

    • For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.

  • Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.

  • Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

esa:GetCacheRule

get

*Site

acs:esa:{#regionId}:{#accountId}:site/{#SiteId}

None None

Request parameters

Parameter

Type

Required

Description

Example

SiteId

integer

Yes

The site ID. Call the ListSites operation to obtain this ID.

123456****

ConfigId

integer

Yes

The configuration ID. Call the ListCacheRules operation to obtain this ID.

352816096987136

Response elements

Element

Type

Description

Example

object

The response schema.

RequestId

string

The request ID.

36af3fcc-43d0-441c-86b1-428951dc8225

ConfigId

integer

The configuration ID.

352816096987136

ConfigType

string

Whether the response contains a global or rule configuration. Valid values:

  • global: A global configuration.

  • rule: A rule configuration.

global

SiteVersion

integer

The version number of the site configuration. For sites with version management enabled, this value indicates the configuration version. Defaults to 0.

1

Sequence

integer

The rule execution order. Smaller values indicate higher priority.

1

RuleEnable

string

Whether the rule is enabled. Applies only to rule configurations. Valid values:

  • on: Enabled.

  • off: Disabled.

on

Rule

string

The rule content, a conditional expression used to match user requests. Applies only to rule configurations.

  • To match all incoming requests, use true.

  • To match specific requests, use a custom expression, such as (http.host eq "video.example.com").

(http.host eq \"video.example.com\")

RuleName

string

The rule name. Applies only to rule configurations.

rule_example

BypassCache

string

Whether to cache requests or bypass the cache. Valid values:

  • cache_all: Cache all requests.

  • bypass_all: Bypass the cache for all requests.

cache_all

BrowserCacheMode

string

The browser cache mode. Valid values:

  • no_cache: Do not cache content.

  • follow_origin: Follow the origin cache policy.

  • override_origin: Override the origin cache policy.

follow_origin

BrowserCacheTtl

string

The browser cache TTL, in seconds.

300

EdgeCacheMode

string

The edge cache mode. Valid values:

  • follow_origin: Use the origin server's cache policy. If none is provided, the default policy applies.

  • no_cache: Do not cache content.

  • override_origin: Override the origin cache policy.

  • follow_origin_bypass: Use the origin server's cache policy. If none is provided, content is not cached.

  • follow_origin_override: Use the origin server's cache policy. If none is provided, a custom cache TTL applies.

follow_origin

EdgeCacheTtl

string

The edge cache TTL, in seconds.

300

EdgeStatusCodeCacheTtl

string

The status code cache TTL, in seconds.

  • Set the cache TTL for a specific status code. For example, 404=10 specifies that responses with a 404 status code are cached for 10 seconds.

  • Set the cache TTL for status code classes, such as 4xx and 5xx. For example, 4xx=10 specifies that all responses with a 4xx status code are cached for 10 seconds.

  • Separate multiple entries with commas.

5xx=0,404=10

SortQueryStringForCache

string

Whether to sort query strings before generating the cache key. Valid values:

  • on: Enabled.

  • off: Disabled.

on

QueryStringMode

string

The query string handling mode for cache key generation. Valid values:

  • ignore_all: Ignore all query strings.

  • exclude_query_string: Exclude specified query strings.

  • reserve_all: Retain all query strings. This is the default value.

  • include_query_string: Include specified query strings.

reserve_all

QueryString

string

The query strings to include in or exclude from the cache key. Separate multiple query strings with spaces.

example

IncludeHeader

string

The headers to include in the cache key. Both header names (case-insensitive) and their values are added to the key. Separate multiple header names with spaces. Header names can contain the following characters:

  • Symbols: ! # $ % & ' * + - . ^ _ | ~

  • Digits: 0-9

  • Letters: lowercase English letters a-z

headername1 headername2

IncludeCookie

string

The cookies to include in the cache key. Both cookie names (case-insensitive) and their values are added to the key. Separate multiple cookie names with spaces. Cookie names can contain the following characters:

  • Symbols: ! # $ % & ' * + - . ^ _ | ~

  • Digits: 0-9

  • Letters: lowercase English letters a-z

cookiename1 cookiename2

CacheReserveEligibility

string

The cache reserve eligibility. Controls whether a request bypasses the cache reserve node during an origin fetch. Valid values:

  • bypass_cache_reserve: Bypass the cache reserve.

  • eligible_for_cache_reserve: Eligible for cache reserve.

bypass_cache_reserve

CheckPresenceHeader

string

The headers whose presence is checked when generating a cache key. If a specified header exists in the request, its name (case-insensitive) is added to the cache key. Separate multiple header names with spaces. Header names can contain the following characters:

  • Symbols: ! # $ % & ' * + - . ^ _ | ~

  • Digits: 0-9

  • Letters: lowercase English letters a-z

headername1 headername2

CheckPresenceCookie

string

The cookies whose presence is checked when generating a cache key. If a specified cookie exists in the request, its name (case-insensitive) is added to the cache key. Separate multiple cookie names with spaces. Cookie names can contain the following characters:

  • Symbols: ! # $ % & ' * + - . ^ _ | ~

  • Digits: 0-9

  • Letters: lowercase English letters a-z

cookiename1 cookiename2

UserDeviceType

string

Whether to include the client's device type in the cache key. Valid values:

  • on: Enabled.

  • off: Disabled.

on

UserGeo

string

Whether to include the client's geographic location in the cache key. Valid values:

  • on: Enabled.

  • off: Disabled.

on

UserLanguage

string

Whether to include the client's language in the cache key. Valid values:

  • on: Enabled.

  • off: Disabled.

on

ServeStale

string

Whether to serve stale content. When enabled, edge nodes serve stale (expired) cached content when the origin server is unavailable. Valid values:

  • on: Enabled.

  • off: Disabled.

on

AdditionalCacheablePorts

string

  • Additional ports on which caching is enabled.

  • Valid values: 8880, 2052, 2082, 2086, 2095, 2053, 2083, 2087, 2096.

  • Separate multiple ports with commas.

8880,2052,2086

CacheDeceptionArmor

string

Whether to enable Cache Deception Armor, which helps mitigate web cache deception attacks by ensuring that only validated content is cached. Valid values:

  • on: Enabled.

  • off: Disabled.

on

PostCache

string

Whether to enable POST request caching.

on

PostBodyCacheKey

string

The body content handling mode for POST request cache key generation. Valid values:

  • md5: Calculate the MD5 hash of the body content and add the hash to the cache key.

  • ignore: Ignore the body content in the cache key.

ignore

PostBodySizeLimit

string

The size limit (in KB) of the body content for POST caching. The value is an integer from 1 to 8. A null or empty value defaults to 8 KB.

1

Examples

Success response

JSON format

{
  "RequestId": "36af3fcc-43d0-441c-86b1-428951dc8225",
  "ConfigId": 352816096987136,
  "ConfigType": "global",
  "SiteVersion": 1,
  "Sequence": 1,
  "RuleEnable": "on",
  "Rule": "(http.host eq \\\"video.example.com\\\")\n",
  "RuleName": "rule_example\n",
  "BypassCache": "cache_all",
  "BrowserCacheMode": "follow_origin",
  "BrowserCacheTtl": "300",
  "EdgeCacheMode": "follow_origin",
  "EdgeCacheTtl": "300",
  "EdgeStatusCodeCacheTtl": "5xx=0,404=10",
  "SortQueryStringForCache": "on",
  "QueryStringMode": "reserve_all",
  "QueryString": "example",
  "IncludeHeader": "headername1 headername2",
  "IncludeCookie": "cookiename1 cookiename2",
  "CacheReserveEligibility": "bypass_cache_reserve",
  "CheckPresenceHeader": "headername1 headername2",
  "CheckPresenceCookie": "cookiename1 cookiename2",
  "UserDeviceType": "on",
  "UserGeo": "on",
  "UserLanguage": "on",
  "ServeStale": "on",
  "AdditionalCacheablePorts": "8880,2052,2086",
  "CacheDeceptionArmor": "on",
  "PostCache": "on",
  "PostBodyCacheKey": "ignore",
  "PostBodySizeLimit": "1"
}

Error codes

HTTP status code

Error code

Error message

Description

400 InternalException Failed to call the service. Try again later or contact technical support. Failed to call the service. Try again later or contact technical support.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.