CDN

    • CDN > API 文档 > 域名管理

    域名管理

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

    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",
  "cname": "test-example-com-xxxx.qiniudns.com",
  "type": "normal",
  "platform": "web",
  "geoCover": "foreign",
  "protocol": "http",
  "operatingState": "success",
  "createAt": "2026-02-13T04:55:32.112Z",
  "modifyAt": "2026-02-13T04:55:54.937Z",
  "source": {"sourceType": "qiniuBucket", "sourceQiniuBucket": "..."},
  "cache": {"cacheControls": [...], "ignoreParam": true},
  "referer": {...},
  "https": {...}
}

    返回域名全量配置 (48 个字段), 含 source、cache、referer、https、timeACL、ipACL 等。

    获取域名列表

    curl -X GET 'https://api.qiniu.com/domain?marker=&limit=20' \
  -H 'Host: api.qiniu.com' \
  -H 'Content-Type: application/json' \
  -H 'X-Qiniu-Date: 20260213T120000Z' \
  -H 'Authorization: Qiniu <AK>:<Sign>'

    分页参数 (URL Query):

    • marker: 分页标记（首次查询传空字符串）
    • limit: 每页数量（1-1000，默认 20）

    响应示例 (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 包装层
    • 泛子域名: 与父泛域名同账号，仅支持一级子域名

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

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