查询预热状态接口
更新时间：2026-03-26
接口
本接口用于查询指定条件的预热任务状态，每次最多返回100条记录。
请求接口
| Method | Path | 说明 |
|---|---|---|
| GET | /v2/geo/cache/prefetch | 查询预热缓存状态接口 |
请求参数
| 参数 | 类型 | 可选 | 说明 |
|---|---|---|---|
| site | String | 必选 | 查询预热任务的站点。 |
| id | String | 可选 | 预热任务 id。 |
| startTime | Timestamp | 可选 | 查询的时间范围起始值。默认为endTime前推 24 小时，UTC 时间，endTime 与 startTime 最大时间跨度为 30 天。 |
| endTime | Timestamp | 可选 | 查询的时间范围结束值。默认为当前时间，UTC 时间。 |
| marker | String | 可选 | 用户上次调用本接口返回的 nextMarker 值，作为本次查询的起点。注：传该参数时，时间参数和上次查询保持一致。 |
注：当指定预热任务id查询时，返回该任务所有记录。无需指定时间，不支持 marker 参数。
响应码
| HTTP Status Code | 说明 |
|---|---|
| 200 | 查询预热状态成功 |
响应体
| 参数 | 类型 | 说明 |
|---|---|---|
| details | PrefetchStatus[] | 提交的预热任务详情。 |
| isTruncated | Bool | true 表示该查询范围内后面还有数据，false 表示已经是最后一页。 |
| nextMarker | String | 当 isTruncated 为false时，该字段不出现。用户通过在下次调用本接口时指定该 marker 标记来获取后续的列表。 |
PrefetchStatus 类型如下
| 参数 | 类型 | 说明 |
|---|---|---|
| status | String | 其合法值为waiting、in-progress、completed、failed。 |
| task | PrefetchTask[] | 提交的缓存预热任务的信息。 |
| createdAt | Timestamp | 表示预热任务的创建时间，UTC时间。 |
| startedAt | Timestamp | 表示预热任务开始执行的时间，UTC时间。 |
| finishedAt | Timestamp | 表示预热任务的结束时间，UTC时间。结束时取值可能是 Completed 或 Failed，如果任务未结束，则不返回该项。 |
| operator | String | 提交缓存预热任务的用户ID。 |
| progress | Int | 表示缓存预热任务的进度百分比。 |
| reason | String | 预热失败的报错信息。 |
| id | String | 单个 url 的任务ID。 |
PrefetchTask 类型如下
| 参数 | 类型 | 说明 |
|---|---|---|
| url | String | 提交缓存预热任务的url。 |
请求示例1: 按照时间范围和站点查询
Plain Text
1GET /v2/geo/cache/prefetch?site=test.com&startTime=2025-11-10T02:00:00Z&endTime=2025-11-11T02:00:00Z HTTP/1.1
2Host: geo.baidubce.com
3Authorization: xxx
4Content-Type: application/json;charset=utf-8
5Accept-Encoding: gzip请求示例2: 按照预热任务id查询
Plain Text
1GET /v2/geo/cache/prefetch?site=test.com&id=xxx HTTP/1.1
2Host: geo.baidubce.com
3Authorization: xxx
4Content-Type: application/json;charset=utf-8
5Accept-Encoding: gzip响应示例1: 只有一页的返回结果
Plain Text
1HTTP/1.1 200 OK
2Server: nginx/1.16.1
3Content-Type: application/json; charset=utf-8
4Transfer-Encoding: chunked
5Connection: keep-alive
6
7{
8 "details": [
9 {
10 "task": {
11 "url": "http://1.test.com/test.png"
12 },
13 "createdAt": "2025-11-10T02:50:39Z",
14 "startedAt": "2025-11-10T02:50:39Z",
15 "progress": 100,
16 "status": "failed",
17 "reason": "Other Error",
18 "operator": "xxx",
19 "id": "xxx"
20 }
21 ],
22 "isTruncated": false
23}响应示例2: 返回结果有多页时
Plain Text
1HTTP/1.1 200 OK
2Server: nginx/1.16.1
3Content-Type: application/json; charset=utf-8
4Transfer-Encoding: chunked
5Connection: keep-alive
6
7{
8 "details": [
9 {
10 "task": {
11 "url": "http://1.test.com/test1.png"
12 },
13 "createdAt": "2025-11-10T02:50:39Z",
14 "startedAt": "2025-11-10T02:50:39Z",
15 "progress": 100,
16 "status": "completed",
17 "operator": "xxx",
18 "id": "xxx"
19 }, {
20 "task": {
21 "url": "http://1.test.com/test2.png"
22 },
23 "createdAt": "2025-11-10T02:50:39Z",
24 "startedAt": "2025-11-10T02:50:39Z",
25 "progress": 100,
26 "status": "completed",
27 "operator": "xxx",
28 "id": "xxx"
29 }
30 ],
31 "isTruncated": true,
32 "nextMarker": "xxx"
33}评价此篇文章