SubmitRefreshTask - 提交刷新任务--内容分发网络-火山引擎

文档中心

立即注册

内容分发网络

内容管理接口

SubmitRefreshTask - 提交刷新任务

在火山引擎内容分发网络（CDN）中提交一个刷新任务。如果在任务中指定文件 URL，CDN 会执行任务时会删除这些文件。如果在任务中指定目录，CDN 默认会标记这些目录中的文件为过期。

使用限制

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

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

每天最多刷新 10,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`
UrlList	String[]	否	表示一个待刷新的 URL 列表。每个 URL 必须以 `http://` 或 `https://` 开头。当 `Type` 是 `file` 时，您指定的是文件 URL。当 `Type` 是 `dir` 时，如果 `Prefix` 是 `false`，您指定的是以 `/` 结尾的目录，例如 `http://www.example.com/image/`。如果 `Prefix` 是 `true`，您指定的是目录前缀。例如 `http://www.example.com/im` 可以匹配 `http://www.example.com/image/` 与 `http://www.example.com/ime/` 这两个目录。当 `Type` 是 `regex` 时，您指定的是用来匹配文件 URL 的正则表达式。参见正则刷新。说明您不能直接对泛域名下的文件和目录执行刷新操作，而是要对每个子域名进行这些操作。参见如何对泛域名下的文件和目录执行刷新、预热、封禁和解封操作。	`["https://www.example.com/1.jpg","https://www.example.com/2.jpg"]`
Delete	Boolean	否	对于目录刷新，该参数表示是否从缓存中删除 `Urls` 指定的文件。该参数仅当 `Type` 是 `dir` 时有效。要使用该参数，请提交工单。该参数有以下取值： `true`：表示删除这些文件。之后，如果收到了这些文件的请求，CDN 会向源站请求这些文件。 `false`：表示不删除这些文件，仅标记这些文件为已过期。之后，如果收到了这些文件的请求，CDN 会执行回源校验。该参数的默认值是 `false`。	`true`
Urls	String	否	不建议使用该参数，请使用 `UrlList` 代替。该参数的作用与 `UrlList` 相同。在 `Urls` 中指定多个 URL 时，URL 之间必须以 `\n` 分隔。如果您同时指定了 `UrlList` 和 `Urls`，仅 `UrlList` 生效。	`https://www.example.com/1.jpg\nhttps://www.example.com/2.jpg`
RequestHeaderInstances	Object[]	否	对于待刷新文件的缓存键，该配置指定了缓存键中必须包含的请求头列表。列表中最多包含 10 个请求头。
CacheShared	Boolean	否	当 `TaskType` 是 `dir`，并且刷新任务的目标域名在一个共享缓存配置中，该参数才有效时。该参数表示刷新任务是否应用于共享缓存配置中的所有域名。该参数有以下取值： `true`：表示刷新任务应用于所有域名。如果收到任意域名下目录文件的请求，CDN 就会对相应文件执行刷新操作。 `false`：表示刷新任务仅应用于目标域名。只有收到目标域名下目录文件的请求，CDN 才会对相应文件执行刷新操作。关于示例，参见缓存刷新。该参数的默认值是 `false`。	`true`

返回参数

参数名称	数据类型	参数说明	示例
TaskID	String	表示该任务的 ID。您可以调用 DescribeContentTasks 查看 `Urls` 列表中每个对象的刷新结果。	`refresh_url_bbd36e1cb5154f52b648b07ee119223e2971399f5a1075c0`

请求示例

POST https://cdn.volcengineapi.com/?Action=SubmitRefreshTask&Version=2021-03-01
{
    "Type": "file",
    "UrlList": [
        "https://www.example.com/1.txt",
        "https://www.example.com/2.txt"
    ],
    "RequestHeaderInstances": [
        {
            "Key": "header1",
            "Value": "value1"
        },
        {
            "Key": "header2",
            "Value": "value2"
        }
    ]
}

返回示例

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

错误码

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

最近更新时间：2026.02.10 10:16:48

这个页面对您有帮助吗？

有用

无用

内容分发网络

使用限制 #

请求说明 #

请求参数 #

Query #

Body #

返回参数 #

请求示例 #

返回示例 #

错误码 #