When you enable parameter ignoring, CDN edge nodes remove query parameters (the part after the ?) from request URLs. This allows requests with different parameters to hit the same cached copy, improving the cache hit ratio. This topic describes how to configure parameter ignoring, compares it with alternative features, and provides troubleshooting guidance for common issues.
Feature Comparison and Selection
Custom Cache Key conflicts with parameter ignoring. When parameter ignoring is enabled, edge nodes strip all parameters after
?in the URL, which invalidates any request parameter settings in your Custom Cache Key configuration. Disable parameter ignoring before using Custom Cache Key.Custom Cache Key can replace parameter ignoring for cache key configuration and offers more comprehensive functionality. We recommend using it first. Configuration comparison:
Scenario
Parameter Ignoring Configuration
Custom Cache Key Configuration
Ignore all request parameters in the cache key
Set Ignore Parameters to Yes and leave Retain Specified Parameters empty.
Add a request parameter handling rule:
Action: Retain
Parameter name: Set to any non-existent parameter name, such as example-argument.
Retain only request parameter key1 in the cache key
Set Ignore Parameters to Yes and set Retain Specified Parameters to
key1.Add a request parameter handling rule:
Action: Retain
Parameter name: key1
Delete only request parameter key1 from the cache key
Delete the parameter setting for
key1.Add a request parameter handling rule:
Action: Delete
Parameter name: key1
Rewrite Origin Parameters can replace parameter ignoring for origin request rewriting and offers more comprehensive functionality. We recommend using it first.
Feature Overview
Ignore Parameters
Function | Scenarios |
Removes query parameters (the part after | Enable parameter ignoring when URL parameters are unrelated to resource content (such as user UID, referral source, or promo codes). For example, these two requests access the same resource but carry different UIDs: User A: User B: Without parameter ignoring, CDN edge nodes treat these as different resources and cannot share the same cache, requiring an origin fetch for each request. With parameter ignoring enabled, CDN edge nodes strip the parameters and use |
URL signing takes precedence over parameter ignoring. Type A signing includes URL parameters in its signature. CDN performs authentication first and caches the replica only after successful validation.
Retain Origin Parameters
Function | Scenarios |
Retains all original URL parameters during origin fetches to ensure the origin server receives critical user information. | When parameter ignoring is enabled, CDN edge nodes use the parameter-stripped URL for origin fetches by default. In the example above, both User A and User B would trigger an origin request to |
Procedure
Log on to the CDN console.
In the navigation pane on the left, click Domain Names.
In the domain list, click the target domain name. In the navigation pane on the left, click Optimization to go to the performance optimization configuration page.
Click Modify in the Ignore Parameters section. Select a mode and complete the configuration based on your needs.
After completing the configuration, click OK to save.
Switching modes clears existing configurations.
After modifying the parameter ignoring configuration, cached files on edge nodes do not update automatically. You must perform a URL refresh or directory refresh in the console to apply the new configuration and purge old cache. Otherwise, users might still access content cached under the old policy, causing access issues.
Mode: Retain Specified Parameters
Parameter | Description | Example |
Ignore Parameters |
| Assume the original URL is
|
Retain Specified Parameters | Enter parameter names to retain. You can specify up to 10 parameters, separated by commas (,). | |
Retain Origin Parameters |
| |
Rule Condition | A rule condition allows a rule to be applied only when a request meets specific criteria. Important
When a feature references rule conditions, the execution order follows the priority of the associated rule conditions, not the order of the feature configurations.
|
Mode: Delete Specified Parameters
Parameter | Description | Example |
Remove Specified Parameters | Enter parameter names to delete. You can specify up to 10 parameters, separated by spaces. | Assume the original URL is
|
Retain Origin Parameters |
| |
Rule Condition | A rule condition allows a rule to be applied only when a request meets specific criteria. Important
When a feature references rule conditions, the execution order follows the priority of the associated rule conditions, not the order of the feature configurations.
|
FAQ
How do I troubleshoot business issues after enabling parameter ignoring?
After enabling parameter ignoring, CDN treats requests with different parameters as the same resource for caching. Do not globally ignore URL parameters if they fall into these categories:
User identity identifiers (such as UID, Token, Session ID): Ignoring them causes authentication failures or data leakage between users.
Dynamic content differentiation (such as version numbers
?v=1or pagination?page=2): Ignoring them returns incorrect cached content.Origin processing instructions (such as OSS image processing parameters
x-oss-process): Ignoring them disables processing and returns unprocessed original resources.
Troubleshooting and resolution:
Delete or disable the Ignore Parameters configuration.
After modifying the configuration, perform a cache purge (URL refresh or directory refresh) to clear old cache from edge nodes.
If some parameters must be retained, use the Retain Specified Parameters mode to preserve critical parameters (such as
x-oss-processortoken).
Why does the parameter ignoring configuration not take effect after modification?
After modifying the parameter ignoring configuration, cached files on edge nodes do not update automatically. If access issues persist or back-to-origin traffic does not decrease, follow these steps:
Confirm the configuration is saved: Log on to the CDN console, revisit the parameter ignoring configuration page, and verify the current settings match your expectations.
Check for conflicts with Custom Cache Key: Parameter ignoring and Custom Cache Key cannot coexist. Enabling parameter ignoring invalidates request parameter settings in Custom Cache Key. Ensure both features are not enabled simultaneously.
Perform a cache purge: The new configuration takes effect immediately, but existing cached files still use the old policy. You must perform a URL refresh or directory refresh on the Refresh and Prefetch Resources page to clear old cache and fully apply the new configuration.
Verify the configuration: Use the command
curl -I "full URL"to check theX-Cachefield in the response header and confirm the cache hit status matches expectations.
How do I configure parameter ignoring when using OSS image processing or video snapshots?
When using OSS image processing (such as x-oss-process=image/resize,w_200) or video snapshot features, enabling parameter ignoring on your CDN domain causes the original resource and processed resource URLs to be cached as the same file, leading to incorrect content delivery.
Solution: In the CDN console parameter ignoring configuration, set the x-oss-process parameter to Retain Specified Parameters mode. This ensures URLs with image processing parameters are cached separately, avoiding conflicts with the original resource cache.
How can I use parameter ignoring to handle requests that bypass cache using URL parameters?
When attackers or crawlers add random meaningless parameters (such as ?timestamp=xxx or ?random=xxx) to request the same resource, CDN treats each parameterized request as a unique resource. This reduces cache hit ratio and spikes back-to-origin traffic.
Enable parameter ignoring (or configure it to ignore all parameters) so requests with different random parameters hit the same cache, effectively reducing origin pressure. For example, after enabling parameter ignoring, these requests hit the same cache:
http://example.com/page.html?t=123456http://example.com/page.html?t=789012http://example.com/page.html?random=abc
With parameter ignoring enabled, all these requests use http://example.com/page.html to match the cache, effectively mitigating cache-bypass attacks via URL parameters.
Why do different clients show inconsistent cache hit status (X-Cache shows MISS) after enabling parameter ignoring?
Possible causes:
URL carries dynamic authentication parameters not ignored: If the URL includes parameters like
auth_keywith different values per request, CDN treats them as different resources even with parameter ignoring enabled (if the auth parameter isn't retained).First access to a node with no cache: The resource hasn't been cached on that specific edge node yet, so the first access always shows MISS.
Differences in client request headers: Variations in headers like
Accept-EncodingorUser-Agentmay trigger multiple cache replicas (for example, separate Gzip and non-Gzip versions).Conflict with Custom Cache Key, causing the configuration to be ineffective.
Troubleshooting method: Run curl -I "full URL" on the client and compare the X-Cache and X-Swift-CacheTime response headers to confirm cache status.
Solution: Verify that parameter ignoring is correctly configured (enabled and critical parameters set to retain) and ensure consistent client request header policies.
How can I control CDN to fetch the latest resources during phased releases or version updates using URL parameters?
If parameter ignoring is enabled, CDN cannot distinguish versions using URL parameters (such as ?v=1 or ?v=2). Use one of these approaches:
Approach 1 (recommended): Use versioned filenames (such as
style.v2.cssorapp.v2.js) instead of relying solely on query parameters to ensure users get the latest content.Approach 2: When releasing a new version, proactively call the CDN refresh API to purge old cache.