文档中心 API文档 新建加速项目

新建加速项目

更新时间:2023-04-04 20:45:49

适用产品

CDN Pro

接口描述

创建加速项目,在加速项目中定义需要部署到CDN Pro服务器的一个或多个加速域名的配置。

推荐使用 Open API在线调试

Open API在线调试功能提供可视化界面在线调试API、支持生成代码示例、快速检索查看API文档等能力。前往调试

请求参数

Body 参数

参数名称描述
*nameString
加速项目的名称。
*legacyTypeString
取值范围: wsapro,webpro,vodpro,downloadpro 服务类型,即全站加速,网页加速,点播加速及下载加速。
descriptionString
取值范围: <= 250 字符 加速项目的描述。
*versionObject
描述加速项目的所有配置信息。
descriptionString
版本描述。
cacheKeyHostnameString
取值范围: <= 80 字符 ^[a-z.-_]+ 用于缓存键(Cache Key)的主机名必须是由小写字母、数字、点、连字符和下划线组成的字符串。如果未指定,默认将使用传入的Host请求头值,并且此加速项目中的不同加速域名之间不共享缓存。
hostnamesList
与加速项目关联的加速域名。必须是FQDN完全限定域名(如 www.domain.com),或泛域名(如*.domain.com)。 同一个加速域名在同一时间只能存在于一个已部署的加速项目中,但泛域名可以与关联的完全限定域名一同部署。
realTimeLogObject
此可选字段用来配置发送消息通知(即实时日志)到您的远程服务器。当有客户端请求访问您的加速域名时,将触发通知。这是高级功能,如果您需要此功能,请联系我们的技术支持开通。
*logUrlString
接收通知的服务器URL地址。必须以'http'或'https'开头。服务器须支持POST方法。这是必填字段。
sampleRateInteger
默认值: 1 取值范围: [ 1 .. 65536 ] 采样率。介于[1, 65536]之间的整数。n表示每n个边缘请求发送1条通知。1表示每个边缘请求都会发送。这是可选字段。默认值为1。
escapeString
取值范围: json,none 指定json以开启变量中的json字符转义。如果要禁用转义则指定none。
formatString
该字段用来定义要发送到远程服务器的通知的格式。通知正文可以包括任何能在HTTP POST请求体中发送的可打印文本。这是必填字段。 可以使用以下内置变量定义通知的格式。发送通知时,它们将被替换为实际值。
变量名称描述
$body_bytes_sent响应体大小。
$bytes_sent响应的大小,包括响应体、响应头和响应行。
$client_country_code客户端请求来源国家,以ISO 3166-1国家代码表示。例如'US'。如果国家/地区未知,则返回'ZZ'。
$client_real_ip客户端请求的IP地址。
$cookie_x获取某个cookie。例如,指定$cookie_account可获取名为'account'的cookie值。
$http_x从原始请求中获取某个HTTP请求头。请求头名称需转换为小写,并用下划线替换连字符。例如,指定$http_user_agent来获取User-Agent的值。
$msec当前unix时间,以毫秒为单位。
$qtl_req_id请求的唯一标识符。
$request_uriHTTP请求URI。
$request_method用于访问源站的HTTP请求方法。
$request_time响应时间,以毫秒为单位。这是从接收到请求的第一个字节到服务端响应最后一个字节之间的时间。
$sc_completed1表示对象的最后一个字节已返回给用户,否则为0。
$sc_initial1表示对象的第一个字节已返回给用户,否则为0。
$scheme表示用户请求的协议('http'或'https')。
$sent_http_content_length原始文件大小。
$sent_http_x获取在对客户端响应中某个HTTP响应头的值。响应头名称需转换为小写,并用下划线替换连字符。例如,$sent_http_etag可获取ETag头的值。
$server_addr为用户请求提供服务的边缘节点的IP地址。
$server_protocol表示用户请求中使用的HTTP版本,可以是'HTTP/1.0'、'HTTP/1.1'或'HTTP/2.0'。
$ssl_cipher表示用于TLS(SSL)连接的加密算法套件。
$ssl_server_name客户端发起TLS(SSL)连接所要连接的域名。仅由支持SNI(Server Name Indication)的客户端发送。
$ssl_protocol表示用于TLS(SSL)连接的TLS版本。例如,'SSLv3'、'TLSv1'、'TLSv1.1'、'TLSv1.2'和'unknown'。
$status用户请求的HTTP状态码。
$tcpinfo_rtt数据包往返目的地所用的时间,以微秒为单位。
headersList
需要发送到远程服务器的HTTP请求头名称和值。请求头名称可以包含任何字母,数字或连字符'-'。值可以包含任何可打印字符,也可以使用realTimeLog对象format字段中支持的任何内置变量。
nameString
HTTP标头名称
valueString
HTTP标头值
edgeLogicString
取值范围: <= 65530 字符 自定义边缘逻辑。参考边缘逻辑介绍。
hasBeianBoolean
默认值: False 此加速项目中的所有加速域名是否都已获得中国政府的ICP备案。只有获取备案的域名才能使用中国大陆节点来提供服务。如果设置为true,还必须在beianContentType字段中指定内容类型。
redirectHttpToHttpsString
默认值: False 此字段可以设置为布尔值或字符串。如果设置为true,则CDN Pro服务器会将所有HTTP请求重定向到HTTPS,并返回301状态码。如果您希望在重定向请求时返回不同的状态码,可在此处指定需要的状态码,如'302'、'307'或'308'。
originsList
描述加速项目对应的源站。
nameString
^[a-zA-z0-9_] 源站名称,在此加速项目中必须唯一。
serversList
源站服务器列表。每个条目为一个字符串,由一个地址与一个或多个参数组成,参数之间以空格分隔。地址可以采用以下三种形式之一: {域名或IP地址} {域名或IP地址}:{HTTP端口} {域名或IP地址}:{HTTP端口},{HTTPS端口} HTTP和HTTPS端口的值应为[1,65535]范围内的整数。 即使supportedProtocol的值设为'https',也必须在此处指定HTTPS端口。 在第三种形式中,两个端口中的一个可以为空。 支持的参数包括'backup'和'weight'。 'backup'用于标识备份服务器。它将在主服务器不可用时使用。 'weight'是范围[1,100]内的值,默认值为1,用来设置服务器权重,控制一台源站服务器相对于另一台被使用的可能性。 每个源站应至少定义一个主服务器(即不带'backup'参数的服务器)。 示例: ['www.abc.com weight=1', 'www1.abc.com:8080 weight=4', 'www2.abc.com:880,4443 backup'] 此示例指定了两个主服务器和一个备份服务器,其中,主服务器的权重为1:4,表示第一个服务器将获得约20%的回源请求,而另一个将获得约80%。
supportedProtocolString
取值范围: http,https,both 此可选字段表示源站服务器支持的协议。如果此加速项目附加了证书,且allowProtocolDowngrade字段也设置为true,则可以将该值设置为http。
directConnectionString
默认值: auto 此可选字段用来指定回源方式,可以是'noDirect'、'auto'、'alwaysDirect'。 'noDirect'指总是通过至少一个中间缓存节点回源。对于特别关心源站负载的客户可以使用此选项。我们的调度程序将根据性能和资源可用性动态选择中间缓存节点。 'alwaysDirect'指总是直接回源。 'auto'指自动选择直接回源或通过中间缓存节点回源。调度程序将根据性能和资源可用性动态做出选择。该字段未指定时,采用此默认行为。
hostHeaderString
可选,用来指定回源HOST头部。必须是有效的域名。当连接HTTPS源站时,该值也作为SNI域名。可以用nginx变量来指定,变量以'$'开头,后跟[a-z_]{3,60}。Nginx变量名不区分大小写,因此我们只允许小写字符。 如果未指定,将使用请求中的HOST请求头的值。 注意:如果指定了'awsS3'作为回源鉴权参数,则hostHeader的值不能为变量或为空,而必须是有效的Amazon S3主机名。参考:https://docs.aws.amazon.com/AmazonS3/latest/dev/VirtualHosting.html
verifyOriginBoolean
默认值: False 可选。用来设定CDN缓存节点是否验证源站证书。
authenticationObject
可选。用于指定与源服务器进行身份验证(回源鉴权)的相关参数(如密码)。必须至少有'methodName'(字符串)字段,用来指定预定义的鉴权方法。目前仅支持源站为AWS S3的回源鉴权,因此唯一有效的值是'awsS3'。使用'awsS3'时,需要提供以下参数: awsS3.region: 您存储在S3上的资源所在的AWS区域。例如,'us-west-1','ap-northeast-1','eu-north-1','cn-north-1'。 awsS3.accessKey: 您的 AWS 访问密钥(access key),CDN Pro 将使用它来访问您存储在 AWS S3 上的资源。 awsS3.secretKey: 您的 AWS 密钥(secret key),CDN Pro 将使用它来访问您存储在 AWS S3 上的资源。 此外,hostHeader字段的值不能为变量或为空,必须是有效的Amazon S3主机名。 示例: {'methodName':'awsS3', 'awsS3':{ 'region':'us-west-1', 'accessKey':'sdnu2932', 'secretKey':'d12345678abcdefghi' }}
methodNameString
鉴权方法。
keepAliveTimeoutInteger
默认值: 60 取值范围: [ 5 .. 600 ] 该字段用于指定CDN Pro服务器和源站建连的Keep-Alive超时时间,单位为秒。通过maxUpstreamKeepaliveTimeOut 该服务设置项可以更改允许的最大值。如果需要调整最大值,请联系我们的技术支持。
peerFailureTimeoutString
该字段用于设置源站故障剔除。开启此功能后,当连接某个源站服务器的失败次数达到设定阈值,该源站服务器将被标记为不可用,并保持该状态直到设定的超时时长。失败次数阈值和超时时长分别通过failureThreshold参数和timeout参数设置。CDN Pro回源时将剔除不可用的源站服务器。如果所有源站服务器都被标记为不可用,则对应的请求将立即响应502状态码。默认情况下,当连接某个源站服务器连续失败6次之后,该服务器将被标记为不可用,超时时长为1秒。如果要禁用此功能,请将peerFailureTimeout设置为'off'。开启源站故障剔除配置示例:{'peerFailureTimeout':{'failureThreshold':10,'timeout':3}}
tlsCertificateIdString
用于验证源站服务器的证书,该证书同样必须被部署。
shieldString
指定某个源站盾(origin shield)的ID。使用源站盾功能后,所有回源请求都会通过源站盾中转回源,这可以帮助收敛回源流量。源站盾是高级功能,如需使用请联系我们的技术支持开通。可通过调用‘获取源站盾列表’接口查询可用的源站盾及其对应的IP地址。您可根据源站的位置,选择合适的源站盾。如果您需使用中国大陆的源站盾,则该加速项目的所有域名必须已取得备案。如果您的源站开启了访问控制,请将所选择源站盾的IP地址加入白名单。
syntaxVersionInteger
默认值: 1 当前仅允许值为1。
disableHttp2Boolean
默认值: False 当值为true时,禁用对HTTP/2的支持,仅支持HTTP/1.1。
schemeInCacheKeyBoolean
默认值: False 指定缓存键(Cache Key)是否区分协议('http'或'https')。默认为false。如果不同协议响应的内容不同,则设置为true。
tlsMaxVersionString
取值范围: 1.1,1.2,1.3 默认值: 1.3 支持的TLS最高版本。
loadBalancerHashKeyString
取值范围: <= 100 字符 我们的CDN使用了多层负载均衡架构,将客户端请求分发到不同的服务器。我们在架构中多处使用到一致性哈希。默认情况下,URL被用作哈希键,这对于大多数情况都适用。您可以在这里定义要添加到哈希键的其他变量,以更均匀地分配请求。一个典型的使用场景是,所有请求都携带相同的URL,但使用特定的请求头来区分资源。 这是一个可选字段,默认值为空字符串。必须满足以下条件: 由字母、数字、下划线_、等号=、美元符号$和符号&组成。 变量名只能采用以下格式之一:$http_name、$cookie_name、$arg_name。 必须至少指定一个变量,不允许超过三个。 总长度不得超过100个字符。 我们的配置验证器将把任何美元符号及其后的字符串(在任何=或&或$之前)视为变量。 以下是一些有效值的示例:
$http_abc
abc=$http_abc&def=$http_def&c_123=$cookie_123
abc=$http_abc=$http_def
$http_abc&$http_def
=$http_abd&
&&abc==$http_abc&&&===qwer
tlsCertificateIdString
该加速项目用到的证书ID。仅设置tlsCertificateId1字段而不设置tlsCertificateId字段是无效的。如果未设置tlsCertificateId,则不会为此加速项目启用HTTPS。此功能允许您指定两个不同类型的证书,即一个RSA,一个EC。如果指定了两个相同类型的证书,则将忽略tlsCertificateId指定的证书。
tlsMinVersionString
取值范围: 1.1,1.2,1.3,1 默认值: 1 所需的TLS最低版本。
tlsCiphersString
取值范围: <= 2040 字符 'openssl ciphers'支持的任何加密算法套件。参考:https://www.openssl.org/docs/manmaster/man1/ciphers.html
allowProtocolDowngradeBoolean
默认值: False 是否允许协议降级。仅当加速项目中存在允许客户端使用HTTPS请求的证书时,此设置才适用。如果allowProtocolDowngrade的值为false,则要求所有源服务器支持HTTPS。如果值为true,则允许仅支持HTTP的源,但这会降低安全性。
tlsCertificateId1String
指该加速项目用到的证书ID。仅设置tlsCertificateId1字段而不设置tlsCertificateId字段是无效的。如果未设置tlsCertificateId,则不会为此加速项目启用HTTPS。此功能允许您指定两个不同类型的证书,即一个RSA,一个EC。如果指定了两个相同类型的证书,则将忽略tlsCertificateId指定的证书。
videoSeekObject
此对象用来支持视频播放器通过指定查询参数来请求部分内容。当videoSeek对象存在时,必须为startParameter设置一个值。
*startParameterString
取值范围: [ 1 .. 31 ] 字符 查询参数的名称,用来指定要获取的内容的起始位置(以字节计算)。参数名称应以字母(a-z,A-Z)开头,后面最多可以有30个字母和数字。
endParameterString
取值范围: [ 0 .. 31 ] 字符 查询参数的名称,用来指定要获取的内容的结束位置(以字节计算)。参数名称应以字母(a-z,A-Z)开头,后面最多可以有30个字母和数字。
tlsSessionTimeoutInteger
默认值: 1800 取值范围: [ 300 .. 86400 ] TLS会话ticket的有效期(秒)。
enableOcspStaplingBoolean
默认值: False 是否启用在线证书状态协议(OCSP)装订以检查数字证书的吊销状态。参考:https://en.wikipedia.org/wiki/OCSP_stapling
beianContentTypeInteger
取值范围: [ 1 .. 24 ] 如果您的域名已获得备案,希望通过中国大陆的服务器分发内容,则需要将hasBeian字段设置为true,并说明您分发的内容类型。请选择与您的内容最匹配的值:
内容类型
1即时通信
2搜索引擎
3综合门户
4网上邮局
5网络新闻
6博客/个人空间
7网络广告
8单位门户网站
9网络购物
10网上支付
11网上银行
12网上炒股
13网络游戏
14网络音乐
15网络影视
16网络图片
17软件下载
18网上求职
19在线交友
20网上房产
21网络教育
22网站建设
23WAP
24其他
accessControlRulesList
指定一个或多个访问控制规则以限制对内容的访问。可以使用边缘逻辑进行更高级的配置。此处定义的访问控制规则,优先级高于边缘逻辑。
idString
取值范围: [ 0 .. 60 ] 字符 访问控制规则ID。
conditionsObject
指定客户端请求必须匹配的条件。必须至少指定一个条件。如果指定了多个条件,则必须全部匹配。
schemeString
取值范围: https,http 客户端请求的协议,HTTP或HTTPS。
hostnameString
请求对应的加速域名。必须是加速项目中定义的加速域名之一。
uriString
取值范围: <= 500 字符 用于前缀匹配的URI,以'/'开头,可以以'*'结尾。
serverRegionsList
服务器所在区域,以ISO-3166-1 两位国家代码表示。例如,'US'代表'美国'。
clientRegionsList
客户端请求来源区域,以ISO-3166-1 两位国家代码表示。例如,'CN'代表'中国'。
clientIpRangeList
用于指定要匹配的客户端请求的开始和结束IP地址。必须是IPv4或IPv6格式。
actionObject
对于匹配到以上条件的请求所采取的相应操作。
*statusCodeString
响应的HTTP状态码,范围必须在300-309、400-409或500-509之间,分别表示重定向或错误。
messageString
取值范围: <= 200 字符 如果status字段的值在300-309范围内,message字段的值将在返回给客户端的Location响应头中。如果status字段的值在400-409或500-509范围内,则message字段的值将在返回给客户端的响应体中。
disableCertAutomationBoolean
默认值: False 默认情况下,CDN Pro控制/.well-known/{acme-challenge, pki-validation}目录下的内容,以支持加速项目的证书自动更新功能。如果您需要自己在源站管理这两个目录,例如,为了实现您自己的证书自动更新机制,您可以将此字段设置为true来禁用默认行为。关于证书自动更新的更多信息,请参考'创建证书'接口中autoRenew字段的说明。
cacheKeyUriString
取值范围: preRewrite,postRewrite 默认值: preRewrite 如果在加速项目的边缘逻辑中使用了'rewrite'指令,可使用该字段来控制客户端请求的URI如何合并到缓存键(Cache Key)中 。默认值'preRewrite'指将改写前的URI放入缓存键,而'postRewrite'则使用改写后的URI。如果您的'rewrite'指令将多个不同的URI改写为相同的值,则使用'postRewrite'可以提高缓存命中率。
extraServicePortsObject
除标准的80,443端口外,我们还支持一些扩展端口。可用该字段指定用于处理HTTP和HTTPS请求的扩展端口。
httpList
指定用于处理HTTP请求的端口列表(80端口除外)。可通过调用'获取系统配置'接口来查询系统支持的端口。如果您需要开通其他端口,请联系技术支持。
httpsList
指定用于处理HTTPS请求的端口列表(443端口除外)。可通过调用'获取系统配置'接口来查询系统支持的端口。如果您需要开通其他端口,请联系技术支持。
loadBalancerLogicString
取值范围: <= 65530 字符 此字段可用来自定义边缘逻辑,控制负载均衡器的行为。支持使用 边缘逻辑指令中的部分指令。请参考'获取系统配置'接口中baseLbDirectives字段所列出的负载均衡基础指令。目前,这些基础指令包括'if'、'else'、'elseif'、'set'、'return'、'add_header'、'deny'、'allow'、'access_log_sampling'和'proxy_set_headers'。此外,我们还支持一些高级指令,请参考'获取系统配置'接口中advancedLbDirectives字段所列出的负载均衡高级指令。如果您需要使用这些高级指令,请联系技术支持。
示例:
if ($http_user_agent = bot) { return 403;}
tls0RttBoolean
默认值: False 是否开启TLS 0-RTT功能。这是TLS 1.3版本支持的功能。启用该功能后,当用户频繁访问您的站点时,可提高访问响应速度。需要注意的是,启用该功能可能会加大站点遭受HTTP replay攻击的风险。

返回参数

响应头

参数名称描述
LocationString
通过Location响应头返回新建的加速项目的URL。URL中包含加速项目ID。可使用该ID调用'查询加速项目的基础信息及版本信息'接口来查看加速项目详情。URL示例:Location: http://open.chinanetcenter.com/cdn/properties/5dwa2205f9e9cc0001df7b24

错误码

错误代码(code)描述(message)HTTP状态码语义
InvalidEdgeLogicPlease check the edgeLogic configuration format. Make sure each 'location' block has an 'origin_pass' or a 'return' directive. A top-level 'if' block must have a 'return' directive and not contain an 'origin_pass' directive. A location directive for the default path '/' is also required.400边缘逻辑配置有误。每个location块必须包含origin_pass或return指令。边缘逻辑里必须有一个指向根路径'/'的location指令。如果if块放在最外层,则必须包括return指令,且不能包含origin_pass指令。
InvalidCertIdThe specified tlsCertificateId does not exist.400指定的tlsCertificateId不存在。
InvalidTLSSessionTimeoutThe TLS session timeout value should be between 300 and 86400 inclusive.400TLS session超时时间必须在300-86400之间。
OriginHostnameConflictAt least one of the hostnames is equal to an origin's server name.400加速域名与源站的server name冲突。
InvalidServicePortThe https service port 1234 is not supported.400不支持所指定的https特殊端口。
UnauthorizedDirectiveThe directive 'origin_fast_route' is not enabled for your account. Please contact our support team if you require it.400未取得origin_fast_route指令的授权。请联系我们的技术支持开通。
InvalidDirectiveAn invalid directive 'ORIGIN_set_header' was found in your Edge Logic. Please refer to the API documentation for a list of supported directives.400边缘逻辑中包括无效的指令,如ORIGIN_set_header。请参考API文档查看支持的指令列表。
InvalidHostnameThe hostname 'mytesthostname.com' is already in your property.400所指的域名已存在您的加速项目中。
AccessDeniedPlease enter valid credentials.403鉴权失败。
DuplicatePropertyNameA property with the same name already exists.409加速项目名称已存在。

示例

400
403
409
400
请求示例
复制代码 复制成功
#!/bin/bash
username="example_username"
apiKey="example_apiKey"
date=`env LANG="en_US.UTF-8" date -u "+%a, %d %b %Y %H:%M:%S GMT"`
password=`echo -en "$date" | openssl dgst -sha1 -hmac $apiKey -binary | openssl enc -base64`
curl -i --url "https://open.chinanetcenter.com/cdn/properties" \
-X "POST" \
-u "$username:$password" \
-H "Date: $date" \
-H "Accept: application/json" \
-d '{"name": "TestProperty1572420065294", "description": "a new property", "version": {"syntaxVersion": 1, "edgeLogic": "location / {origin_pass my_origin_1572420065294;}", "origins": [{"hostHeader": "testcustomer.g.qtlcdn.com", "servers": ["edgetools.theoriginserver.com"], "name": "my_origin_1572420065294", "directConnection": "auto"}], "hostnames": ["testcustomer1572420065294.g.qtlcdn.com"]}}'
返回示例
复制代码 复制成功
{
    "code": "InvalidEdgeLogic",
    "message": "Please check the edgeLogic configuration format. Make sure each 'location' block has an 'origin_pass' or a 'return' directive. A top-level 'if' block must have a 'return' directive and not contain an 'origin_pass' directive. A location directive for the default path '/' is also required."
}
本篇文档内容对您是否有帮助?
有帮助
我要反馈
提交成功!非常感谢您的反馈,我们会继续努力做到更好!