提交 URL 封禁任务--内容分发网络-火山引擎

文档中心

立即注册

导航

提交 URL 封禁任务

最近更新时间：2025.06.27 15:35:47首次发布时间：2021.11.26 20:06:53

提交一个 URL 封禁任务，指示 CDN 拒绝用户对指定 URL 的访问。封禁 URL 任务提交后，如果 CDN 收到了对于指定 URL 的请求，CDN 返回 403 状态码。

要使用该 API，请提交工单。

该 API 支持通过正则表达式匹配需要封禁的 URL。要指定正则表达式，请额外提交工单。

使用限制

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

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

基于 URL 的封禁任务：
- 每日最多封禁 3,000 个 URL。
- 每个任务最多封禁 100 个 URL。
基于正则表达式的封禁任务：
- 您可以对一个加速域名指定累计 20 个用于匹配封禁 URL 的正则表达式。

如果您需要提升额度，请提交工单。

请求说明

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

请求参数

Query

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

Body

参数名称	数据类型	是否必选	参数说明	示例
UrlList	String[]	否	表示需要封禁的 URL 列表，每个 URL 都必须以 `http://` 或 `https://` 开头。如果 `Type` 是 `regex`，则您在列表中指定的是正则表达式。正则表达式仅用于匹配需要被封禁的 URL 中的路径和查询参数，不包含路径开头的 `/`。另外，正则表达式中只能包含以下内容：数字范围，例如 [0-9]。字母范围，例如 [a-z]，[A-Z]，[a-zA-Z] [^/]* .* [,?] ? 说明 URL 中不能包含泛域名。您不能直接通过指定一个包含泛域名的 URL 来对多个子域名下的文件执行封禁操作。您必须为每个域名指定需要封禁的 URL。参见如何对泛域名下的文件和目录执行刷新、预热、封禁和解封操作。	`文件 URL 示例：["https://www.a.com/1.jpg","https://www.b.com/2.jpg"]` `正则表达式示例： ["https://www.example.com/a[0-5]c/[0-9][a-z].*\.js\?a=[a-z]"]`
Type	String	否	表示封禁类型。该参数的取值如下： `url`：表示对指定的 URL 进行封禁。 `regex`：表示对匹配指定正则表达式的 URL 进行封禁。该参数的默认值是 `url`。	`url`
BlockRegion	String	否	表示封禁区域。当 `Type` 是 `url` 时，您才可以指定该参数。对于匹配封禁 URL 列表的请求，仅当接收请求的 CDN 节点位于您指定的封禁区域，CDN 才拒绝该请求。该参数有以下取值： `chinese_mainland`：表示中国内地。 `outside_chinese_mainland`：表示全球（不包含中国内地） `global`：表示全球。如果该参数不指定，封禁区域就是加速域名的加速区域。	`outside_chinese_mainland`
Urls	String	否	该参数与 `UrlList` 都是表示需要封禁的 URL 列表，区别如下： `Urls` 的数据类型是 String。您在 `Urls` 中指定的 URL 之间需要以 `\n` 分隔。 `UrlList` 的数据类型是 String 数组。数组中每个元素是一个 URL。推荐您使用 `UrlList` 来指定需要封禁的 URL 列表。如果您同时指定了 `Urls` 和 `UrlList`，仅 `UrlList` 生效。	`文件 URL 示例：https://www.a.com/1.jpg\nhttps://www.b.com/2.jpg` `正则表达式示例： https://www.example.com/a[0-5]c/[0-9][a-z].*\.js\?a=[a-z]`

返回参数

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

请求示例

POST https://cdn.volcengineapi.com/?Action=SubmitBlockTask&Version=2021-03-01
{
    "UrlList": [
        "https://www.a.com/1.txt",
        "https://www.b.com/2.txt"
    ],
    "BlockRegion": "chinese_mainland",
    "Type": "url"
}

返回示例

{
    "ResponseMetadata": {
        "RequestId": "202111261507450102120420191700979F",
        "Action": "SubmitBlockTask",
        "Version": "2021-03-01",
        "Service": "CDN",
        "Region": "cn-north-1"
    },
    "Result": {
        "TaskID": "url_block_2021112615074501001104903931775"
    }
}

错误码

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