PushObjectCache - CDN - Alibaba Cloud Documentation Center

Operation description

This operation supports POST requests in which parameters are sent as a form.
Related operations: RefreshObjectCaches and PushObjectCache
URL prefetch quota (daily): By default, each account can submit up to 1,000 URL prefetch tasks per day. If the daily peak bandwidth of your account exceeds 200 Mbps, you can submit a ticket to request a quota increase. Alibaba Cloud evaluates your business requirements and adjusts your quota accordingly.
Each Alibaba Cloud account can submit up to 100 URLs at a time.
Prefetch queue rules: Each account can have up to 100,000 URLs in the prefetch queue. Alibaba Cloud CDN prefetches content based on the order in which URLs are submitted. When the number of URLs in the prefetch queue reaches 100,000, Alibaba Cloud CDN rejects new prefetch tasks.
You can call this operation up to 50 times per second per account.
If you want to automate refresh or prefetch operations, see Refresh and prefetch batch script.

Limits

After a prefetch task is submitted and successfully executed, CDN POPs immediately retrieve the required resources from the origin server. Therefore, submitting many prefetch tasks generates many concurrent download tasks, which causes a sudden increase in back-to-origin bandwidth and requests, increasing the pressure on the origin server.
The time required to complete a prefetch task is proportional to the size of the files that you want to prefetch. In most cases, a prefetch task takes 5 to 30 minutes. A task that prefetches a smaller file requires less time to complete.
If you want to use a Resource Access Management (RAM) user to perform refresh or prefetch operations, you must first grant the required permissions to the RAM user. For more information, see Grant a RAM user the permissions to refresh and prefetch.
By default, prefetch requests include the Accept-Encoding:gzip header. If you want a prefetch request to include other headers or implement multi-replica prefetch, you can specify a custom prefetch header by configuring the WithHeader parameter.
During prefetching, if the origin server returns a status code related to redirection such as 307, the prefetch task will not follow the redirection address to complete the prefetch, which ultimately leads to prefetch failure. If the origin server returns a status code of 301 or 302, and CDN has enabled origin 301/302 follow, normal prefetching is not affected in this case.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that support authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

cdn:PushObjectCache

none

*Domain

acs:cdn:*:{#accountId}:domain/{#DomainName}

None

Request parameters

Parameter	Type	Required	Description	Example
ObjectPath	string	Yes	The URL to prefetch. The format is accelerated domain name/file to prefetch. Note Separate multiple URLs with line feeds (\n) or (\r\n). The maximum length of each ObjectPath is 1,024 characters.	example.com/image/1.png\nexample.org/image/2.png
Area	string	No	The region from which content is prefetched. Valid values: domestic: Only Chinese mainland. overseas: Global (excluding Chinese mainland). If you do not set this parameter, content in the acceleration region of your domain name is prefetched. Note If the acceleration region of your domain name is Global and you left this parameter empty, the content is prefetched globally.	domestic
L2Preload	boolean	No	Specifies whether to prefetch content to L2 points of presence (POPs). Valid values: true: The POP level for prefetching must include L2 nodes. false: Content is prefetched only to back-to-origin layer nodes (false is the default value. Back-to-origin layer nodes can be L2 nodes or L3 nodes).	true
WithHeader	string	No	By default, prefetch requests include the Accept-Encoding:gzip header. If you want a prefetch request to include other headers or implement multi-replica prefetch, you can specify a custom prefetch header by configuring the WithHeader parameter. The value must be in the JSON format. Note If you do not want to include the Accept-Encoding header during prefetching, submit the following: `{"Accept-Encoding": [" "]}`	{ "Accept-Encoding": [ "gzip, deflate, br" ] }
QueryHashkey	boolean	No	Specifies whether to enable the hash key query mode when you run a prefetch task. Valid values: false (default): does not enable the hash key query mode and uses the hash key that corresponds to the submitted URL as the hash key of the file to prefetch. true: In this mode, the actual hash key used for the prefetch is queried based on the configuration of the domain name.	true
ConsistencyHash	boolean	No	If the acceleration region of the domain name is Chinese mainland and HASH origin fetch is enabled, you can use this parameter to set HASH prefetching to converge regional origin fetch traffic and reduce origin fetch bandwidth generated by prefetching. true: Enable HASH prefetching. false: Default logic, do not enable HASH prefetching. Important This parameter is valid only for domain names with Chinese mainland as the acceleration region.	true

Response parameters

Parameter	Type	Description	Example
	object
PushTaskId	string	The ID of the prefetch task. If multiple tasks are returned, the IDs are separated by commas (,). The task IDs are merged based on the following rules: Prefetch tasks by URL that you submitted for the same domain name within the same second are merged into the same PushTaskId. If the number of tasks that are set for the same accelerated domain name, submitted within the same second, and prefetch content from URLs instead of directories exceeds 500, every 500 task IDs are merged into the same task ID (RushTaskId).	9524xxxx
RequestId	string	The ID of the request.	16A96B9A-F203-4EC5-8E43-CB92E68F4CD8

Examples

Success response

JSON format

{
  "PushTaskId": "9524xxxx",
  "RequestId": "16A96B9A-F203-4EC5-8E43-CB92E68F4CD8"
}

Error codes

HTTP status code	Error code	Error message	Description
400	SingleRequest.OverLimit	A maximum of 1000 URLs are supported for each request.
400	QuotaExceeded.Preload	Your preload attempts have exceeded the daily limit.	The maximum number of URL prefetches on the current day is exceeded.
400	InvalidObjectPath.Malformed	The specified ObjectPath is invalid.
400	InvalidExtensiveDomain.ValueNotSupported	The specified ExtensiveDomain is not supported.
400	PreloadQueueFull	The warming queue is full,please try again later.
400	QuotaPerMinuteExceeded.Refresh	You have exceeded the prescribed preload limits per minute.
400	InvalidObjectPath.ExceedsMaximum	The maximum number of urls is exceeded.	The number of submitted URLs exceeds the maximum limit.
400	InvalidCustomHeader	Parse preload header failed.	Custom header parsing error.
429	TooManyRequests	System load fluctuates, please try again later.	System load fluctuates, please try again later.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.