PushObjectCache - 预热URL

调用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:PushObjectCachenone
  • Domain
    acs:cdn:*:{#accountId}:domain/{#DomainName}

请求参数

名称类型必填描述示例值
ObjectPathstring

预热 URL,格式为加速域名/预热的文件

说明 多个 URL 之间用换行符(\n)或(\r\n)分隔,ObjectPath 的单条长度最长为 1024 个字符。
example.com/image/1.png\nexample.org/image/2.png
Areastring

预热区域。取值:

  • domestic仅中国内地
  • overseas全球(不包含中国内地)。

如果不传该参数,默认的预热区域为您的域名所配置的 CDN 加速区域。具体如下:

  • 域名的加速区域为“仅中国内地”,预热区域是仅中国内地。
  • 域名的加速区域为“全球”,预热区域是全球。
  • 域名的加速区域为“全球(不包含中国内地)”,预热区域是全球(不包含中国内地)。
domestic
L2Preloadboolean

是否直接预热到 L2 节点。取值:

  • true:代表预热的节点层级必须包含 L2 节点。
  • false:代表仅预热回源层节点(false 为默认值,回源层节点可能是 L2 节点,也可能是 L3 节点)。
true
WithHeaderstring

预热请求默认携带的 header 是 Accept-Encoding:gzip,如果您需要预热请求携带其他 header,或者实现多副本预热,那么可以使用该参数来实现自定义预热 header。用 JSON 串格式提交。

说明 若预热的时候不需要 Accept-Encoding 头部,则按如下提交
  • {"Accept-Encoding": [" "]}
  • { "Accept-Encoding": [ "gzip, deflate, br" ] }
    QueryHashkeyboolean

    该参数用于控制执行预热任务时是否开启 hashkey 查询模式。取值范围:

    • false:默认模式,不传参数的时候使用该模式,指的是直接使用提交的 URL 作为预热文件的 hashkey。
    • true:根据域名的配置来查询预热 URL 实际使用的 hashkey。
    true

    返回参数

    名称类型描述示例值
    object
    PushTaskIdstring

    预热返回的任务 ID,多个任务 ID 用半角逗号(,)分隔。预热返回的任务 ID 会按照以下两条规则对预热任务做合并:

    • 同一个域名、同一秒钟提交的预热任务(URL 颗粒度)会被合并为同一个 PushTaskId。
    • 同一个域名、同一秒钟提交的预热任务(URL 颗粒度)如果超过 500 条,那么会按照每 500 条合并为一个 PushTaskId 的方式处理。
    9524xxxx
    RequestIdstring

    请求 ID。

    16A96B9A-F203-4EC5-8E43-CB92E68F4CD8

    示例

    正常返回示例

    JSON格式

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

    错误码

    HTTP status code错误码错误信息描述
    400SingleRequest.OverLimitA maximum of 1000 URLs are supported for each request.-
    400QuotaExceeded.PreloadYour preload attempts have exceeded the daily limit.超出当日预热额度限制。
    400InvalidObjectPath.MalformedThe specified ObjectPath is invalid.-
    400InvalidExtensiveDomain.ValueNotSupportedThe specified ExtensiveDomain is not supported.-
    400PreloadQueueFullThe warming queue is full,please try again later.-
    400PreloadQueueFullPreload queue is full, please try again later.预热队列已满,请稍候重试。
    400QuotaPerMinuteExceeded.RefreshYou have exceeded the prescribed preload limits per minute.-
    400InvalidObjectPath.ExceedsMaximumThe maximum number of urls is exceeded.提交URL数超过最大限制。
    400InvalidCustomHeaderParse preload header failed.-
    400InvalidCustomHeaderUnsupported Preload headers included.-
    429TooManyRequestsSystem load fluctuates, please try again later.系统负载波动,请稍候重试。

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

    变更历史

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