Rewrite request URLs by configuring redirect rules-Edge Security Acceleration(ESA)-阿里云帮助中心

How it works

The redirect process:

A client requests a resource.
The ESA POP matches the request against redirect rules. On a match, it returns a redirect status code (e.g., 301 or 302) with the destination URL in the Location response header.
The client follows the Location header and requests the resource from the new URL.

Status codes and scenarios

Status code	Meaning	Method handling	Common scenarios
301	Moved Permanently	GET requests remain unchanged. Other methods may change to GET.	The resource permanently moved to a new URL. Search engines update their indexes.
302	Found	GET requests remain unchanged. Other methods may change to GET.	The resource is temporarily at a different URL. Search engines retain the original link.
303	See Other	GET requests remain unchanged. Other methods are forced to GET, and the request body is discarded.	Redirect after PUT or POST to prevent duplicate submissions on refresh.
307	Temporary Redirect	Method and request body remain unchanged.	Temporary redirect. Prefer over 302 when your site uses non-GET methods.
308	Permanent Redirect	Method and request body remain unchanged.	Permanent redirect that preserves the HTTP method and request body. Use for API migrations or site refactoring requiring method consistency.

Create a redirect rule

ESA evaluates rules in priority order and applies the first match.

In the ESA console, choose Site Management. In the Website column, click the target site.
In the navigation pane on the left, choose Rules > Redirect Rules. Click Create Rule.

On the Add Redirect Rule page, configure the following settings and click OK:

Enter a Rule Name.
In the If requests match... section, define the request conditions to match. For more information, see Components of a rule expression.

URL Redirect:

Single Redirect configuration

Parameter	Type	Description
Redirect Type	Static	Redirect to a fixed URL. For example, set URL to `https://test.example.com/image/1.jpg?test=123`.
Redirect Type	Dynamic	Construct the destination URL dynamically with an expression. For example, to replace the hostname in the request URL while keeping the original path, set Expression to `concat("https://www.example.com", http.request.uri.path)`.
Status Code		The HTTP status code returned for the redirect. Valid values: 301 (default), 302, 303, 307, and 308. For details, see Status codes and scenarios.
Retain Query String		Whether to carry the original request's query string to the destination URL. Disabled by default (the original query string is dropped). When Retain Query String is enabled: If the original request has a query string, it overrides the redirect URL's query string. If the original request has no query string, the redirect URL's query string is preserved. For configuration examples, see Configuration examples.

Configuration examples

Static redirect examples

Scenario 1: Request has no query string, redirect URL has a query string

Request contains query string: No
Configured redirect URL contains query string: Yes
Preserve query string: Enabled or disabled
Sample request URL: http://test.example.com/1.jpg
Configured redirect URL: http://test.example.com/image/1.jpg?test=123
Actual redirect Location: http://test.example.com/image/1.jpg?test=123
Notes: No query string in the original request, so the configured URL's query string is used regardless of the Preserve query string setting.

Scenario 2: Both URLs have query strings, Preserve query string enabled

Request contains query string: Yes
Configured redirect URL contains query string: Yes
Preserve query string: Enabled
Sample request URL: http://test.example.com/1.jpg?test=321
Configured redirect URL: http://test.example.com/image/1.jpg?test=123
Actual redirect Location: http://test.example.com/image/1.jpg?test=321
Notes: With Preserve query string enabled, only the original request's query string is kept; the configured URL's query parameters are discarded.

Scenario 3: Both URLs have query strings, Preserve query string disabled

Request contains query string: Yes
Configured redirect URL contains query string: Yes
Preserve query string: Disabled
Sample request URL: http://test.example.com/1.jpg?test=321
Configured redirect URL: http://test.example.com/image/1.jpg?test=123
Actual redirect Location: http://test.example.com/image/1.jpg?test=123
Notes: With Preserve query string disabled, only the configured URL's query string is kept; the original request's query parameters are discarded.

Scenario 4: Request has a query string, redirect URL does not, Preserve query string enabled

Request contains query string: Yes
Configured redirect URL contains query string: No
Preserve query string: Enabled
Sample request URL: http://test.example.com/1.jpg?test=321
Configured redirect URL: http://test.example.com/image/1.jpg
Actual redirect Location: http://test.example.com/image/1.jpg?test=321
Notes: With Preserve query string enabled, the original query string is appended to the configured URL even if it has no query parameters.

Scenario 5: Request has a query string, redirect URL does not, Preserve query string disabled

Request contains query string: Yes
Configured redirect URL contains query string: No
Preserve query string: Disabled
Sample request URL: http://test.example.com/1.jpg?test=321
Configured redirect URL: http://test.example.com/image/1.jpg
Actual redirect Location: http://test.example.com/image/1.jpg
Notes: With Preserve query string disabled, the original query string is discarded and only the configured URL is returned.

Dynamic redirect examples

Scenario 1: Preserve query string disabled

Preserve query string: Disabled
Sample request URL: https://test.example.com/image/1.jpg?test=123
Expression: concat("https://www.example.com", http.request.uri.path)
Actual redirect Location: https://www.example.com/image/1.jpg
Notes:
- With Preserve query string disabled, the path (/image/1.jpg) is kept and the query string (?test=123) is dropped.
- The expression concatenates hostname and path only; query parameters are not handled.

Scenario 2: Preserve query string enabled

Preserve query string: Enabled
Sample request URL: https://test.example.com/image/1.jpg?test=123
Expression: concat("https://www.example.com", http.request.uri.path)
Actual redirect Location: https://www.example.com/image/1.jpg?test=123
Notes:
- With Preserve query string enabled, the original query string is appended to the generated URL even if the expression does not handle query parameters.
- The expression handles path concatenation only; the system appends the query string per configuration.

Scenario 3: wildcard_replace function, Preserve query string enabled

Preserve query string: Enabled
Sample request URL: https://www.example.com/image-flower-20250816-1.html?src=cdn
Expression: wildcard_replace(http.request.full_uri, "https://www.example.com/image-*", "https://www.example.com/${1}")
Actual redirect Location: https://www.example.com/flower-20250816-1.html?src=cdn
Notes:
- With Preserve query string enabled, the system appends the original query string (e.g., ?src=cdn) to the destination URL.
- The expression handles path rewriting only; the system passes through the query string per configuration.

Scenario 4: wildcard_replace function, Preserve query string disabled

Preserve query string: Disabled
Sample request URL: https://www.example.com/index.html?place=garden&date=20250816
Expression: wildcard_replace(http.request.full_uri, "https://www.example.com/index.html?place=garden&date=*", "https://www.example.com/flower-${1}-1.html")
Actual redirect Location: https://www.example.com/flower-20250816-1.html
Notes:
- With Preserve query string disabled, the destination URL is built entirely from the expression. Original parameters (e.g., place=garden) are used only for matching; * captures the value after date and substitutes it as ${1}.
- The final URL excludes the original query parameters.

Plan support

Feature	Free	Basic	Standard	Advanced	Enterprise
Number of rules	5	10	50	75	125

Request redirects