托管 CDN 开放 API

本文档用于管理托管站点的 CDN 域名、缓存规则及刷新预热任务。调用前，先通过托管开放 API 的“获取可管理站点列表”取得 instanceCode。

所有接口均使用 POST。除路径参数外，CDN 接口都必须在查询参数中传入当前账号拥有的 instanceCode：

?instanceCode=0123456789abcdef0123456789abcdef

响应沿用统一结构。HTTP 200 只表示请求到达服务端，仍需判断响应中的 status 是否为 true。

接口列表

路径	用途	请求体
`/hcp/cdn/v1/domain/list`	获取 CDN 域名列表	无
`/hcp/cdn/v1/domain/config`	获取域名配置	至少传 `domain`
`/hcp/cdn/v1/refresh/query/{page}/{size}`	查询刷新和预热任务	可省略或 `{}`
`/hcp/cdn/v1/domain/modifyBasicConfig`	修改 IPv6 基础配置	基础配置对象
`/hcp/cdn/v1/domain/modifyCacheConfig`	修改缓存配置	缓存配置对象
`/hcp/cdn/v1/domain/modifyIpFilterConfig`	修改 IP 黑白名单	IP 过滤配置对象
`/hcp/cdn/v1/domain/modifyIpFreqLimitConfig`	修改 IP 访问限频	IP 限频配置对象
`/hcp/cdn/v1/domain/modifyOriginConfig`	修改回源超时	回源配置对象
`/hcp/cdn/v1/domain/setNoCache`	设置全路径不缓存	仅传 `domain`
`/hcp/cdn/v1/modifyRulePriorityPole/{ruleCode}`	调整缓存规则顺序	排序动作
`/hcp/cdn/v1/refresh/purgeUrls`	URL 刷新	URL 列表
`/hcp/cdn/v1/refresh/purgePaths`	目录刷新	目录列表
`/hcp/cdn/v1/refresh/pushUrls`	URL 预热	URL 列表

写请求标识

修改配置、调整规则、刷新和预热属于写请求，必须携带以下请求头：

名称	类型	必选	说明
Xn-Request-Id	string	是	16-80 位字母、数字、下划线或短横线；每个逻辑请求唯一
Xn-Request-Time	integer	是	Unix 毫秒时间戳，与服务端时间相差不能超过 10 分钟

同一个逻辑请求重试时必须复用原 Xn-Request-Id ，不能重新生成。相同请求标识的参数不同会被拒绝；请求可能处于处理中或结果不确定时，应先查询配置或任务记录，不能直接换新标识重复提交。

查询接口不需要这两个请求头。

POST 获取 CDN 域名列表

POST /hcp/cdn/v1/domain/list?instanceCode=

请求体为空。成功时 res 为当前站点的 CDN 域名数组，常用字段如下：

名称	类型	说明
domain	string	加速域名
cname	string	CDN CNAME
status	string	域名状态
area	string	加速区域

POST 获取域名配置

POST /hcp/cdn/v1/domain/config?instanceCode=

{
  "domain": "www.example.com"
}

domain 必须属于当前 instanceCode 。成功时 res 返回厂商支持的完整 CDN 配置；不同厂商可能返回不同的可选配置字段。

POST 查询刷新和预热任务

POST /hcp/cdn/v1/refresh/query//?instanceCode=

路径参数：

名称	类型	必选	说明
page	integer	是	页码，范围 1-10000
size	integer	是	每页条数，范围 1-100

不传请求体、传 {} ，或只传其他筛选条件时，默认查询当前时间往前 24 小时。也可以指定任务 ID 或时间范围：

{
  "startTime": "2026-09-14 00:00:00",
  "endTime": "2026-09-14 15:00:00",
  "keyword": "www.example.com",
  "refreshType": "purgePaths",
  "status": "done",
  "area": "mainland"
}

名称	类型	必选	说明
startTime	string	否	开始时间，格式 `yyyy-MM-dd HH:mm:ss` ，北京时间
endTime	string	否	结束时间，与 startTime 成对提供
keyword	string	否	URL 或域名关键字
refreshType	string	否	`purgeUrls`、 `purgePaths` 或 `pushUrls`
status	string	否	任务状态
area	string	否	刷新区域
taskId	string	否	厂商任务 ID；单独传入时不附加最近 24 小时限制

开始时间不能晚于结束时间。响应 res 包含 total、 elements、 page 和 size ，其中任务元素常用字段如下：

名称	类型	说明
taskId	string	任务 ID
url	string	刷新或预热目标
status	string	任务状态，例如 `process`、 `done`
refreshType	string	任务类型
flushType	string	目录刷新方式
area	string	区域
percent	integer	完成百分比，厂商未返回时为空
createTime	string	创建时间
updateTime	string	更新时间

POST 修改 IPv6 基础配置

POST /hcp/cdn/v1/domain/modifyBasicConfig?instanceCode=

{
  "domain": "www.example.com",
  "ipv6AccessSwitch": "on"
}

ipv6AccessSwitch 使用 on 或 off 。具体支持范围以域名当前 CDN 厂商为准。

POST 修改缓存配置

POST /hcp/cdn/v1/domain/modifyCacheConfig?instanceCode=

{
  "domain": "www.example.com",
  "followOriginSwitch": "off",
  "responseHeaderCacheSwitch": "off",
  "cacheRules": []
}

名称	类型	必选	说明
domain	string	是	当前站点的 CDN 域名
cacheRules	[object]	是	缓存规则，最多 100 条
responseHeaderCacheSwitch	string	否	响应头缓存开关
followOriginSwitch	string	否	是否跟随源站缓存配置

缓存规则结构及可配置字段取决于域名所使用的 CDN 厂商。修改可能覆盖或删除已有规则，调用前应先通过域名配置接口保存当前配置。

POST 修改 IP 黑白名单

POST /hcp/cdn/v1/domain/modifyIpFilterConfig?instanceCode=

{
  "domain": "www.example.com",
  "ipFilter": {
    "switch": "on",
    "filterType": "whitelist",
    "filters": ["192.0.2.10", "198.51.100.0/24"]
  }
}

ipFilter 不能为空。字段及取值以域名配置接口返回的厂商配置为准。

POST 修改 IP 访问限频

POST /hcp/cdn/v1/domain/modifyIpFreqLimitConfig?instanceCode=

{
  "domain": "www.example.com",
  "ipFreqLimit": {
    "switch": "on",
    "Qps": 20
  }
}

ipFreqLimit 不能为空。字段及取值以域名配置接口返回的厂商配置为准。

POST 修改回源超时

POST /hcp/cdn/v1/domain/modifyOriginConfig?instanceCode=

{
  "domain": "www.example.com",
  "connectTimeout": 5,
  "receiveTimeout": 10
}

名称	类型	必选	说明
domain	string	是	当前站点的 CDN 域名
connectTimeout	integer	否	回源连接超时秒数
receiveTimeout	integer	否	回源读取超时秒数

POST 设置全路径不缓存

POST /hcp/cdn/v1/domain/setNoCache?instanceCode=

{
  "domain": "www.example.com"
}

该操作关闭跟随源站缓存，并设置全路径不缓存规则。执行前应保存当前缓存配置，以便需要时恢复。

POST 调整缓存规则顺序

POST /hcp/cdn/v1/modifyRulePriorityPole/?instanceCode=

{
  "pole": "TOP"
}

pole 支持 TOP、 BOTTOM、 UP、 DOWN 。也可以使用字段名 priority。 ruleCode 必须属于当前站点的缓存规则。

POST URL 刷新

POST /hcp/cdn/v1/refresh/purgeUrls?instanceCode=

{
  "domain": "www.example.com",
  "urls": [
    "https://www.example.com/index.html"
  ],
  "urlEncode": false,
  "area": "mainland"
}

POST 目录刷新

POST /hcp/cdn/v1/refresh/purgePaths?instanceCode=

{
  "domain": "www.example.com",
  "paths": [
    "https://www.example.com/assets/"
  ],
  "flushType": "delete",
  "urlEncode": false,
  "area": "mainland"
}

flushType=delete 清除目录下全部缓存资源；具体取值和行为以 CDN 厂商支持范围为准。以域名根地址作为目录可提交全站缓存清理。

POST URL 预热

POST /hcp/cdn/v1/refresh/pushUrls?instanceCode=

{
  "domain": "www.example.com",
  "urls": [
    "https://www.example.com/index.html"
  ],
  "urlEncode": false,
  "area": "mainland"
}

刷新和预热请求每次必须提交 1-100 个目标。每个目标必须是当前 domain 下完整的 HTTP 或 HTTPS URL，不接受其他域名、用户名密码或 URL 片段。刷新或预热提交后无法撤销；提交接口成功时 res 为空，可通过任务查询接口确认执行状态。

错误处理

业务失败示例：

{
  "status": false,
  "code": "400",
  "msg": "CDN 操作失败，请查询状态或联系技术支持",
  "res": null
}

常见失败原因包括：站点不属于当前账号、服务状态不可用、商品未开通 CDN 能力、域名不属于当前站点、请求参数错误、写请求标识失效，以及 CDN 厂商暂时不可用。

Last modified: 18 September 2026