文档中心

提交刷新任务

最近更新时间：2024.04.02 17:39:10

首次发布时间：2021.07.15 11:09:03

在火山引擎内容分发网络中提交一个刷新任务。您一次可以多个 URL 或目录执行刷新操作。

使用限制

节流限制：您每秒最多可以发送 20 个请求。

默认情况下，每个火山引擎账号下的刷新额度如下：

URL 刷新：每天最多刷新 1,000 个 URL。
目录刷新：每天最多刷新 50 个目录路径。
任务刷新额度：每个任务可以包含 100 个 URL或目录路径。

您账号下的实际额度可能会与默认额度有差异。要查看实际额度，有以下两个方法：

打开火山引擎控制台的刷新预热页面。
调用 DescribeContentQuota。

如需调整任务的额度，请提交工单。

请求说明

请求方式：POST
请求地址：https://cdn.volcengineapi.com/?Action=SubmitRefreshTask&Version=2021-03-01

请求参数

Query

参数名称	数据类型	是否必选	参数说明
Action	String	是	接口名称。当前 API 的名称为 `SubmitRefreshTask`。
Version	String	是	接口版本。当前 API 的版本为 `2021-03-01`。

Body

参数名称	数据类型	是否必选	参数说明	示例
Type	String	否	指定刷新类型。该参数有以下取值： `file`：表示 URL 刷新，对一个或者多个文件执行刷新操作。 `dir`：表示目录刷新，对一个或者多个目录下的所有文件，包括子目录下的文件执行刷新操作。 `regex`：表示正则刷新。指定一个或多个正则表达式，对与正则表达式匹配的文件 URL 执行刷新操作。要使用正则刷新，请提交工单。关于正则刷新的介绍和 URL 规范，参见正则刷新。该参数的默认值为 `file`。	`file`
Prefix	Boolean	否	表示是否启用前缀刷新。该参数仅当 `Type` 是 `dir` 时有效，有以下取值： `true`：表示启用前缀刷新，对以指定前缀开头的目录路径下的所有文件执行刷新操作。 `false`：表示不启用前缀刷新。该参数的默认值是 `false`。	`true`
Urls	String	是	表示需要刷新的 URL，多个 URL 之间使用 `\n` 分隔。每个 URL 都必须以 `http://` 或 `https://` 开头。当 `Type` 是 `file` 时，您需要指定一个或者多个文件的 URL。当 `Type` 是 `dir` 时，如果 `Prefix` 是 `false`，您需要指定一个或者多个以 `/` 结尾的目录路径。如果 `Prefix` 是 `true`，您需要指定一个或者多个 URL 前缀，用于匹配目录路径。例如 `http://www.example.com/im` 可以匹配 `http://www.example.com/image/` 与 `http://www.example.com/ime/` 这两个目录路径。当 `Type` 是 `regex` 时，您需要指定一个或者多个正则表达式。参见正则刷新。说明 URL 中不能包含泛域名。您不能直接通过指定一个包含泛域名的 URL 来对多个子域名下的文件或目录执行刷新操作。您必须为每个域名指定刷新 URL。参见如何对泛域名下的文件和目录执行刷新、预热、封禁和解封操作。	`https://www.a.com/1.jpg\nhttps://www.b.com/2.jpg`
Delete	Boolean	否	表示是否在刷新指定的文件时，是否同时从缓存中删除这些文件。该参数仅当 `Type` 是 `dir` 时有效。要使用该参数，请提交工单。该参数有以下取值： `true`：表示删除这些文件。之后，如果收到了这些文件的请求，内容分发网络会向源站获取这些文件。 `false`：表示保留这些文件。之后，如果收到了这些文件的请求，内容分发网络会向源站校验这些文件是否已过期。参见回源校验。该参数的默认值是 `false`。	`true`

响应正文

参数名称	数据类型	参数说明	示例
TaskID	String	表示提交的任务 ID。您可以调用 DescribeContentTasks 查看 `Urls` 列表中每个 URL 的执行状态。	`refresh_url_bbd36e1cb5154f52b648b07ee119223e2971399f5a1075c0`

请求示例

POST https://cdn.volcengineapi.com/?Action=SubmitRefreshTask&Version=2021-03-01
{
  "Type": "file",
  "Urls": "https://www.a.com/1.txt\nhttps://www.b.com/2.txt"
}

返回示例

{
  "ResponseMetadata": {
    "RequestId": "202201141648440102100180260E003ABA",
    "Action": "SubmitRefreshTask",
    "Version": "2021-03-01",
    "Service": "CDN",
    "Region": "cn-north-1"
  },
  "Result": {
    "TaskID": "refresh_url_bbd36e1cb5154f52b648b07ee119223e2971399f5a1075c0"
  }
}

错误码

如果响应正文的 ResponseMetadata 字段中包含 Error 字段，则表示 API 请求失败。更多关于错误码的信息，参见错误码。