CDN

    • CDN > API 文档 > 域名管理

    域名管理

    最近更新时间: 2026-03-25 18:43:24

    1. 快速查阅区

    1.1 核心接口概览

    接口功能 请求方法 接口路径 核心参数 成功响应
    创建域名 POST /domain/<Name> type、geoCover、platform、source、cache {"code":200}
    创建泛子域名 POST /pandomain/<Name> pareDomain、source、testURLPath {"code":200}
    下线域名 POST /domain/<Name>/offline - {"code":200} (400013=已下线)
    上线域名 POST /domain/<Name>/online - {"code":200} (400317=非已下线)
    删除域名 DELETE /domain/<Name> - {"code":200} (须先下线)
    获取域名信息 GET /domain/<Name> - 直接返回域名对象 (无 code 包装)
    获取域名列表 GET /domain marker、limit {"domains":[...],"marker":"..."}

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

    1.2 核心约束

    • 请求域名: api.qiniu.com
    • 鉴权方式: Qiniu 鉴权（详见 鉴权指南）
    • QPS限制: 10 QPS
    • 生效时间: 创建/上线操作 5-10 分钟生效，其余操作立即生效

    2. 详细接口说明

    2.1 创建域名

    基本信息

    • 请求方法: POST
    • 接口地址: https://api.qiniu.com/domain/<Name>
    • 幂等性: 非幂等
    • 前置条件: 国内/全球加速域名需完成ICP备案

    请求参数

    参数名 类型 必填 说明 示例值
    type string 是 域名类型 normal (普通域名)/ wildcard (泛域名)
    platform string 是 业务类型 web (静态网站) / vod (音视频点播)/ download (文件下载)/ dynamic (动态加速)
    geoCover string 是 加速区域 china (中国大陆, 需备案) / foreign (海外, 免备案) / global (全球, 需备案)
    protocol string 是 加速协议 http / https
    source object 是 回源配置 见下方说明
    cache object 是 缓存规则 必须包含cache配置，否则返回 400309
    testURLPath string 是 源站测试路径 /test.jpg (以 / 开头, 源站需返回 200)
    registerNo string 条件 ICP备案号 geoCover=china/global 时必填

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

    {
    "sourceType": "qiniuBucket",
    "sourceQiniuBucket": "your-bucket-name"
}

    其他源站配置参考修改源站配置

    缓存规则 (cache) - 必传, 须含全局兜底:

    {
    "cacheControls": [
        {
            "time": 1,
            "timeunit": 5,
            "type": "all",
            "rule": "*"
        }
    ]
}

    不配置cache规则会返回 {"code":400309,"error":"缓存规则未设置全局或者为遵循源站"}。

    请求示例

    curl -X POST 'https://api.qiniu.com/domain/test.example.com' \
  -H 'Host: api.qiniu.com' \
  -H 'Content-Type: application/json' \
  -H 'X-Qiniu-Date: 20260213T120000Z' \
  -H 'Authorization: Qiniu <AK>:<Sign>' \
  -d '{"type":"normal","platform":"web","geoCover":"foreign","protocol":"http","source":{"sourceType":"qiniuBucket","sourceQiniuBucket":"test-bucket"},"cache":{"cacheControls":[{"time":1,"timeunit":5,"type":"all","rule":"*"}]},"testURLPath":"/test.jpg"}'

    响应示例

    成功 (HTTP 200):

    {
    "code": 200
}

    创建成功后通过 GET /domain/<Name> 获取 cname 等详细信息。

    失败:

    #示例1
{
    "code": 400309,
    "error": "缓存规则未设置全局或者为遵循源站"
}
#示例2
{
    "code": 400020,
    "error": "域名未备案"
}
#示例3
{
    "code": 400062,
    "error": "重复域名"
}

    2.2 创建泛子域名

    基本信息

    • 请求方法: POST
    • 接口地址: https://api.qiniu.com/pandomain/<Name>
    • 前置条件: 父泛域名必须已创建并上线

    请求参数

    参数名 类型 必填 说明 示例值
    Name string 是 域名（支持一级泛子域名） testqiniu.example.com
    pareDomain string 是 泛子域名所属的泛域名 .example.com
    source object 是 回源配置 同创建域名
    testURLPath string 是 源站测试路径 /test.jpg

    重要限制

    • 仅支持一级子域名（如 app.example.com）
    • 不支持多级嵌套（如 x.app.example.com）
    • 父泛域名、泛子域名、存储桶必须归属同一账号

    请求示例

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

    响应示例

    成功 (HTTP 200):

    {
    "code": 200
}

    失败:

    #示例1
{
    "code": 400095,
    "error": "未知的父域名"
}
#示例2
{
    "code": 400412,
    "error": "无效的泛子域名"
}

    2.3 域名状态管理

    状态流转

    创建 → processing → success(online) ←→ offline → (可删除)
    操作 成功 已处于目标状态 正在处理中 前置状态不满足
    下线 {"code":200} 400013 重复操作 400030 -
    上线 {"code":200} - 400030 400317 非已下线
    删除 {"code":200} - 400030 400317 须先下线

    400030「正在处理中」表示上一操作 (创建/上下线) 尚未完成，需等待 5-10 分钟后重试。

    下线域名

    curl -X POST 'https://api.qiniu.com/domain/test.example.com/offline' \
  -H 'Host: api.qiniu.com' \
  -H 'Content-Type: application/json' \
  -H 'X-Qiniu-Date: 20260213T120000Z' \
  -H 'Authorization: Qiniu <AK>:<Sign>'

    响应:

    {
    "code": 200
}

    上线域名

    curl -X POST 'https://api.qiniu.com/domain/test.example.com/online' \
  -H 'Host: api.qiniu.com' \
  -H 'Content-Type: application/json' \
  -H 'X-Qiniu-Date: 20260213T120000Z' \
  -H 'Authorization: Qiniu <AK>:<Sign>'

    响应:

    {
    "code": 200
}

    删除域名

    前置条件: 域名必须处于下线状态，否则返回 400317

    curl -X DELETE 'https://api.qiniu.com/domain/test.example.com' \
  -H 'Host: api.qiniu.com' \
  -H 'Content-Type: application/json' \
  -H 'X-Qiniu-Date: 20260213T120000Z' \
  -H 'Authorization: Qiniu <AK>:<Sign>'

    响应:

    {
    "code": 200
}

    2.4 域名查询

    获取域名信息

    curl -X GET 'https://api.qiniu.com/domain/test.example.com' \
  -H 'Host: api.qiniu.com' \
  -H 'Content-Type: application/json' \
  -H 'X-Qiniu-Date: 20260213T120000Z' \
  -H 'Authorization: Qiniu <AK>:<Sign>'

    响应示例 (HTTP 200, 直接返回域名对象, 无 code 包装):

    {
  "name": "test.example.com",
  "pareDomain": ".example.com",
  "type": "normal",
  "cname": "test-example-com-xxxx.qiniudns.com",
  "testURLPath": "qiniu_do_not_delete.gif",
  "protocol": "http",
  "platform": "web",
  "product": "cdn",
  "geoCover": "china",
  "operationType": "create_domain",
  "operatingState": "success",
  "operatingStateDesc": "",
  "freezeType": "notIcp",
  "createAt": "2017-08-10T12:20:12.046Z",
  "modifyAt": "2017-08-10T12:20:42.979Z",
  "source": {  "sourceType": "qiniuBucket", "sourceQiniuBucket": "..."  },
  "cache": {  "cacheControls": [...],  "ignoreParam": true  },
  "referer": { ... },
  "https": { ... },
  "ipACL": { ... },
  "uaACL": { ... },
  "timeACL": { ... },
  "bsauth": { ... },
  "tagList": None,
  "ipTypes": 3,
  "operTaskId": "",
  "operTaskType": "",
  "operTaskErrCode": 0
}

    响应参数

    参数 类型 说明
    name string 加速域名
    PareDomain string 父域名,属于泛子域名字段
    cname string 创建域名成功后七牛生成的域名，用户需要把 name cname 到这个域名
    type string normal (普通域名)/ wildcard (泛域名)
    platform string 业务类型, web (静态网站) / vod (音视频点播)/ download (文件下载)/ dynamic (动态加速)
    product string 产品类型 , cdn(静态加速)/dcdn(全站加速)
    geoCover string 加速区域 , china (中国大陆, 需备案) / foreign (海外, 免备案) / global (全球, 需备案)
    protocol string 加速协议 , http / https
    operatingState string 域名状态 , processing创建状态，success成功状态
    CreateAt string 域名创建时间，格式:RFC3339
    ModifyAt string 域名最后一次修改时间，格式:RFC3339
    freezeType string 域名冻结类型,illegal违法违规、notIcp未备案、accountFrozen账号冻结、other其他
    Https Object Https结构请参考 HTTPS
    cache object Cache结构请参考 缓存策略
    Referer object Referer结构请参考 referer防盗链
    ipACL object IPACL结构请参考 ip黑白名单
    uaACL object UAACL结构请参考 ua黑白名单
    timeACL object TimeACL结构请参考 时间戳防盗链
    bsauth object Bsauth结构请参考 回源鉴权
    source object Source结构请参考 回源配置
    operationtype string 域名最近一次操作类型: create_domain/offline_domain/online_domain/ modify_source/modify_referer/modify_cache/ freeze_domain/unfreeze_domain/modify_timeacl(修改时间戳防盗链)/ modify_https_crt/sslize(升级HTTPS)/modify_bsauth(修改回源鉴权) /offline_bsauth(删除回源鉴权)
    operatingstate string 域名最近一次的操作状态: processing/success/failed/frozen/offlined
    operatingstateDesc string 域名最近一次的操作状态的描述
    iptypes uint IP协议：仅允许ipv4访问，取值为1；同时允许ipv4/ipv6访问，取值为3。
    taglist []string 域名的标签列表（废弃）
    operTaskId string 可操作域名任务ID
    operTaskType string 域名任务可操作类型，""-无可操作，“redo”-重试，“abandon”-回滚，“all”-重试/回滚
    operTaskErrCode string 域名任务错误码

    获取域名列表

    curl -X GET 'https://api.qiniu.com/domain?types=<Types>&certId=<CertId>&sourceTypes=<SourceTypes>&sourceQiniuBucket=<SourceQiniuBucket>&sourceIp=<SourceIp>&marker=<Marker>&limit=<Limit> \
  -H 'Host: api.qiniu.com' \
  -H 'Content-Type: application/json' \
  -H 'X-Qiniu-Date: 20260213T120000Z' \
  -H 'Authorization: Qiniu <AK>:<Sign>'

    请求参数

    参数 类型 含义
    Types []string 域名类型，可选normal（普通域名）、wildcard（泛域名）、pan（泛子域名）、test（测试域名）中的一个或多个，不填默认查询全部域名。
    CertId string 证书ID，不填默认查询全部域名。
    SourceTypes []string 回源类型，可选domain、ip、qiniuBucket、advanced中的一个或多个，不填默认查询全部域名；如果指定了SourceQiniuBucket参数，SourceTypes只能指定为qiniuBucket一种回源类型，否则SourceQiniuBucket参数将不生效；如果指定了SourceIp参数，SourceTypes只能指定为ip一种回源类型，否则SourceIp参数将不生效；同时获取多种回源类型域名的请求url示例：http://api.qiniu.com/domain?sourceTypes=domain&sourceTypes=ip。
    SourceQiniuBucket string 七牛存储空间名称，不填默认查询全部域名。请求url示例：http://api.qiniu.com/domain?sourceTypes=qiniuBucket&sourceQiniuBucket=test。
    SourceIp string 回源IP, 不填默认查询全部域名。请求url示例：http://api.qiniu.com/domain?sourceTypes=ip&sourceIp=1.1.1.1。
    Marker string 用于标示从哪个位置开始获取域名列表，不填或空表示从头开始。
    Limit int 返回的最大域名个数。1~1000, 不填默认10

    响应示例 (HTTP 200, 无 code 包装):

    {
  "domains": [
    {
      "name": "test.example.com",
      "cname": "test-example-com-xxxx.qiniudns.com",
      "type": "normal",
      "protocol": "http",
      "geoCover": "foreign",
      "operatingState": "success"
    }
  ],
  "marker": "MTc2NTM3MTY5NDE1MzAwMDAwMA=="
}

    3. 常见问题

    3.1 专属错误码

    错误码 描述 场景 解决方案
    400013 重复操作 域名已处于目标状态 (如已下线再下线) 无需处理
    400020 域名未备案 geoCover=china/global 完成 ICP 备案，或改用 foreign
    400030 正在处理中 上一操作未完成 等待 5-10 分钟后重试
    400041 源站测试路径不可访问 创建时 testURLPath 不可达 确保路径以 / 开头，源站返回 200
    400062 重复域名 域名已存在 无需重复创建
    400095 未知的父域名 创建泛子域名 检查 pareDomain 格式 (以 . 开头)
    400309 缓存规则未设置全局 创建时缺 cache 全局兜底 cache.cacheControls 须含 type=all
    400317 非已下线的域名 删除/上线未下线域名 须先下线再操作
    400412 无效的泛子域名 泛子域名格式错误 仅支持一级子域名

    3.2 最佳实践

    • 创建域名: cache 全局兜底规则必传，geoCover=foreign 可免备案
    • 域名创建后: 立即配置 DNS 解析指向 cname，5-10 分钟生效
    • 状态感知: 写操作前查询 operatingState，避免 400030 (处理中)
    • 删除操作: 先下线再删除，避免 400317
    • 响应格式: GET 域名接口直接返回域名对象，无 code 包装层
    • 泛子域名: 与父泛域名同账号，仅支持一级子域名

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

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