CDN > API 文档 > 缓存管理

缓存管理

最近更新时间: 2026-03-25 14:06:44

1. 快速查阅区

1.1 核心接口概览

接口功能	请求方法	接口路径	核心参数	成功响应
缓存刷新	POST	`/v2/tune/refresh`	urls、dirs	`{"code":200,"taskIds":{...}}`
刷新任务查询	POST	`/v2/tune/refresh/list`	requestId / taskId	`{"code":200,"items":[...]}`
资源预取	POST	`/v2/tune/prefetch`	urls	`{"code":200,"taskIds":{...}}`
预取任务查询	POST	`/v2/tune/prefetch/list`	requestId	`{"code":200,"items":[...]}`

1.2 核心约束

请求域名: fusion.qiniuapi.com
鉴权方式: QBox 鉴权（详见鉴权指南）
QPS限制: 刷新+预取请求中 url/dir 总量每秒 ≤ 240
生效时间: 5-10 分钟

1.3 每日配额

操作	默认配额	单次上限 (官网)	超限错误码
文件刷新	500 次/天	20 个 URL	400034
目录刷新	11次/天	5 个目录	400035 / 400038
资源预取	100 次/天	20 个 URL	400033

配额每日 0 点重置，可在控制台申请提升。成功响应中 urlQuotaDay / urlSurplusDay 返回当日配额和剩余量。

2. 详细接口说明

2.1 缓存刷新

基本信息

请求方法: POST
接口地址: https://fusion.qiniuapi.com/v2/tune/refresh
用途: 强制 CDN 节点回源拉取最新文件

请求参数

参数名	类型	必填	说明	示例值
urls	array	否	文件 URL 列表，完整 http:// 或 https:// 格式	`["http://test.com/a.jpg"]`
dirs	array	否	目录 URL 列表，须以 / 结尾	`["http://test.com/static/"]`

urls 和 dirs 不能同时为空，至少传一个。

请求示例

curl -X POST 'https://fusion.qiniuapi.com/v2/tune/refresh' \
  -H 'Host: fusion.qiniuapi.com' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: QBox <AK>:<Sign>' \
  -d '{"urls":["http://test.example.com/index.html","http://test.example.com/style.css"],"dirs":["http://test.example.com/static/"]}'

响应参数

参数名	类型	说明
code	int	响应状态码
error	string	响应错误码描述
requestId	string	刷新请求id，只有在任务被接受时才有值
taskIds	map[string]string	URL/DIR 对应的任务 ID，map[url/dir]taskId
invalidUrls	string array	无效的url列表
invalidDirs	string array	无效的dir列表
urlQuotaDay	int	每日的刷新url限额
urlSurplusDay	int	每日的当前剩余的刷新url限额
dirQuotaDay	int	每日的刷新dir限额
dirSurplusDay	int	每日的当前剩余的刷新dir限额

响应示例

成功 (HTTP 200):

{
    "code": 200,
    "error": "success",
    "requestId": "698e908943d723411eda9d41",
    "taskIds": {
        "http://test.example.com/index.html": "698e908943d723411eda9d42",
        "http://test.example.com/static/": "698e908943d723411eda9d43"
    },
    "invalidUrls": null,
    "invalidDirs": null,
    "urlQuotaDay": 500,
    "urlSurplusDay": 493,
    "dirQuotaDay": 11,
    "dirSurplusDay": 3
}

失败:


{
    "code": 400031,
    "error": "invalid url",
    "invalidUrls": [
        "invalid-url"
    ]
}

2.2 刷新任务查询

基本信息

请求方法: POST
接口地址: https://fusion.qiniuapi.com/v2/tune/refresh/list
用途: 查询刷新任务执行状态
查询时间范围: 近 7 天，默认返回近 3 天记录

请求参数

参数名	类型	必填	说明	示例值
taskIds	array	否	任务 ID 列表	`["698ee3057911048e39e0ac8d"]`
requestId	string	否	请求 ID	`"698ee3057911048e39e0ac8c"`
isDir	string	否	是否目录刷新	`"yes"` / `"no"`
urls	array	否	按 URL 查询	`["http://test.com/a.jpg"]`
state	string	否	按状态筛选	`"success"` / `"failure"` / `"processing"`
pageNo	int	否	页码	0
pageSize	int	否	每页条数	100
startTime	string	否	开始日期	`"2026-02-10"`
endTime	string	否	结束日期	`"2026-02-13"`

可选参数不能全部为空，至少传一个。时间范围最多 7 天，startTime/endTime 缺失时默认返回近 3 天。

请求示例

curl -X POST 'https://fusion.qiniuapi.com/v2/tune/refresh/list' \
  -H 'Host: fusion.qiniuapi.com' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: QBox <AK>:<Sign>' \
  -d '{"requestId":"698e908943d723411eda9d41"}'

响应参数

参数名	类型	说明
code	int	响应状态码
error	string	响应错误码描述
requestId	string	记录所在的刷新请求id
total	int	当前条件下查询的记录总数
pageNo	int	要查询的页号
pageSize	int	要返回的页长度
currentSize	int	当前实际返回的页长度
uid	string	用户id
taskId	string	任务id
isDir	string	是否目录刷新，取值为yes／no
url	string	url
progress	int	任务进度，0-100
state	string	刷新状态，取值为success／processing／failure
stateDetail	string	刷新状态描述信息
createAt	string	当前记录创建时间，格式为xxxx-xx-xx xx:xx:xx，例如2015-11-01 16:05:05
beginAt	string	当前记录开始时间，格式为xxxx-xx-xx xx:xx:xx，例如2015-11-01 16:05:25
endAt	string	当前记录结束时间，格式为xxxx-xx-xx xx:xx:xx，例如2015-11-01 16:09:05

响应示例

成功 (HTTP 200):

{
  "code": 200,
  "error": "success",
  "total": 2,
  "pageNo": 0,
  "pageSize": 100,
  "currentSize": 2,
  "items": [
    {
      "uid": 1383263287,
      "requestId": "698e908943d723411eda9d41",
      "taskId": "698e908943d723411eda9d42",
      "isDir": "no",
      "url": "https://test.example.com/1235.jpg",
      "progress": 100,
      "state": "success",
      "stateDetail": "",
      "createAt": "2026-02-13 10:46:33",
      "beginAt": "2026-02-13 10:46:33",
      "endAt": "2026-02-13 10:46:35"
    },
    {
      "uid": 1383263287,
      "requestId": "698e908943d723411eda9d41",
      "taskId": "698e908943d723411eda9d43",
      "isDir": "yes",
      "url": "https://test.example.com/static/",
      "progress": 100,
      "state": "success",
      "stateDetail": "",
      "createAt": "2026-02-13 10:46:33",
      "beginAt": "2026-02-13 10:46:33",
      "endAt": "2026-02-13 10:47:35"
    }
  ]
}

state 值: "success" (完成) / "failure" (失败) / "processing" (进行中)

2.3 资源预取

基本信息

请求方法: POST
接口地址: https://fusion.qiniuapi.com/v2/tune/prefetch
用途: 提前将资源从源站拉取到 CDN 节点缓存

请求参数

参数名	类型	必填	说明	示例值
urls	array	是	文件 URL 列表，完整 http:// 或 https://	`["http://test.com/big.mp4"]`

预取仅支持文件，不支持目录。

请求示例

curl -X POST 'https://fusion.qiniuapi.com/v2/tune/prefetch' \
  -H 'Host: fusion.qiniuapi.com' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: QBox <AK>:<Sign>' \
  -d '{"urls":["http://test.example.com/large-file.jpg"]}'

响应参数

参数名	类型	说明
code	int	响应状态码
error	string	响应错误码描述
requestId	string	预取请求id，只有在任务被接受时才有值
taskIds	map[string]string	URL 对应的任务 ID，map[url]taskId
invalidUrls	string array	无效的url列表
quotaDay	int	每日的预取 url 限额
surplusDay	int	每日的当前剩余的预取url限额

响应示例

成功 (HTTP 200):

{
  "code": 200,
  "error": "success",
  "requestId": "698ee598ae4f8446dac2b967",
  "taskIds": {
    "http://test.example.com/large-file.jpg": "698ee598ae4f8446dac2b968"
  },
  "invalidUrls": null,
  "quotaDay": 100,
  "surplusDay": 93
}

2.4 预取任务查询

基本信息

请求方法: POST
接口地址: https://fusion.qiniuapi.com/v2/tune/prefetch/list
用途: 查询预取任务执行状态 (与刷新查询独立)
查询时间范围: 近 7 天

请求参数

参数名	类型	必填	说明	示例值
requestId	string	否	请求 ID	`"698ee3057911048e39e0ac8c"`
urls	array	否	按 URL 查询	`["http://test.com/a.jpg"]`
state	string	否	按状态筛选	`"success"` / `"failure"` / `"processing"`
pageNo	int	否	页码	0
pageSize	int	否	每页条数	100
startTime	string	否	开始日期	`"2026-02-10"`
endTime	string	否	结束日期	`"2026-02-13"`

可选参数不能全部为空，至少传一个。时间范围最多 7 天，startTime/endTime 缺失时默认返回近 3 天。

请求示例

curl -X POST 'https://fusion.qiniuapi.com/v2/tune/prefetch/list' \
  -H 'Host: fusion.qiniuapi.com' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: QBox <AK>:<Sign>' \
  -d '{"requestId":"698ee598ae4f8446dac2b967"}'

响应参数

参数名	类型	说明
code	int	响应状态码
error	string	响应错误码描述
requestId	string	记录所在的预取请求id
total	int	当前条件下查询的记录总数
pageNo	int	要查询的页号
pageSize	int	要返回的页长度
currentSize	int	当前实际返回的页长度
uid	string	用户id
taskId	string	任务id
isDir	string	是否目录，取值为yes／no
url	string	url
progress	int	任务进度，0-100
state	string	预取状态，取值为success／processing／failure
stateDetail	string	预取状态描述信息
midState	string	中间状态描述
createAt	string	当前记录创建时间，格式为xxxx-xx-xx xx:xx:xx，例如2015-11-01 16:05:05
beginAt	string	当前记录开始时间，格式为xxxx-xx-xx xx:xx:xx，例如2015-11-01 16:05:25
endAt	string	当前记录结束时间，格式为xxxx-xx-xx xx:xx:xx，例如2015-11-01 16:09:05

响应示例

成功 (HTTP 200):

{
    "code": 200,
    "error": "success",
    "total": 1,
    "pageNo": 0,
    "pageSize": 100,
    "currentSize": 1,
    "items": [
        {
            "uid": 1383263287,
            "requestId": "698ee598ae4f8446dac2b967",
            "taskId": "698ee598ae4f8446dac2b968",
            "isDir": "no",
            "url": "http://test.example.com/large-file.jpg",
            "progress": 100,
            "state": "success",
            "stateDetail": "",
            "midState": "success",
            "createAt": "2026-03-18 17:42:10",
            "beginAt": "2026-03-18 17:42:10",
            "endAt": "2026-03-18 17:42:21"
        }
    ]
}

3. 常见问题

3.1 专属错误码

错误码	描述	场景	解决方案
400000	无效输入	urls/dirs 为空数组	至少传 1 个 URL
400031	invalid url	URL 格式错误，非完整 http/https	检查 URL 完整格式
400032	invalid host	域名无效	确认域名已接入 CDN
400033	prefetch url limit error	预取每日配额用完	次日恢复，或控制台申请提升
400034	refresh url limit error	文件刷新每日配额用完	同上
400035	refresh dir limit error	目录刷新配额用完	同上
400036	invalid request id	请求 ID 无效	检查 requestId 拼写
400037	url has existed	URL 正在刷新/预取中	等待完成后重试
400038	refresh dir authority error	未开通目录刷新	控制台开通

3.2 最佳实践

URL 格式: 完整 http:// 或 https://，http/https 均可接受
批量提交: 官网限制单次 20 个 URL / 5 个目录，建议分批
配额感知: 响应中 urlSurplusDay 返回当日剩余配额，据此控制提交量
任务追踪: 保存 requestId，刷新用 refresh/list 查询，预取用 prefetch/list 查询，二者独立
预取场景: 大文件发布前预取，避免用户首次访问直接回源

参考: 鉴权详见鉴权指南，错误码详见公共错误码&通用约束。

以上内容是否对您有帮助？