When a resource moves to a new path on your origin server, the original URL on Alibaba Cloud CDN points of presence (POPs) stops working. Create an access URL rewrite rule to redirect clients to the correct destination, reducing unnecessary origin fetch requests and improving response times.
Prerequisites
Before you begin, make sure that you have:
A domain name added to CDN
Access to the CDN console
Create a rewrite rule
Log on to the CDN console.
In the left navigation pane, click Domain Names.
Find the target domain name and click Manage in the Actions column.
In the domain's navigation pane, click Cache.
Click the Access URL Rewrite tab.
Click Create and configure the following parameters.
Parameter
Description
Path to Be Rewritten
The source path to match against incoming requests. The path must start with a forward slash (
/) and cannot include a protocol or domain name. Perl Compatible Regular Expressions (PCRE) are supported. Example:^/hello$.Target Path
The destination path. The format depends on the Flag setting. With Break, the path must start with
/and cannot include a protocol or domain name. With Redirect, the path can include a protocol and domain name, and PCRE capture groups ($1,$2, etc.) are supported for extracting matched segments from the source path.Flag
Controls how the POP processes the rewrite. See Flag behavior for details.
Rule Condition
Restricts when this rule applies based on request attributes. Select Do not use to skip conditions, or manage conditions in the Rules engine.
Enable NGINX variable computing
This option is not shown by default. To enable it, submit a ticket. Once enabled, built-in NGINX variables can be used in Target Path. For example, set Path to Be Rewritten to
^/test.jpg$and Target Path to/test.${arg_type}, where${arg_type}resolves to thetypequery parameter from the original URL.
Click OK.
After the rule is created, it appears in a list where you can Modify or Delete it.
Each domain name supports a maximum of 50 rewrite rules. When multiple rules exist, they run in the order listed on the Rewrite Access URL page in the CDN console.
Flag behavior
Two flags are available by default: Redirect and Break. Three additional flags are available by request. Submit a ticket to enable Empty, enhance_break, and enhance_redirect.
Flag | Rewrite method | Modifies URL parameters | Supports cross-domain or cross-protocol rewrite | Continues to next rule |
Redirect | 302 redirection | No | Yes | Yes |
Break | Direct URL rewrite | No | No | No |
Empty | Direct URL rewrite | — | No | Yes |
enhance_break | Direct URL rewrite | Yes | No | No |
enhance_redirect | 302 redirection | Yes | Yes | — |
"—" indicates a behavior not explicitly documented. Submit a ticket for details about these flags.
Redirect: Returns a
302redirect with the destination URL in theLocationheader. Original URL parameters are preserved. After this rule runs, remaining rules continue to be evaluated.Break: Rewrites the request URL internally without sending a redirect to the client. Original URL parameters are preserved. After this rule runs, remaining rules are skipped.
Empty: If a request URL matches the rule, the request continues to be matched against the subsequent rules after the current rule is executed.
enhance_break: Similar to Break, but modifies the entire URL, including parameters.
enhance_redirect: Similar to Redirect, but modifies the entire URL, including parameters.
Redirect and enhance_redirect use 302 redirection, which supports rewriting to a different domain name (for example, from example.com to aliyundoc.com) and a different protocol (for example, from HTTP to HTTPS). Break, Empty, and enhance_break rewrite the URL directly and do not support cross-domain or cross-protocol changes.
Examples
Redirect to a new path on the same domain
A client requests http://example.aliyundoc.com/hello. The path /hello matches the rule, and the POP returns a 302 redirect with /index.html in the Location header. The client then requests http://example.aliyundoc.com/index.html.
When the Location header contains only a path without a protocol or domain name, the client uses the protocol and domain name from the original request.
Redirect to a different domain and protocol
A client requests http://example.aliyundoc.com/hello. The path matches the regular expression ^/hello$. The POP returns a 302 redirect with https://test.aliyundoc.com/index.html in the Location header. The client follows the redirect to https://test.aliyundoc.com/index.html.
Extract and redirect an embedded URL
A client requests http://www.example.com/cdn/url/http://image.example.com/image/cat.jpg. The path matches ^/cdn/url/http://(.*), and the capture group $1 extracts image.example.com/image/cat.jpg. The POP returns a 302 redirect to http://image.example.com/image/cat.jpg.
How it works
After you create a rewrite rule, CDN POPs respond with a 302 (Found) status code and include the new URL in the Location header. The client follows the redirect and sends a new request to the destination URL.
By default, POPs use the 302 status code. The 303 and 307 status codes are also available. To switch, submit a ticket.
Status code | Meaning | Method handling | When to use |
302 | Found | GET stays unchanged. Other methods may change to GET. | A page is temporarily unavailable. Search engines keep the original link. |
303 | See Other | GET stays unchanged. Other methods change to GET. The message body is dropped. | Redirect after a PUT or POST completes, preventing duplicate submissions on page refresh. |
307 | Temporary Redirect | Method and message body stay unchanged. | A page is temporarily unavailable, and the site uses non-GET methods that must be preserved. Preferred over 302 in this scenario. |
Access URL rewrite flow
A client sends a request to a POP. The request URL is
old.example.com/hello.The POP matches the request against the rewrite rule, generates a
302response, and sets theLocationheader tonew.example.com/hello.The client follows the redirect and sends a new request to
new.example.com/hello.The POP checks its cache. If the content is cached, the POP returns it directly. Otherwise, the POP fetches the content from the origin server using the rewritten URL.
The origin server returns the response.
The POP caches the response and returns it to the client.
Access URL rewrite vs. origin path rewrite
CDN provides two types of URL rewriting. Choose the one that matches your goal:
Dimension | Access URL rewrite | Origin path rewrite |
What changes | The URL the client accesses and the URL the POP uses for origin fetch. | Only the URL the POP uses for origin fetch. The client-facing URL stays the same. |
Client experience | With the Redirect flag, the client follows a redirect to the new URL. With the Break flag, the rewrite is transparent and the client sees the original URL. | Transparent. The client always sees the original URL. |
Typical use case | Migrate URLs from an old domain to a new domain, or serve different URLs for mobile and desktop clients. Example: | Hide the origin server's directory structure, or map CDN paths to different origin directories. Example: a request for |
For origin path rewrite details, see Rewrite origin path.
Origin path rewrite flow
A client sends a request to a POP. The request URL is
cdn.example.com/files/hello.txt.The POP checks its cache. If the content is cached, the POP returns it. Otherwise, the POP rewrites the origin path to
origin.example.com/secret/files/hello.txtbased on the rewrite rule and fetches the content from the origin.The origin server returns the response.
The POP caches the response and returns it to the client.