Create Cache Control V2

This API is used to create a cache control policy for the website acceleration service.

Request

Request-Line

POST /cdn/v1.1/services/{serviceId}/cacheControl HTTP/1.1

Request Parameters

Path Parameters

Parameter	Type	Required	Description
serviceId	Integer	Mandatory	The unique identifier for the service for which the cache control policy will be created.

Body Parameters

Parameter	Type	Required	Description
policyName	String	Mandatory	Policy name for the cache control configuration.
priority	Integer	Mandatory	Priority weight for the rule. Rules with a higher weight take precedence. The weight must be a positive integer (greater than zero).
matches	Array	Mandatory	Matching configuration that determines which requests the rule applies to. See Matches for details.
ttl	Long	Optional	Cache TTL (time-to-live) in seconds for content stored on the edge servers.
refererAcl	Object	Optional	Access control based on the Referer header. Defines a domain list and an allow/deny policy to control which referer domains can access the resource. See Referer Acl for details.
originAcl	Object	Optional	Access control based on the requesting origin. Defines a domain list and an allow/deny policy to control which referer domains can access the resource. See Origin Acl for details.
ignoreClientNoCache	Boolean	Optional	When true, ignores no-cache headers sent by the client. Default is false.
ignoreOriginNoCache	Boolean	Optional	When true, ignores no-cache headers sent by the origin server. Default is false.
ignoreQueryString	Boolean	Optional	When true, ignores URL query strings when caching content. Default is false.
enableXCache	Boolean	Optional	When enabled, responses from edge servers include an X-Cache header indicating whether the response was served from cache (e.g., HIT or MISS). Default is false.
noCache	Boolean	Optional	When true, content is not cached even if the origin indicates it is cacheable. Default is false.
autoGzipDisable	Boolean	Mandatory	Disable automatic Gzip compression on the CDN edge. Default is false.
responseHeaders	Array	Optional	List of response header configurations. See Response Headers for details.
varyMIMEs	Array	Optional	Enables the "vary for images" feature. A list of MIME types (e.g., image/webp, image/jpeg) that should be preferred for objects matched by this policy.
enabled	Boolean	Optional	Whether the policy is active. Default is true.

Object: Matches

Parameter	Type	Required	Description
	Array	Mandatory	See Match for details.

Object: Match

Parameter	Type	Required	Description
field	String	Mandatory	Which part of the request to match. Supported values: • req.path - Request path (excluding query string). • req.query - Request query parameters. • req.method - HTTP method (GET, POST, etc.). • client.ip - Client IP address. • req.host - Request host. • req.header.user-agent - User-Agent header. • req.header.cookie - Cookie header. • req.header.origin - Origin header. • req.header.via - Via header.
operator	String	Mandatory	Defines how to match the field. Supported values: • startswith - Succeeds if the what matches one of the prefixes listed in patterns. • not_startswith - Matches if field value does not starts with any of the specified prefixes. • istartswith - Case-independent version of startswith. • not_istartswith - Matches if the field value does not starts with any of the specified prefixes, ignoring letter case differences. • regex - Succeeds if what matches one of the regexes listed in patterns. • equals - Succeeds if the what matches one of the strings listed in patterns. • not_equals - Succeeds if the field value does not exactly match any of the specified strings. • iequals - Case-independent version of equals. • not_iequals - Succeeds if the field value does not exactly match any of the specified strings,ignoring letter case differences. • endswith - Succeeds if the what ends with one of the strings listed in patterns. Useful e.g. to match file extensions like ".mp4". • not_endswith - Succeeds if the what does not ends with one of the strings listed in patterns. • iendswith - Case-independent version of endswith. • not_iendswith - Succeeds if the what does not ends with one of the strings listed in patterns,ignoring letter case differences. • subnet - Succeeds if the what belongs to one of subnets, specified in patterns, like "1.222.94.98/32". • not_subnet - Succeeds if the what does not belongs to one of subnets. Note: subnet operator is applicable only to the client.ip match option.
values	Array	Mandatory	List of values matching the URL path string.

Object: Referer/Origin Acl

Parameter	Type	Required	Description
aclType	String	Mandatory	Access control type. Support values: whitelist or blacklist.
domainList	Array	Mandatory	List of domain names to be allowed or blocked.

Object: Response Headers

Parameter	Type	Required	Description
name	String	Mandatory	Response header name.
operationType	String	Mandatory	Operation to perform on the response header. Supported values: add, replace or delete.
value	String	Optional	Response header value. Required when operationType is add or replace.

Response

Response Body

Parameter	Type	Description
policyId	Integer	Policy ID number for cache control.
policyName	String	Policy name for the cache control configuration.
priority	Integer	Priority weight for the rule. Rules with a higher weight take precedence. The weight must be a positive integer (greater than zero).
matches	Array	Matching configuration that determines which requests the rule applies to. See Matches for details.
ttl	Long	Cache TTL (time-to-live) in seconds for content stored on the edge servers.
refererAcl	Object	Access control based on the Referer header. Defines a domain list and an allow/deny policy to control which referer domains can access the resource. See Referer Acl for details.
originAcl	Object	Access control based on the requesting origin. Defines a domain list and an allow/deny policy to control which referer domains can access the resource. See Origin Acl for details.
ignoreClientNoCache	Boolean	When true, ignores no-cache headers sent by the client. Default is false.
ignoreOriginNoCache	Boolean	When true, ignores no-cache headers sent by the origin server. Default is false.
ignoreQueryString	Boolean	When true, ignores URL query strings when caching content. Default is false.
enableXCache	Boolean	When enabled, responses from edge servers include an X-Cache header indicating whether the response was served from cache (e.g., HIT or MISS). Default is false.
noCache	Boolean	When true, content is not cached even if the origin indicates it is cacheable. Default is false.
autoGzipDisable	Boolean	Disable automatic Gzip compression on the CDN edge. Default is false.
responseHeaders	Array	List of response header configurations. See Response Headers for details.
varyMIMEs	Array	Enables the "vary for images" feature. A list of MIME types (e.g., image/webp, image/jpeg) that should be preferred for objects matched by this policy.
enabled	Boolean	Whether the policy is active. Default is true.

Status Codes, Error Codes and Error Messages

Status Code	Error Code	Error Message
400	Request.BadRequest	Bad request.
400	InvalidCustomer.IdEmpty	Customer ID cannot be empty or invalid.
400	InvalidService.IdIncorrect	Service ID is empty or invalid.
400	InvalidService.IdPermission	Service ID cannot be found or unknown.
400	Invalid.PolicyName	Policy name is required.
400	InvalidPolicy.MatchURLIncorrect	The matchUrlPath cannot be empty.
400	InvalidPolicy.Operator	Operator must be one of the following values: prefix, regex, equals or suffix.
400	InvalidPolicy.Patterns	Patterns cannot be empty or invalid.
400	InvalidPolicy.RefererAcl	Invalid AclType. must be whitelist or blacklist.
400	InvalidPolicy.AclDomainList	DomainList cannot be empty and must not contain empty values.
400	InvalidPolicy.AclDomainType	DomainList elements cannot start with '-'.
400	InvalidPolicy.Priority	Priority is required and must be a positive integer.
400	InvalidService.VaryMiME	The varyMIMEs field cannot be an empty array or contain empty values.
400	InvalidPolicy.ResponseHeader	ResponseHeaders cannot be empty or invalid.
400	InvalidPolicy.MatchesIncorrect	The matches cannot be empty or incorrect.
400	InvalidPolicy.MatchFieldIncorrect	The match field cannot be empty, or use the specified value.
400	InvalidPolicy.MatchOperatorIncorrect	The match operator is required, or use the specified value.
400	InvalidPolicy.MatchValuesIncorrect	The match values are required, or cannot be empty.
400	InvalidPolicy.MatchValueIncorrect	All match values must not be empty.

Examples

Create Cache Control V2

Request

POST /cdn/v1.1/services/229033/cacheControl HTTP/1.1

{   "priority":5,
    "policyName":"cacheInfo",
    "matches":[
        {
            "field":"req.path",
            "operator":"startswith",
            "values":["/css/","/images/abc/"]
        },
        {
            "field":"req.host",
            "operator":"iequals",
            "values":["example.com"]
        },
        {
            "field":"req.method",
            "operator":"equals",
            "values":["get"]
        }
    ],
    "ignoreClientNoCache":false,
    "ignoreOriginNoCache":false,
    "ignoreQueryString":true,
    "enableXCache":true,
    "noCache":false,
    "autoGzipDisable":false,
    "responseHeaders":[{
      "name": "Content-Type",
      "operationType": "add",
      "value": "application/json"
    }]
}

Successful Response Body

{
    "policyId": 262285,
    "policyName": "cacheInfo",
    "ttl": 0,
    "originAcl": {
        "aclType": "",
        "domainList": []
    },
    "ignoreClientNoCache": false,
    "ignoreOriginNoCache": false,
    "ignoreQueryString": true,
    "enableXCache": true,
    "noCache": false,
    "autoGzipDisable": false,
    "responseHeaders": [
        {
            "name": "Content-Type",
            "value": "application/json",
            "operationType": "Add"
        }
    ],
    "matches": [
        {
            "field": "req.path",
            "operator": "startswith",
            "values": [
                "/css/",
                "/images/abc/"
            ]
        },
        {
            "field": "req.host",
            "operator": "iequals",
            "values": [
                "example.com"
            ]
        },
        {
            "field": "req.method",
            "operator": "equals",
            "values": [
                "get"
            ]
        }
    ],
    "varyMIMEs": [],
    "priority": 5,
    "enabled": true
}