1. 快速查阅区

1.1 核心接口概览

注：<Name>为加速服务域名

1.2 核心约束

• 请求域名: api.qiniu.com
• 鉴权方式: Qiniu 鉴权（详见 鉴权指南）
• QPS限制: 10 QPS
• 生效时间: 所有配置修改需要 5-10 分钟生效

2. 详细接口说明

2.1 修改加速区域

基本信息

• 请求方法: PUT
• 接口地址: https://api.qiniu.com/domain/<Name>/geocover
• 生效时间: 5-10 分钟
• 前置条件: geoCover 为 china 和 global 时域名需在中国大陆已备案

请求参数

请求示例

curl -X PUT 'https://api.qiniu.com/domain/test.example.com/geocover' \
  -H 'Host: api.qiniu.com' \
  -H 'Content-Type: application/json' \
  -H 'X-Qiniu-Date: 20260213T120000Z' \
  -H 'Authorization: Qiniu <AK>:<Sign>' \
  -d '{"geoCover":"global"}'

2.2 修改源站配置

基本信息

• 请求方法: PUT
• 接口地址: https://api.qiniu.com/domain/<Name>/source

请求参数

回源配置示例 (七牛存储源):

{
  "sourceType": "qiniuBucket",
  "sourceQiniuBucket": "your-bucket-name",
  "testURLPath": "/1235.jpg"
}

回源配置示例 (域名源站):

{
  "sourceType": "domain",
  "sourceDomain": "origin.example.com",
  "sourceProtocol": "http",
  "testURLPath": "/1235.jpg"
}

回源配置示例 (IP源站):

{
  "sourceType": "ip",
  "sourceIPs": ["1.1.1.1","2.2.2.2"],
  "sourceProtocol": "http",
  "testURLPath": "/1235.jpg"
}

回源配置示例 (高级源站):

{
  "sourceType": "advanced",
  "sourceURLScheme": "http",
  "advancedSources": [
        {
            "addr": "1.1.1.1:8080",
            "weight": 1,
            "backup": false
        },
        {
            "addr": "2.2.2.2:8888",
            "weight": 2,
            "backup": true
        }
    ],
    "testURLPath": "/path/1235.jpg"
}

请求示例

curl -X PUT 'https://api.qiniu.com/domain/test.example.com/source' \
  -H 'Host: api.qiniu.com' \
  -H 'Content-Type: application/json' \
  -H 'X-Qiniu-Date: 20260213T120000Z' \
  -H 'Authorization: Qiniu <AK>:<Sign>' \
  -d '{"sourceType":"qiniuBucket","sourceQiniuBucket":"new-bucket","testURLPath":"/1235.jpg"}'

2.3 修改 Range 回源

基本信息

• 请求方法: PUT
• 接口地址: https://api.qiniu.com/domain/<Name>/range

请求参数

请求体示例:

{
    "enable": "off"
}

请求示例

curl -X PUT 'https://api.qiniu.com/domain/test.example.com/range' \
  -H 'Host: api.qiniu.com' \
  -H 'Content-Type: application/json' \
  -H 'X-Qiniu-Date: 20260213T120000Z' \
  -H 'Authorization: Qiniu <AK>:<Sign>' \
  -d '{"enable":"off"}'

响应示例

成功 (HTTP 200):

{
    "code": 200
}

失败 (无改动):

{
    "code": 400910,
    "error": "没有改动不能提交"
}

2.4 修改回源超时

基本信息

• 请求方法: PUT
• 接口地址: https://api.qiniu.com/domain/<Name>/sourcetimeout

请求参数

请求结构

{
    "sourceConnTimeout": <SourceConnTimeout>,
    "sourceReadTimeout": <SourceReadTimeout>
}

响应结构

{
    sourceTimeout: {
        "sourceConnTimeout": <SourceConnTimeout>,
        "sourceReadTimeout": <SourceReadTimeout>
    }
}

2.5 修改缓存规则

基本信息

• 请求方法: PUT
• 接口地址: https://api.qiniu.com/domain/<Name>/cache

请求参数

Body 直接传 cacheControls + ignoreParam，不包 cache 层。

cacheControls 数组中每个元素的字段:

顶层参数:

修改缓存时若缺少 type=all 全局规则，服务端会自动追加默认全局兜底。

缓存规则配置示例:

{
    "cacheControls": [
        {
            "time": 1,
            "timeunit": 2,
            "type": "path",
            "rule": "/live"
        },
        {
            "time": 2,
            "timeunit": 3,
            "type": "suffix",
            "rule": ".jpg"
        },
        {
            "time": 3,
            "timeunit": 0,
            "type": "all",
            "rule": "*"
        }
    ],
    "ignoreParam": true,
    "ignoreParams": ["type","key"],
    "includeParams": ["sourcepath","taskid"]
}

请求示例

curl -X PUT 'https://api.qiniu.com/domain/test.example.com/cache' \
  -H 'Host: api.qiniu.com' \
  -H 'Content-Type: application/json' \
  -H 'X-Qiniu-Date: 20260213T120000Z' \
  -H 'Authorization: Qiniu <AK>:<Sign>' \
  -d '{"cacheControls":[{"time":1,"timeunit":2,"type":"path","rule":"/live"},{"time":2,"timeunit":3,"type":"suffix","rule":".jpg"},{"time":3,"timeunit":0,"type":"all","rule":"*"}],"ignoreParam":true,"ignoreParams": ["type","key"],"includeParams": ["sourcepath","taskid"]}'

响应示例

成功 (HTTP 200):

{
    "code": 200
}

失败 (用错字段名):

{
    "code": 400309,
    "error": "缓存规则未设置全局或者为遵循源站"
}

2.6 修改响应头

基本信息

• 请求方法: PUT
• 接口地址: https://api.qiniu.com/domain/<Name>/respheader

请求参数

响应头配置示例:

{
  "responseHeaderControls": [
    {
      "op": "set",     
      "key": "Cache-Control",
      "value": "max-age=3600"
    },
    {
      "op": "set",
      "key": "Access-Control-Allow-Origin",
      "value": "*"
    }
  ]
}

2.7 开启 HTTPS

基本信息

• 请求方法: PUT
• 接口地址: https://api.qiniu.com/domain/<Name>/sslize
• 前置条件: 已上传有效的SSL证书

请求参数

SSL配置示例:

{
   "certId": "your-cert-id",
   "forceHttps": true,
   "http2Enable": true,
   "tlsVersions": "TLSv1.0"
}

请求示例

curl -X PUT 'https://api.qiniu.com/domain/test.example.com/sslize' \
  -H 'Host: api.qiniu.com' \
  -H 'Content-Type: application/json' \
  -H 'X-Qiniu-Date: 20260213T120000Z' \
  -H 'Authorization: Qiniu <AK>:<Sign>' \
  -d '{"certId":"abcdef1234567890","forceHttps":true,"http2Enable":true,"tlsVersions":"TLSv1.0"}'

2.8 修改 HTTPS 配置

基本信息

• 请求方法: PUT
• 接口地址: https://api.qiniu.com/domain/<Name>/httpsconf

请求参数

SSL证书修改示例:

{
    "certId": "update-cert-id",
    "forceHttps": true,
    "http2Enable": true,
    "tlsVersions": "TLSv1.0"
}

2.9 配置 Referer 防盗链

基本信息

• 请求方法: PUT
• 接口地址: https://api.qiniu.com/domain/<Name>/referer

请求参数

Referer防盗链配置示例:

{
    "refererType": "white",
    "refererValues": [
        "*.example.com",
        "www.trusted.com"
    ],
    "nullReferer": true
}

2.10 配置 IP 黑白名单

基本信息

• 请求方法: PUT
• 接口地址: https://api.qiniu.com/domain/<Name>/ipacl

请求参数

IP黑白名单配置示例:

{
    "ipACLType": "black",
    "ipACLValues": [
        "192.168.1.0/24",
        "172.168.2.50"
    ]
}

2.11 配置 UA 黑白名单

基本信息

• 请求方法: PUT
• 接口地址: https://api.qiniu.com/domain/<Name>/uaacl

请求参数

UA黑白名单配置示例:

{
	"enable": "on",
	"ruleType": "black",
	"userAgent":["Mozilla/5.0 (Macintosh"]
}

2.12 配置时间戳防盗链

基本信息

• 请求方法: PUT
• 接口地址: https://api.qiniu.com/domain/<Name>/timeacl
• 互斥配置: 不能与回源鉴权同时启用

请求参数

时间戳防盗链配置示例:

{
    "enable": true,
    "timeACLKeys": [
        "your-secret-key-1",
        "your-secret-key-2"
    ],
    "checkUrl": "https://test.example.com/test/test.jpg?sign=<SIGN>&t=<T>"
}

2.13 配置回源鉴权

基本信息

• 请求方法: PUT
• 接口地址: https://api.qiniu.com/domain/<Name>/bsauth

请求参数

回源鉴权配置示例:

{
    "enable": true,
    "method": "GET",
    "timeLimit": 5000,
    "userAuthUrl": "https://auth.example.com/verify",
    "strict": false,
    "successStatusCode": 200,
    "failureStatusCode": 403
}

3. 常见问题

3.1 专属错误码

3.2 最佳实践

• 配置生效时间: 所有配置修改需要 5-10 分钟生效，避免频繁调用
• 增量修改: 可以只传需要修改的配置项，未传项保留原有配置

提示: 详细的鉴权签名生成方法请参考 鉴权指南,错误码详细说明请参考 公共错误码&通用约束。