DescribeContentTasks - 获取刷新与预热任务列表--内容分发网络-火山引擎

文档中心

立即注册

导航

DescribeContentTasks - 获取刷新与预热任务列表

最近更新时间：2025.12.09 18:02:25首次发布时间：2021.07.15 11:09:03

获取过去 7 天内提交的刷新或预热任务，细分到这些任务中的每个 URL。返回结果展示了每个 URL 的任务详情，包括任务的执行结果。您可以使用多个过滤选项对结果进行过滤。

使用限制

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

请求说明

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

请求参数

Query

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

Body

参数名称	数据类型	是否必选	参数说明	示例
Url	String	否	表示一个 URL 列表，用于对查询结果进行过滤，以获取列表中每个 URL 的任务详情。每个 URL 都必须以 `http://` 或 `https://` 开头。该参数是一个字符串，多个 URL 之间使用 `\n` 分隔。如果您同时指定了 `UrlList`，则 `Url` 不生效。	`https://www.example.com/1.jpg\nhttps://www.example.com/2.jpg`
DomainName	String	否	表示一个加速域名，用于对查询结果进行过滤，以获取 URL 中包含该域名的任务。	`www.example.com`
TaskID	String	否	表示加速域名，用于筛选查询结果，获取所有该 ID 的任务。	`prefetch_url_89c25a1aa3044b39921387190fc9b0e438f3d071f278f031`
TaskType	String	是	表示一个任务类型，用于对查询结果进行过滤，以获取该类型任务。该参数的可用值如下： `refresh_file`：表示 URL 刷新任务。 `refresh_dir`：表示目录刷新任务。 `preload`：表示 URL 预热任务。 `refresh_regex`：表示正则刷新任务。	`preload`
Status	String	否	表示一个任务状态，用于对查询结果进行过滤，以获取该状态下任务。该参数的可用值如下： `complete`：表示已完成的任务。 `running`：表示执行中的任务。 `failed`：表示执行失败的任务。如果不指定该参数，则表示不使用该参数对任务列表进行过滤。	`complete`
StartTime	Integer	否	表示一个开始时间，格式是 Unix 时间戳，用于对查询结果进行过滤，以获取提交时间晚于或等于该时间的 URL 任务。需要留意的是，您无法查询 7 天前提交的 URL 任务。您必须同时指定 `StartTime` 和 `EndTime`，或者两个参数都不指定。如果两个参数都不指定，则获取过去 7 天内提交的 URL 任务。	`1641844915`
EndTime	Long	否	表示一个结束时间，格式是 Unix 时间戳，，用于对查询结果进行过滤，以获取提交时间早于或等于该时间的 URL 任务。	`1641845373`
PageNum	Long	否	表示一个页码，用于获取该分页上的 URL 任务。该参数的默认值为 `1`。 CDN 对符合过滤条件的 URL 任务进行分页。您可以根据响应正文中的 `Total` 和 `PageSize` 参数的值计算页数。	`1`
PageSize	Long	否	表示每个分页所包含的 URL 任务数量。该参数的取值范围是 1-1000，默认值是 `50`。	`10`
Remark	String	否	表示一个错误消息，用户对查询结果进行过滤，以获取返回该错误消息的任务。该参数的取值如下： `Origin_Error`：表示源站返回了错误。其他错误消息待补充。	`origin_error`
UrlList	String[]	否	表示一个 URL 列表，用于对查询结果进行过滤，以获取列表中每个 URL 的任务详情。每个 URL 都必须以 `http://` 或 `https://` 开头。该参数是一个字符串数组。如果您同时指定了 `Url`，则 `Url` 不生效。	`["https://www.example.com/1.jpg","https://www.example.com/2.jpg"]`

返回参数

参数名称	数据类型	参数说明	示例
Total	Long	表示符合过滤条件的 URL 任务总数。	`2`
PageNum	Long	表示请求正文中的 `PageNum`。	`1`
PageSize	Long	表示请求正文中的 `PageSize`。	`100`
Data	Object[]	表示 `PageNum` 所指定分页上的 URL 任务列表。如果 `PageNum` 所表示页码不存在或者该页上没有任务，该参数值为 `null`。

请求示例

POST https://cdn.volcengineapi.com/?Action=DescribeContentTasks&Version=2021-03-01
{
    "StartTime": 1625587200,
    "EndTime": 1625673600,
    "TaskType": "preload",
    "PageSize": 3,
    "PageNum": 2
}

返回示例

{
    "ResponseMetadata": {
        "RequestId": "20250717112310C351411163F79CB1D257",
        "Action": "DescribeContentTasks",
        "Version": "2021-03-01",
        "Service": "CDN",
        "Region": "cn-north-01"
    },
    "Result": {
        "Data": [
            {
                "CreateTime": 1752721949,
                "Process": "100%",
                "Remark": "",
                "Status": "complete",
                "TaskID": "prefetch_url_4b2d138c7fcb499abd7f5acfe41c6977ecc45788129c0db",
                "TaskType": "preload",
                "Url": "http://www.example.com/file/1.txt"
            },
            {
                "CreateTime": 1752721767,
                "Process": "100%",
                "Remark": "origin_error",
                "Status": "failed",
                "StatusCode": 404,
                "TaskID": "prefetch_url_a4fde3a31e9d46bb98fc88c4b179d1f815c7397d37074f6c",
                "TaskType": "preload",
                "Url": "http://www.example.com/file/2.txt"
            },
            {
                "CreateTime": 1752724151,
                "Process": "100%",
                "Remark": "",
                "RequestHeaderInstances": [
                    {
                        "Key": "header",
                        "Value": "value"
                    },
                    {
                        "Key": "hello",
                        "Value": "world"
                    }
                ],
                "Status": "complete",
                "TaskID": "prefetch_url_8c2d22809aca48349c128bef48b9e79913083634bd249aa8",
                "TaskType": "preload",
                "Url": "http://www.example.com/file/3.txt"
            }
        ],
        "PageNum": 2,
        "PageSize": 3,
        "Total": 56
    }
}

错误码

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