Customize HTTP request headers in origin requests using rules-Edge Security Acceleration(ESA)-阿里云帮助中心

How it works

When a client request results in a cache miss, the ESA POP forwards an origin request to your server. You can customize the HTTP headers in that origin request:

Notes

When rules take effect: Rules apply only to origin fetches (cache misses). Requests served from the ESA cache are not affected.
Execution order: Operations within a rule execute top to bottom. When multiple operations target the same header, the last one takes effect. For example, if the client request contains test:123 and the rule first adds test:321 then deletes test, the test header is removed from the origin request.

Procedure

When a request arrives, ESA executes matching rules based on the rule execution priority.

In the ESA console, choose Websites, and click the target site in the Website column.
In the navigation pane on the left, choose Rules > Transform Rules.
Click the Modify request header tab, select the ESA to Origin item, and click Create Rule.

In the Add Request Header Modification Rule area, configure the following parameters:

Parameter	Description
Rule Name	A custom name for the rule.
If requests match...	All Requests: applies to all requests for the current site. Filtered Requests: applies only to traffic matching a custom expression.
Modify Request Header	The operation, type, and header details. See Operations and Restrictions.

Operations

Operation	Type	Behavior	Example
Add	Static	Adds the header to the origin request. If a header with the same name exists, the new value overwrites it.	Request Header Name: `x-code`	Request Header Value: `key1`
Add	Dynamic	Adds a header with a value computed from an expression.	Request Header Name: `True-Client-IP`	Request Header Value: `ip.src`
Change	Static	Changes the value of an existing header. Applies only if a header with the specified name exists in the original request.	Request Header Name: `x-code`	Request Header Value: `key2`
Change	Dynamic	Changes the value of an existing header using an expression. Applies only if a header with the specified name exists in the original request.	Request Header Name: `True-Client-IP`	Request Header Value: `ip.src`
Delete	N/A	Deletes all headers matching the specified Request Header Name, regardless of duplicates.	Request Header Name: `x-code`

Restrictions

Do not use a Request Header Name that starts with ali- or Ali-.
To specify multiple values for Request Header Value, separate them with a comma (,).
The Delete operation works the same way for both Static and Dynamic types.
The Change operation applies only if a header with the specified name already exists in the original request.
Within a single rule, operations execute sequentially. If different operations target the same header name, the last operation overwrites the previous ones.

Examples

Complete Steps 1–3 in Procedure to open the Add Request Header Modification Rule area.

Add the client originating IP address to all requests

Configure these parameters:

Rule Name: add-client-ip-out
If requests match...: Select All Requests.
Modify Request Header:
- Type: Dynamic
- Operation: Add
- Request Header Name: True-Client-IP-OUT
- Request Header Value: ip.src

Verification

Before: The request header does not include the client IP address.

After: The true-client-ip-out header with the client IP address is added.

Add the country code for requests outside China (Hong Kong)

Configure these parameters:

Rule Name: add-client-country
If requests match...: Select Filtered Requests and enter Country/Region does not equal China (Hong Kong). You can also edit the expression directly: (ip.geoip.country ne "HK")
Modify Request Header:
- Type: Dynamic
- Operation: Add
- Request Header Name: IP-Country-Code
- Request Header Value: ip.geoip.country

Verification

Before: The request header does not include the country code for the client IP address.

After: The ip-country-code header with the client country code is added.

Add the province code for a specific URI path

Configure these parameters:

Rule Name: add-client-province
If requests match...: Select Filtered Requests and enter URI Path equals /content. You can also edit the expression directly: (http.request.uri.path eq "/content")
Modify Request Header:
- Type: Dynamic
- Operation: Add
- Request Header Name: IP-Province-Code
- Request Header Value: ip.src.subdivision_1_iso_code

Verification

Before: The request header does not include the province code for the client IP address.

After: The ip-province-code header with the client province code is added.

References

How ESA rules take effect covers execution priority, rule behavior, and configuration scope.