PushObjectCache - 预热URL

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

接口说明

  • 请求方式:支持 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

ConsistencyHash

boolean

如果域名加速区域为中国大陆并且开启了 HASH 回源,可通过此参数设置 HASH 预热,实现区域回源收敛,减少预热产生的回源带宽。

  • true: 开启 HASH 预热。

  • false: 缺省逻辑,不开启 HASH 预热。

重要

仅对加速区域为中国大陆的域名有效。

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 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. 自定义头部解析错误。
429 TooManyRequests System load fluctuates, please try again later. 系统负载波动,请稍候重试。

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

变更历史

更多信息,参考变更详情