DocsICP FilingConsole
Documentation

PushObjectCache

Updated at:
Copy as MD
Product
My Favorites

Prefetches content from the origin server to cache nodes. This ensures that initial requests hit the cache directly and reduces the load on the origin server.

Operation description

  • Request method: Supports POST requests. Parameters are displayed in a form.

  • Related operations: Refresh and prefetch operations include the RefreshObjectCaches refresh operation and the PushObjectCache prefetch operation.

  • URL prefetch quota (daily): By default, an account can submit up to 1,000 URL prefetch tasks per day. If the daily peak bandwidth of your account exceeds 200 Mbit/s, you can apply to increase the daily quota by using Quota Center. Alibaba Cloud evaluates and configures the quota based on your actual business requirements.

  • You can submit up to 100 URL prefetch tasks at a time.

  • Prefetch queue rules: The maximum prefetch queue size for each account is 100,000 URLs. CDN prefetches URLs in the order they are submitted. When the number of URLs waiting to be prefetched in the queue reaches 100,000, CDN will deny new prefetch tasks.

  • Invoke frequency per user: 50 times per second.

  • To automate refresh or prefetch, refer to Batch scripts for refresh and prefetch.

Precautions

  • After a prefetch task is submitted and successfully executed, the point of presence immediately performs an origin fetch to load the required resources. Therefore, submitting a large number of prefetch tasks generates many concurrent download tasks, which causes a sudden increase in origin fetch bandwidth and requests, and increases the load on the origin server.

  • The actual execution time from submission to completion of a prefetch task depends on the size of the prefetched files and takes about 5 to 30 minutes. The smaller the average file size, the faster the prefetch speed.

  • If you use a Resource Access Management (RAM) user to perform refresh or prefetch operations, you must first obtain authorization. For more information, refer to Grant a RAM user the permissions to refresh and prefetch resources to complete the authorization.

  • By default, prefetch requests carry the Accept-Encoding:gzip header. If you need prefetch requests to carry other headers or implement multi-replica prefetching, you can use the WithHeader request parameter to customize the prefetch headers.

  • During prefetching, if the origin server returns status codes related to redirection such as 307, the prefetch task does not follow the redirection address to continue prefetching, which ultimately results in a failed prefetch task. If the origin server returns a 301 or 302 status code and the 301/302 redirect feature is enabled on the point of presence, Normal prefetching is not affected.

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 supports 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 None

Request parameters

Parameter

Type

Required

Description

Example
ObjectPath

string

Yes

The URLs to prefetch. Format: accelerated domain name/file to prefetch.

Note

Separate multiple URLs with line breaks. The maximum length of a single ObjectPath is 1,024 characters.

http://example.com/image/1.png http://example.org/image/2.png
Area

string

No

The prefetch region. Valid values:

  • domestic: the Chinese mainland only

  • overseas: global (excluding the Chinese mainland)

If you do not specify this parameter, the default prefetch region is the CDN acceleration region configured for your domain name.

Note

  • If you want to set the prefetch region to global, make sure that the acceleration region of the accelerated domain name is set to global, and do not specify this parameter.

Valid values:

  • domestic :

    The Chinese mainland only.

  • overseas :

    Global (excluding the Chinese mainland).

domestic
L2Preload

boolean

No

Specifies whether to prefetch content directly to Layer 2 (L2) nodes. Valid values:

  • true: Prefetches content to L2 nodes.

  • false: Prefetches content only to origin fetch nodes. This is the default value. Origin fetch nodes can be L2 or Layer 3 (L3) nodes.

true
WithHeader

string

No

By default, prefetch requests carry the Accept-Encoding:gzip header. If you need prefetch requests to carry other headers or implement multi-replica prefetching, you can use this parameter to customize the prefetch headers. Submit the value in JSON format.

Note

If you do not need the Accept-Encoding header during prefetching, submit the value as follows:

  • {"Accept-Encoding": [" "]}

{ "Accept-Encoding": [ "gzip, deflate, br" ] }
QueryHashkey

boolean

No

Specifies whether to enable the hash key query mode when executing prefetch tasks. Valid values:

  • false: The default mode. Used when this parameter is not specified. The submitted URL is directly used as the hash key of the prefetched file.

  • true: Queries the actual hash key used for the prefetch URL based on the domain name configuration.

true
ConsistencyHash

boolean

No

If the acceleration region of the domain name is the Chinese mainland and hash-based origin fetch is enabled, you can use this parameter to enable hash-based prefetching. This implements regional origin fetch convergence and reduces the back-to-origin bandwidth generated by prefetching. Valid values:

  • true: Enables hash-based prefetching.

  • false: The default logic. Hash-based prefetching is disabled.

Important This parameter is valid only for domain names whose acceleration region is the Chinese mainland.

true

Response elements

Element

Type

Description

Example

object

PushTaskId

string

The ID of the prefetch task. Multiple task IDs are separated by commas (,). The returned task IDs are merged based on the following rules:

  • Prefetch tasks (at the URL granularity) submitted for the same domain name within the same second are merged into the same PushTaskId.

  • If the number of prefetch tasks (at the URL granularity) submitted for the same domain name within the same second exceeds 500, the tasks are merged into one PushTaskId for every 500 tasks.

9524xxxx
RequestId

string

The request ID.

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.