You need to enable JavaScript to run this app.
文档中心
内容分发网络

内容分发网络

复制全文
下载 pdf
域名操作接口
AddCdnDomain - 添加域名
复制全文
下载 pdf
AddCdnDomain - 添加域名

在火山引擎内容分发网络中添加您的域名。在添加域名时,您可以设置域名的配置。

使用限制

节流限制:您每秒最多可以发送 20 个请求。

在您调用该 API 时,CDN 会对该域名做一系列检查。如果域名未通过某项检查,您会收到相应的错误消息。参见 域名准入规范。

说明

如果您要添加的域名是一个泛域名,请 提交工单。

请求说明

  • 请求方式:POST
  • 请求地址:https://cdn.volcengineapi.com/?Action=AddCdnDomain&Version=2021-03-01

公共参数

参数名称
数据类型
是否必选
参数说明
Action
String
是
接口名称。当前 API 的名称为 AddCdnDomain。
Version
String
是
接口版本。当前 API 的版本为 2021-03-01。

Body

基础配置

域名配置

参数名称
数据类型
是否必选
参数说明
示例
Domain
String
是

表示您需要添加的一个域名。主账号下最多能添加 200 个加速域名。如果您需要添加的域名数量超过 200 个,请 提交工单。

您可以添加中文域名。在指定中文名时,您必须将域名中的汉字转化为 punycode 码后再输入。 您添加的域名必须满足以下额外要求:

  • 域名长度不超过 100 个字符。

  • 域名不能包含大写字母。

  • 域名不包含这些后缀:zjgslb.com,yangyi19.com,volcgslb.com,veew-alb-cn1.com,bplgslb.com,bplslb.com,ttgslb.com。

www.example.com
ServiceType
String
是

表示业务类型。该参数有以下取值:

  • download:表示文件下载。
  • web:表示网页。
  • video:表示音视频点播。
web
ServiceRegion
String
否

表示该加速域名的加速区域。该参数有以下取值:

  • chinese_mainland:表示中国内地。
  • global:表示全球。
  • outside_chinese_mainland:表示全球(不含中国内地)。
该参数的默认值是 chinese_mainland。要指定另两个值,请 提交工单。
chinese_mainland
Project
String
否

表示该域名所归属的项目。您可以在 项目管理 页面查看已有的项目以及项目下的资源。

该参数的默认值是 default,表示名称是 default 的项目。
default
ResourceTags
Object[]
否
表示您对该域名设置的标签。您最多可以设置 10 个标签。

IPv6 加速

参数名称
数据类型
是否必选
参数说明
示例
IPv6
Object
否
表示 IPv6 配置。

源站配置

参数名称
数据类型
是否必选
参数说明
示例
Origin
Object[]
是
表示源站配置。

条件源站

参数名称
数据类型
是否必选
参数说明
示例
ConditionalOrigin
Object
否
表示 "条件源站" 特性的配置。要使用此特性,请 提交工单。

回源协议

参数名称
数据类型
是否必选
参数说明
示例
OriginProtocol
String
是

表示回源请求使用的协议。该参数有以下取值:

  • http:表示回源请求使用 HTTP 协议。

  • https:表示回源请求使用 HTTPS 协议。

  • followclient:表示回源协议与用户请求使用的协议相同。

http

源站证书校验

参数名称
数据类型
是否必选
参数说明
示例
OriginCertCheck
Object
否

表示 "源站证书校验" 特性的配置。要使用此特性,请 提交工单。

该特性启用后,CDN 会校验源站证书的合法性,包括证书是否已被吊销、证书是否由可信 CA 签发、证书与源站域名是否匹配等。CDN 内置了常见可信 CA 的根证书。

该特性还支持双向认证,使源站对 CDN 身份进行校验。您需要在 CDN 中指定相应的客户端证书。

IPv6 回源

参数名称
数据类型
是否必选
参数说明
示例
OriginIPv6
String
否

表示 "IPv6 回源" 的配置。该参数有以下取值:

  • ipv6_first:表示 CDN 始终尝试获取源站域名的 IPv6 地址。如果无法获取该 IP 地址,CDN 才尝试获取源站域名的 IPv4 地址。

  • ipv4_first:表示 CDN 始终尝试获取源站域名的 IPv4 地址。如果无法获取该 IP 地址,CDN 才尝试获取源站域名的 IPv6 地址。

  • followclient:表示 CDN 尝试获取与用户请求相同类型的 IP 地址。

该参数的默认值是 followclient。

由于海外部分 CDN 回源节点不支持向 IPv6 地址发送回源请求,该功能仅适用于位于中国内地的回源节点。
followclient

回源 Host

参数名称
数据类型
是否必选
参数说明
示例
OriginHost
String
否

如果源站服务器上有多个站点,该参数表示回源请求访问的站点域名。该参数对所有源站配置生效,但是优先级低于源站配置中 OriginHost 参数。

该参数的默认值与 Domain 相同。

如果源站是一个对象存储桶,您无需指定该参数。其默认值与源站配置中的 Address 相同。
img.example.com

加速区域

参数名称
数据类型
是否必选
参数说明
示例
ServiceRegion
String
否

表示该加速域名的加速区域。该参数有以下取值:

  • chinese_mainland:表示中国内地。
  • global:表示全球。
  • outside_chinese_mainland:表示全球(不含中国内地)。
该参数的默认值是 chinese_mainland。要指定另两个值,请 提交工单。
chinese_mainland

HTTPS 配置

HTTPS

参数名称
数据类型
是否必选
参数说明
示例
HTTPS
Object
否
表示 HTTPS 特性的配置。

HTTPS 强制跳转到 HTTP 设置

参数名称
数据类型
是否必选
参数说明
示例
HttpForcedRedirect
Object
否

表示 "HTTPS 强制跳转到 HTTP" 特性的配置。

说明

关于 HTTP 重定向至 HTTPS 的配置,参见 HTTPS 下的 ForcedRedirect 特性。HttpForcedRedirect 与 ForcedRedirect 是互斥的。也就是说,如果您配置了其中任意一个特性,就不能配置另一个。

QUIC 设置

参数名称
数据类型
是否必选
参数说明
示例
Quic
Object
否
表示 QUIC 配置。

访问控制

URL 标准化

参数名称
数据类型
是否必选
参数说明
示例
UrlNormalize
Object
否
表示 "URL 标准化" 特性的配置。

地域访问控制

参数名称
数据类型
是否必选
参数说明
示例
AreaAccessRule
Object
否
表示 "地域访问控制" 特性的配置。

禁用 HTTP Method

参数名称
数据类型
是否必选
参数说明
示例
MethodDeniedRule
Object
否
表示 "禁用 HTTP Method" 特性的配置。

IP 黑白名单

参数名称
数据类型
是否必选
参数说明
示例
IpAccessRule
Object
否

表示 "IP 黑白名单" 特性的配置。

该特性提供了两种配置方式:

  • 常规配置:指定 RuleType 和 Ip 对当前加速域名进行配置。
  • 全局配置:指定 SharedConfig 使用一个全局配置。全局配置是白名单功能。要使用此功能,请 提交工单。
您只能选择一种配置方式。

Referer 黑白名单

参数名称
数据类型
是否必选
参数说明
示例
RefererAccessRule
Object
否
表示 "Referer 黑白名单" 特性的配置。关于不同配置对请求匹配结果的影响,参见 配置示例。

UA 黑白名单

参数名称
数据类型
是否必选
参数说明
示例
UaAccessRule
Object
否
表示 "UA 黑白名单" 特性的配置。

Origin 黑白名单

参数名称
数据类型
是否必选
参数说明
示例
OriginAccessRule
Object
否
表示 "Origin 黑白名单" 特性的配置。

自定义头部黑白名单

参数名称
数据类型
是否必选
参数说明
示例
CustomizeAccessRule
Object
否
表示 "自定义头部黑白名单" 特性的配置。要使用该特性,请 提交工单。

自定义拦截规则

参数名称
数据类型
是否必选
参数说明
示例
RequestBlockRule
Object
否
表示 "自定义拦截" 特性的配置。

URL 重定向改写

参数名称
数据类型
是否必选
参数说明
示例
RedirectionRewrite
Object
否
表示 "URL 重定向改写" 特性的配置。

URL 鉴权

参数名称
数据类型
是否必选
参数说明
示例
SignedUrlAuth
Object
否
表示 "URL 鉴权" 特性的配置。

远程鉴权

参数名称
数据类型
是否必选
参数说明
示例
RemoteAuth
Object
否
表示 "远程鉴权" 特性的配置。

下载限速

参数名称
数据类型
是否必选
参数说明
示例
DownloadSpeedLimit
Object
否
表示 "下载限速" 特性的配置。

缓存配置

缓存键值

参数名称
数据类型
是否必选
参数说明
示例
CacheKey
Object[]
否

表示 "缓存键值" 特性的配置。在该配置中,您可以创建一个规则列表,说明如下:

  • 每条规则包含匹配条件配置和操作配置。
  • 列表中最多可以包含 50 条规则。
  • 规则在列表中出现的顺序表示规则的优先级。列表中第一条规则的优先级最高。
  • 当收到一个用户请求时,CDN 按规则的优先级,从高到低将规则与请求匹配。如果一条规则匹配了请求,CDN 就停止处理其余规则。

您必须在列表中添加以下默认规则,并且这条规则必须出现在列表的末尾。该默认规则用于匹配任何未能匹配其他规则的用户请求。在默认规则中,您可以调整 CacheKeyAction 的配置,但不能调整 Condition 的配置。

{
    "CacheKeyAction": {
        "CacheKeyComponents": [
            {
                "Action": "include",
                "IgnoreCase": true,
                "Object": "queryString",
                "Subobject": "*"
            }
        ]
    },
    "Condition": {
        "ConditionRule": [
            {
                "Name": "",
                "Object": "directory",
                "Operator": "match",
                "Type": "url",
                "Value": "/"
            }
        ]
    }
}

节点缓存规则

参数名称
数据类型
是否必选
参数说明
示例
Cache
Object[]
否

表示 "缓存规则" 特性的配置。该特性默认为禁用,表示不创建自定义规则。

  • 列表中最多可以包含 50 条规则。
  • 列表中规则的顺序定义了规则的优先级。列表中第一条规则的优先级最高。
  • 当收到一个用户请求时,CDN 按规则的优先级,从高到低将规则与请求匹配。如果一条规则匹配了请求,CDN 就停止处理其余规则。
CDN 中有一条 默认缓存规则,用于匹配任何未能匹配其他规则的用户请求。该默认规则始终生效,并且优先级最低。您无需在配置该特性时指定该默认规则。

状态码缓存规则

参数名称
数据类型
是否必选
参数说明
示例
NegativeCache
Object[]
否

表示 "状态码缓存" 特性的配置。在该配置中,您可以创建一个规则列表,说明如下:

  • 每条规则包含匹配条件配置和操作配置。
  • 列表中最多可以包含 50 条规则。
  • 规则在列表中出现的顺序表示规则的优先级。列表中第一条规则的优先级最高。
  • 当收到一个用户请求时,CDN 按规则的优先级,从高到低将规则与请求匹配。如果一条规则匹配了请求,CDN 就停止处理其余规则。

浏览器缓存规则

参数名称
数据类型
是否必选
参数说明
示例
BrowserCache
Object[]
否

表示 "浏览器缓存" 特性的配置。在该配置中,您可以创建一个规则列表,说明如下:

  • 每条规则包含匹配条件配置和操作配置。
  • 列表中最多可以包含 50 条规则。
  • 规则在列表中出现的顺序表示规则的优先级。列表中第一条规则的优先级最高。
  • 当收到一个用户请求时,CDN 按规则的优先级,从高到低将规则与请求匹配。如果一条规则匹配了请求,CDN 就停止处理其余规则。

HTTP 响应头设置

参数名称
数据类型
是否必选
参数说明
示例
RequestHeader
Object[]
否
表示 "回源 HTTP 请求头" 特性的配置。

自定义错误页面

参数名称
数据类型
是否必选
参数说明
示例
CustomErrorPage
Object
否
表示 "自定义错误页面" 特性的配置。

共享缓存

参数名称
数据类型
是否必选
参数说明
示例
CacheHost
Object
否

表示 "共享缓存" 特性的配置。要使用该功能,请 提交工单。

如果您要对多个加速域名配置共享缓存,您需要调用该 API 对每个加速域名配置目标域名。

Multi-range

参数名称
数据类型
是否必选
参数说明
示例
MultiRange
Object
否
表示 "多重范围(Multi-range)" 特性的配置。

离线缓存

参数名称
数据类型
是否必选
参数说明
示例
OfflineCache
Object
否
表示 "离线缓存" 特性的配置。要使用此特性,请 提交工单。

HTTP 响应头配置

参数名称
数据类型
是否必选
参数说明
示例
ResponseHeader
Object[]
否
表示 "HTTP 响应头" 特性的配置。

回源配置

Range 回源设置

参数名称
数据类型
是否必选
参数说明
示例
OriginRange
Boolean
否

表示 "回源 Range" 特性的配置。该参数有以下取值:

  • true:表示启用该特性。
  • false:表示禁用该特性。

该参数的默认值是 false。请求分片大小默认是 1 MB。

说明

如果 Range 结构体中 Switch 为 true,则该特性为启用,即使 OriginRange 为 false。

true
Range
Object
否
表示分片大小的设置。

回源超时时间设置

参数名称
数据类型
是否必选
参数说明
示例
Timeout
Object
否
表示 "回源超时时间" 特性的配置。

回源重试设置

参数名称
数据类型
是否必选
参数说明
示例
OriginRetry
Object
否
表示 "回源重试设置" 特性的配置。要使用该功能,请 提交工单。

回源重定向跟随

参数名称
数据类型
是否必选
参数说明
示例
FollowRedirect
Boolean
否

表示 "回源重定向跟随" 特性的配置。该参数有以下取值:

  • true:表示启用该特性。
  • false:表示禁用该特性。
该参数的默认值是 false。
true

回源 HTTP 请求头设置

参数名称
数据类型
是否必选
参数说明
示例
RequestHeader
Object[]
否
表示 "回源 HTTP 请求头" 特性的配置。

回源 URL 改写

参数名称
数据类型
是否必选
参数说明
示例
OriginRewrite
Object
否
表示 "回源 URL 改写" 特性的配置。

回源参数设置

参数名称
数据类型
是否必选
参数说明
示例
OriginArg
Object[]
否

表示 "回源参数" 配置的规则列表。

  • 列表中最多可以包含 50 条规则。
  • 每条规则包含一个匹配条件(Condition)和 CDN 执行操作(OriginArgAction)。
  • 列表中规则的顺序定义了规则的优先级。列表中第一条规则的优先级最高。
  • 当收到一个用户请求时,CDN 按规则的优先级,从高到低将规则与请求匹配。如果一条规则匹配了请求,CDN 就停止处理其余规则。

您必须在规则列表的最后添加以下这条默认规则。该默认规则用于匹配任何未能匹配其他规则的用户请求。您不可更改该规则中的 Condition,但可以更改 OriginArgAction 中的配置。

{
    "Condition": {
        "ConditionRule": [
            {
                "Object": "directory",
                "Operator": "match",
                "Type": "url",
                "Value": "/"
            }
        ]
    },
    "OriginArgAction": {
        "OriginArgComponents": [
            {
                "Action": "include",
                "Object": "queryString",
                "Subobject": "*"
            }
        ]
    }
}

说明

如果您加速域名的源站配置尚未升级到 新版源站配置,回源参数的配置会有以下限制:

  • 规则列表中只能包含上述这条默认规则。
  • 在这条默认规则的 OriginArgAction 中,Action 的值只能为 include 或者 exclude。

回源 SNI 设置

参数名称
数据类型
是否必选
参数说明
示例
OriginSni
Object
否
表示 "回源 SNI" 特性的配置。

源站响应头设置

参数名称
数据类型
是否必选
参数说明
示例
OriginResponseHeader
Object[]
否
表示 "源站响应头设置" 的配置。要使用该特性,请 提交工单。

内容优化

智能压缩

参数名称
数据类型
是否必选
参数说明
示例
Compression
Object
否
表示 "智能压缩" 特性的配置。

页面优化

参数名称
数据类型
是否必选
参数说明
示例
PageOptimization
Object
否
表示 "页面优化" 特性的配置。

视频拖拽

参数名称
数据类型
是否必选
参数说明
示例
VideoDrag
Object
否
表示 "视频拖拽" 特性的配置。

标准 HLS 加密改写

参数名称
数据类型
是否必选
参数说明
示例
RewriteHLS
Object
否
表示 "标准 HLS 加密改写" 特性的配置。要使用该功能,请 提交工单。

规则引擎

参数名称
数据类型
是否必选
参数说明
示例
RuleEngine
Object
否
详情参见 规则引擎配置。

返回参数

由于该 API 没有响应参数,响应正文只有包含请求元数据的 ResponseMetadata 结构体,没有 Result 结构体。

参数名称
数据类型
参数说明
示例
暂无数据

请求示例

本示例仅展示了基础配置。关于其他模块的示例以及源站配置的更多示例,参见 UpdateCdnConfig。

POST https://cdn.volcengineapi.com/?Action=AddCdnDomain&Version=2021-03-01
{
    "Domain": "www.example.com",
    "ServiceType": "web",
    "OriginProtocol": "http",
    "Origin": [
        {
            "OriginAction": {
                "OriginLines": [
                    {
                        "Address": "1.1.1.1",
                        "HttpPort": "80",
                        "HttpsPort": "443",
                        "InstanceType": "ip",
                        "OriginType": "primary",
                        "PrivateBucketAccess": false,
                        "Weight": "1"
                    }
                ]
            }
        }
    ],
    "ResourceTags": [
        {
            "Key": "hello",
            "Value": "world"
        }
    ]
}

返回示例

{
    "ResponseMetadata": {
        "RequestId": "2021121621104801021219403908010CBC",
        "Action": "AddCdnDomain",
        "Version": "2021-03-01",
        "Service": "CDN",
        "Region": "cn-north-1"
    }
}

错误码

如果响应正文的 ResponseMetadata 字段中包含 Error 字段,则表示 API 请求失败。更多关于错误码的信息,参见错误码。

最近更新时间:2026.10.08 16:07:29
这个页面对您有帮助吗?
有用
有用
无用
无用