RefreshObjectCaches - CDN

Refreshes files on Alibaba Cloud CDN points of presence (POPs). After files are refreshed, the original file content immediately becomes invalid. If clients request the original file content, Alibaba Cloud CDN forwards the requests to the origin server. Then, Alibaba Cloud CDN caches the latest content to the POPs and returns the content to the clients. Alibaba Cloud CDN allows you to refresh content from multiple URLs at the same time.

Operation description

Alibaba Cloud CDN supports POST requests in which parameters are sent as a form.
You can call the RefreshObjectCaches operation to refresh content and call the PushObjectCache operation to prefetch content.
You can call the RefreshObjectCaches operation up to 50 times per second per account.
For more information about how to automatically refresh or prefetch tasks, see Run scripts to refresh and prefetch content.

Precautions

After a refresh task is submitted and completed, specific resources are removed from POPs. When a POP receives a request for the removed resources, the POP forwards the request to the origin server to retrieve the resources. The retrieved resources are returned to the client and cached on the POP. Multiple refresh tasks may cause a large number of resources to be removed from the POPs. This increases the number of requests that are forwarded to the origin server. The back-to-origin routing process consumes more bandwidth resources and the origin server may be overwhelmed.
A refresh task takes effect 5 to 6 minutes after being submitted. This means that if the resource you want to refresh has a TTL of less than five minutes, you wait for it to expire instead of manually running a refresh task.
If you want to use RAM users to refresh or prefetch resources, you must obtain the required permissions. For more information, see Authorize a RAM user to prefetch and refresh resources.

Refresh quota

By default, each Alibaba Cloud account can refresh content from up to 10,000 URLs and 100 directories per day. The directories include subdirectories. If the daily peak bandwidth value exceeds 200 Mbit/s, you can submit a ticket to request a quota increase. Alibaba Cloud CDN evaluates your application based on your workloads.
By default, each Alibaba Cloud account can submit up to 20 refresh rules that contain regular expressions per day. If the daily peak bandwidth of your Alibaba Cloud account exceeds 10 Gbit/s, you can submit a ticket to request a quota increase.
You can specify up to 1,000 URL refresh rules, 100 directory refresh rules, or 1 refresh rule that contains regular expressions in each call.
You can refresh up to 1,000 URLs per minute for each domain name.

Debugging

You can run this interface directly in OpenAPI Explorer, saving you the trouble of calculating signatures. After running successfully, OpenAPI Explorer can automatically generate SDK code samples.

Debug

Authorization information

The following table shows the authorization information corresponding to the API. The authorization information can be used in the Action policy element to grant a RAM user or RAM role the permissions to call this API operation. Description:

Operation: the value that you can use in the Action element to specify the operation on a resource.
Access level: the access level of each operation. The levels are read, write, and list.
Resource type: the type of the resource on which you can authorize the RAM user or the RAM role to perform the operation. Take note of the following items:
- The required resource types are displayed in bold characters.
- If the permissions cannot be granted at the resource level, All Resources is used in the Resource type column of the operation.
Condition Key: the condition key that is defined by the cloud service.
Associated operation: other operations that the RAM user or the RAM role must have permissions to perform to complete the operation. To complete the operation, the RAM user or the RAM role must have the permissions to perform the associated operations.

Operation	Access level	Resource type	Condition key	Associated operation
cdn:RefreshObjectCaches	none	Domain acs:cdn:*:{#accountId}:domain/{#DomainName}	none	none

Request parameters

Parameter	Type	Required	Description	Example
ObjectPath	string	Yes	If you submit multiple URLs or directories at a time, separate them with line breaks (\n) or (\r\n). The total number of domain names contained all URLs in a submitted task cannot exceed 10.	http://example.com/image/1.png\nhttp://aliyundoc.com/image/2.png
ObjectType	string	No	The type of the object that you want to refresh. Valid values: File (default): refreshes one or more files. Directory: refreshes the files in one or more directories. Regex: refreshes content based on regular expressions. ExQuery: omits parameters after the question mark in the URL and refreshes content. If you set the ObjectType parameter to File or Directory, you can view Refresh and prefetch resources to obtain more information. If you set the ObjectType parameter to Regex, you can view Configure URL refresh rules that contain regular expressions to obtain more information. If you set the ObjectType parameter to Directory, the resources in the directory that you want to refresh are marked as expired. You cannot delete the directory. If clients request resources on POPs that are marked as expired, Alibaba Cloud CDN checks whether the resources on your origin server are updated. If resources are updated, Alibaba Cloud CDN retrieves the latest version of the resources and returns the resources to the clients. Otherwise, the origin server returns the 304 status code.	File
Force	boolean	No	When the comparison between the source content and the source site resources is consistent, should the resources within the corresponding range be forcibly refreshed. The default is false. true: purges all resources in the range that corresponds to the type of the purge task. If you set this parameter to true, when the requested resource matches the resource in the range that corresponds to the type of the purge task, the POP retrieves the resource from the origin server, returns the resource to the client, and caches the resource. false: purges the changed resources in the range that corresponds to the type of the purge task. If you set this parameter to false, when the requested resource matches the resource in the range that corresponds to the type of the purge task, the POP obtains the Last-Modified parameter of the resource from the origin server. If the obtained value of the Last-Modified parameter is the same as that of the cached resource, the cached resource is returned. Otherwise, the POP retrieves the resource from the origin server, returns the resource to the client, and caches the resource. Note This parameter takes effect only when the ObjectType parameter is not set to File.	false

Response parameters

Parameter	Type	Description	Example
	object
RefreshTaskId	string	The ID of the refresh task. If multiple tasks are returned, the task IDs are separated by commas (,). The task IDs are merged based on the following rules: If the tasks are specified for the same accelerated domain name, submitted within the same second, and run to refresh content based on URLs instead of directories, the task IDs are merged into one task ID (RefreshTaskId). If the number of tasks that are specified for the same accelerated domain name, submitted within the same second, and run to refresh content based on URLs instead of directories exceeds 2,000, every 2,000 task IDs are merged into one task ID (RefreshTaskId).	704222904
RequestId	string	The request ID.	D61E4801-EAFF-4A63-AAE1-FBF6CE1CFD1C

Examples

Sample success responses

JSONformat

{
  "RefreshTaskId": "704222904",
  "RequestId": "D61E4801-EAFF-4A63-AAE1-FBF6CE1CFD1C"
}

Error codes

HTTP status code	Error code	Error message	Description
400	SingleRequest.OverLimit	A maximum of 1000 URLs are supported for each request.	-
400	InvalidObjectType.Malformed	The specified ObjectType is invalid.	-
400	InvalidObjectPath.Malformed	The specified ObjectPath is invalid.	-
400	QuotaExceeded.Refresh	Your refresh attempts have exceeded the daily limit.	Refresh quantity exceeds daily quota limit.
400	InvalidExtensiveDomain.ValueNotSupported	The specified ExtensiveDomain is not supported.	-
400	QuotaPerMinuteExceeded.Refresh	You tried to refresh too frequently, please try again later.	-
400	TooMany.Refresh	The refresh queue is full, please try again later.	-
429	TooManyRequests	Too many requests, please try again later	-

For a list of error codes, visit the Service error codes.

Change history

Change time	Summary of changes	Operation
2023-10-17	The Error code has changed. The request parameters of the API has changed	View Change Details