PushObjectCache - 预热URL - CDN

调用PushObjectCache将源站的内容主动预热到缓存节点上。您首次访问可直接命中缓存，缓解源站压力。

接口说明

请求方式：支持 POST 请求，参数用 form 表单显示。
相关接口：刷新预热类接口包含 RefreshObjectCaches 刷新接口和 PushObjectCache 预热接口。
URL 预热配额（每日）：默认情况下，一个账号每日最多可以提交 1000 条 URL 预热任务，如果您账号的日带宽峰值大于 200 Mbps，可通过提交工单申请提升每日配额，阿里云将根据您业务的实际需求进行评估和配置。
每次最多可以提交 100 条 URL 预热任务。
预热队列规则：每个账号的预热队列最大为 100000 条 URL，CDN 根据 URL 提交的先后顺序进行预热；当预热队列中待预热的 URL 达到了 100000 条时，CDN 将会拒绝接收新的预热任务。
单用户调用频率：50 次/秒。
如果您需要自动化刷新或预热，请参见刷新预热批处理脚本。

注意事项

提交预热任务并成功执行后，CDN 节点会立即回源站加载所需资源，因此大批量提交预热任务会生成较多的并发下载任务，导致回源带宽和请求突增，增加源站压力。
预热任务从提交到预热完成，实际执行时间视预热文件大小而定，大约需要 5~30 分钟，文件平均大小越小，预热速度越快。
使用 RAM 用户来执行刷新或预热操作的，需要先获得授权，请参见授予 RAM 用户刷新预热权限完成授权。
预热请求默认携带的 header 是 Accept-Encoding:gzip，如果您需要预热请求携带其他 header，或者实现多副本预热，那么可以使用请求参数 WithHeader 来实现自定义预热 header。
预热时，如果源站返回 307 等重定向相关的状态码，预热任务并不会跟随重定向地址继续完成预热，最终会导致预热失败。如果源站返回的是 301 或者 302 状态码，并且 CDN 上已经开启了回源 301/302 跟随，这种情况下正常预热不受影响。

调试

您可以在OpenAPI Explorer中直接运行该接口，免去您计算签名的困扰。运行成功后，OpenAPI Explorer可以自动生成SDK代码示例。

调试

授权信息

下表是API对应的授权信息，可以在RAM权限策略语句的Action元素中使用，用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下：

操作：是指具体的权限点。
访问级别：是指每个操作的访问级别，取值为写入（Write）、读取（Read）或列出（List）。
资源类型：是指操作中支持授权的资源类型。具体说明如下：
- 对于必选的资源类型，用背景高亮的方式表示。
- 对于不支持资源级授权的操作，用全部资源表示。
条件关键字：是指云产品自身定义的条件关键字。
关联操作：是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限，操作才能成功。

操作	访问级别	资源类型	条件关键字	关联操作
cdn:PushObjectCache	none	Domain `acs:cdn::{#accountId}:domain/{#DomainName}`	无	无

请求参数

名称	类型	必填	描述	示例值
ObjectPath	string	是	预热 URL，格式为加速域名/预热的文件。说明多个 URL 之间用换行符（\n）或（\r\n）分隔，ObjectPath 的单条长度最长为 1024 个字符。	example.com/image/1.png\nexample.org/image/2.png
Area	string	否	预热区域。取值： domestic：仅中国内地。 overseas：全球（不包含中国内地）。如果不传该参数，默认的预热区域为您的域名所配置的 CDN 加速区域。具体如下：域名的加速区域为“仅中国内地”，预热区域是仅中国内地。域名的加速区域为“全球”，预热区域是全球。域名的加速区域为“全球（不包含中国内地）”，预热区域是全球（不包含中国内地）。	domestic
L2Preload	boolean	否	是否直接预热到 L2 节点。取值： true：代表预热的节点层级必须包含 L2 节点。 false：代表仅预热回源层节点（false 为默认值，回源层节点可能是 L2 节点，也可能是 L3 节点）。	true
WithHeader	string	否	预热请求默认携带的 header 是 Accept-Encoding:gzip，如果您需要预热请求携带其他 header，或者实现多副本预热，那么可以使用该参数来实现自定义预热 header。用 JSON 串格式提交。说明若预热的时候不需要 Accept-Encoding 头部，则按如下提交 {"Accept-Encoding": [" "]}	{ "Accept-Encoding": [ "gzip, deflate, br" ] }
QueryHashkey	boolean	否	该参数用于控制执行预热任务时是否开启 hashkey 查询模式。取值范围： false：默认模式，不传参数的时候使用该模式，指的是直接使用提交的 URL 作为预热文件的 hashkey。 true：根据域名的配置来查询预热 URL 实际使用的 hashkey。	true

返回参数

名称	类型	描述	示例值
	object
PushTaskId	string	预热返回的任务 ID，多个任务 ID 用半角逗号（,）分隔。预热返回的任务 ID 会按照以下两条规则对预热任务做合并：同一个域名、同一秒钟提交的预热任务（URL 颗粒度）会被合并为同一个 PushTaskId。同一个域名、同一秒钟提交的预热任务（URL 颗粒度）如果超过 500 条，那么会按照每 500 条合并为一个 PushTaskId 的方式处理。	9524xxxx
RequestId	string	请求 ID。	16A96B9A-F203-4EC5-8E43-CB92E68F4CD8

示例

正常返回示例

JSON格式

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

错误码

HTTP status code	错误码	错误信息	描述
400	SingleRequest.OverLimit	A maximum of 1000 URLs are supported for each request.	-
400	QuotaExceeded.Preload	Your preload attempts have exceeded the daily limit.	超出当日预热额度限制。
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	PreloadQueueFull	Preload 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.	提交URL数超过最大限制。
400	InvalidCustomHeader	Parse preload header failed.	自定义头部解析错误。
400	InvalidCustomHeader	Unsupported Preload headers included.	无效的自定义预热头部。
429	TooManyRequests	System load fluctuates, please try again later.	系统负载波动，请稍候重试。

访问错误中心查看更多错误码。

变更历史

变更时间	变更内容概要	操作
2024-11-03	OpenAPI 描述信息更新、OpenAPI 错误码发生变更、OpenAPI 入参发生变更	查看变更详情
2024-08-21	OpenAPI 错误码发生变更	查看变更详情
2023-07-25	OpenAPI 错误码发生变更	查看变更详情