新建加速项目版本_API文档-网宿科技

返回文档中心

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

适用产品

CDN Pro

接口描述

创建一个新的加速项目版本。

调用URL： https://open.chinanetcenter.com/cdn/properties/*/versions
调用方法：POST

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

请求参数

Path 参数

参数名称	类型	必填	描述
propertyId	String	是	加速项目ID。

Body 参数

参数名称类型必填描述

description

String

否

版本描述。

cacheKeyHostname

String

否

取值范围: <= 80 字符 ^[a-z.-_]+ 用于缓存键（Cache Key）的主机名必须是由小写字母、数字、点、连字符和下划线组成的字符串。如果未指定，默认将使用传入的Host请求头值，并且此加速项目中的不同加速域名之间不共享缓存。

hostnames

List

否

与加速项目关联的加速域名。必须是FQDN完全限定域名（如 www.domain.com），或泛域名（如*.domain.com）。同一个加速域名在同一时间只能存在于一个已部署的加速项目中，但泛域名可以与关联的完全限定域名一同部署。

realTimeLog

Object

否

此可选字段用来配置发送消息通知（即实时日志）到您的远程服务器。当有客户端请求访问您的加速域名时，将触发通知。这是高级功能，如果您需要此功能，请联系我们的技术支持开通。

logUrl

String

是

接收通知的服务器URL地址。必须以'http'或'https'开头。服务器须支持POST方法。这是必填字段。

sampleRate

Integer

否

默认值: 1 取值范围: [ 1 .. 65536 ] 采样率。介于[1, 65536]之间的整数。n表示每n个边缘请求发送1条通知。1表示每个边缘请求都会发送。这是可选字段。默认值为1。

escape

String

否

取值范围: json,none 指定json以开启变量中的json字符转义。如果要禁用转义则指定none。

format

String

否

该字段用来定义要发送到远程服务器的通知的格式。通知正文可以包括任何能在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_uri	HTTP请求URI。
$request_method	用于访问源站的HTTP请求方法。
$request_time	响应时间，以毫秒为单位。这是从接收到请求的第一个字节到服务端响应最后一个字节之间的时间。
$sc_completed	1表示对象的最后一个字节已返回给用户，否则为0。
$sc_initial	1表示对象的第一个字节已返回给用户，否则为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	数据包往返目的地所用的时间，以微秒为单位。

headers

List

否

需要发送到远程服务器的HTTP请求头名称和值。请求头名称可以包含任何字母，数字或连字符'-'。值可以包含任何可打印字符，也可以使用realTimeLog对象format字段中支持的任何内置变量。

name

String

否

HTTP标头名称

value

String

否

HTTP标头值

edgeLogic

String

否

取值范围: <= 65530 字符自定义边缘逻辑。参考边缘逻辑介绍。

hasBeian

Boolean

否

默认值: False 此加速项目中的所有加速域名是否都已获得中国政府的ICP备案。只有获取备案的域名才能使用中国大陆节点来提供服务。如果设置为true，还必须在beianContentType字段中指定内容类型。

redirectHttpToHttps

String

否

默认值: False 此字段可以设置为布尔值或字符串。如果设置为true，则CDN Pro服务器会将所有HTTP请求重定向到HTTPS，并返回301状态码。如果您希望在重定向请求时返回不同的状态码，可在此处指定需要的状态码，如'302'、'307'或'308'。

origins

List

否

描述加速项目对应的源站。

name

String

否

^[a-zA-z0-9_] 源站名称，在此加速项目中必须唯一。

servers

List

否

源站服务器列表。每个条目为一个字符串，由一个地址与一个或多个参数组成，参数之间以空格分隔。地址可以采用以下三种形式之一： {域名或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%。

supportedProtocol

String

否

取值范围: http,https,both 此可选字段表示源站服务器支持的协议。如果此加速项目附加了证书，且allowProtocolDowngrade字段也设置为true，则可以将该值设置为http。

directConnection

String

否

默认值: auto 此可选字段用来指定回源方式，可以是'noDirect'、'auto'、'alwaysDirect'。 'noDirect'指总是通过至少一个中间缓存节点回源。对于特别关心源站负载的客户可以使用此选项。我们的调度程序将根据性能和资源可用性动态选择中间缓存节点。 'alwaysDirect'指总是直接回源。 'auto'指自动选择直接回源或通过中间缓存节点回源。调度程序将根据性能和资源可用性动态做出选择。该字段未指定时，采用此默认行为。

hostHeader

String

否

可选，用来指定回源HOST头部。必须是有效的域名。当连接HTTPS源站时，该值也作为SNI域名。可以用nginx变量来指定，变量以'$'开头，后跟[a-z_]{3,60}。Nginx变量名不区分大小写，因此我们只允许小写字符。如果未指定，将使用请求中的HOST请求头的值。注意：如果指定了'awsS3'作为回源鉴权参数，则hostHeader的值不能为变量或为空，而必须是有效的Amazon S3主机名。参考：https://docs.aws.amazon.com/AmazonS3/latest/dev/VirtualHosting.html

verifyOrigin

Boolean

否

默认值: False 可选。用来设定CDN缓存节点是否验证源站证书。

authentication

Object

否

可选。用于指定与源服务器进行身份验证（回源鉴权）的相关参数（如密码）。必须至少有'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' }}

methodName

String

否

鉴权方法。

keepAliveTimeout

Integer

否

默认值: 60 取值范围: [ 5 .. 600 ] 该字段用于指定CDN Pro服务器和源站建连的Keep-Alive超时时间，单位为秒。通过maxUpstreamKeepaliveTimeOut 该服务设置项可以更改允许的最大值。如果需要调整最大值，请联系我们的技术支持。

peerFailureTimeout

String

否

该字段用于设置源站故障剔除。开启此功能后，当连接某个源站服务器的失败次数达到设定阈值，该源站服务器将被标记为不可用，并保持该状态直到设定的超时时长。失败次数阈值和超时时长分别通过failureThreshold参数和timeout参数设置。CDN Pro回源时将剔除不可用的源站服务器。如果所有源站服务器都被标记为不可用，则对应的请求将立即响应502状态码。默认情况下，当连接某个源站服务器连续失败6次之后，该服务器将被标记为不可用，超时时长为1秒。如果要禁用此功能，请将peerFailureTimeout设置为'off'。开启源站故障剔除配置示例：{'peerFailureTimeout':{'failureThreshold':10,'timeout':3}}

tlsCertificateId

String

否

用于验证源站服务器的证书，该证书同样必须被部署。

shield

String

否

指定某个源站盾（origin shield）的ID。使用源站盾功能后，所有回源请求都会通过源站盾中转回源，这可以帮助收敛回源流量。源站盾是高级功能，如需使用请联系我们的技术支持开通。可通过调用‘获取源站盾列表’接口查询可用的源站盾及其对应的IP地址。您可根据源站的位置，选择合适的源站盾。如果您需使用中国大陆的源站盾，则该加速项目的所有域名必须已取得备案。如果您的源站开启了访问控制，请将所选择源站盾的IP地址加入白名单。

syntaxVersion

Integer

否

默认值: 1 当前仅允许值为1。

disableHttp2

Boolean

否

默认值: False 当值为true时，禁用对HTTP/2的支持，仅支持HTTP/1.1。

schemeInCacheKey

Boolean

否

默认值: False 指定缓存键（Cache Key）是否区分协议（'http'或'https'）。默认为false。如果不同协议响应的内容不同，则设置为true。

tlsMaxVersion

String

否

取值范围: 1.1,1.2,1.3 默认值: 1.3 支持的TLS最高版本。

loadBalancerHashKey

String

否

取值范围: <= 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

tlsCertificateId

String

否

该加速项目用到的证书ID。仅设置tlsCertificateId1字段而不设置tlsCertificateId字段是无效的。如果未设置tlsCertificateId，则不会为此加速项目启用HTTPS。此功能允许您指定两个不同类型的证书，即一个RSA，一个EC。如果指定了两个相同类型的证书，则将忽略tlsCertificateId指定的证书。

tlsMinVersion

String

否

取值范围: 1.1,1.2,1.3,1 默认值: 1 所需的TLS最低版本。

tlsCiphers

String

否

取值范围: <= 2040 字符 'openssl ciphers'支持的任何加密算法套件。参考：https://www.openssl.org/docs/manmaster/man1/ciphers.html

allowProtocolDowngrade

Boolean

否

默认值: False 是否允许协议降级。仅当加速项目中存在允许客户端使用HTTPS请求的证书时，此设置才适用。如果allowProtocolDowngrade的值为false，则要求所有源服务器支持HTTPS。如果值为true，则允许仅支持HTTP的源，但这会降低安全性。

tlsCertificateId1

String

否

指该加速项目用到的证书ID。仅设置tlsCertificateId1字段而不设置tlsCertificateId字段是无效的。如果未设置tlsCertificateId，则不会为此加速项目启用HTTPS。此功能允许您指定两个不同类型的证书，即一个RSA，一个EC。如果指定了两个相同类型的证书，则将忽略tlsCertificateId指定的证书。

videoSeek

Object

否

此对象用来支持视频播放器通过指定查询参数来请求部分内容。当videoSeek对象存在时，必须为startParameter设置一个值。

startParameter

String

是

取值范围: [ 1 .. 31 ] 字符查询参数的名称，用来指定要获取的内容的起始位置（以字节计算）。参数名称应以字母（a-z，A-Z）开头，后面最多可以有30个字母和数字。

endParameter

String

否

取值范围: [ 0 .. 31 ] 字符查询参数的名称，用来指定要获取的内容的结束位置（以字节计算）。参数名称应以字母（a-z，A-Z）开头，后面最多可以有30个字母和数字。

tlsSessionTimeout

Integer

否

默认值: 1800 取值范围: [ 300 .. 86400 ] TLS会话ticket的有效期（秒）。

enableOcspStapling

Boolean

否

默认值: False 是否启用在线证书状态协议（OCSP）装订以检查数字证书的吊销状态。参考：https://en.wikipedia.org/wiki/OCSP_stapling

beianContentType

Integer

否

取值范围: [ 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	网站建设
23	WAP
24	其他

accessControlRules

List

否

指定一个或多个访问控制规则以限制对内容的访问。可以使用边缘逻辑进行更高级的配置。此处定义的访问控制规则，优先级高于边缘逻辑。

String

否

取值范围: [ 0 .. 60 ] 字符访问控制规则ID。

conditions

Object

否

指定客户端请求必须匹配的条件。必须至少指定一个条件。如果指定了多个条件，则必须全部匹配。

scheme

String

否

取值范围: https,http 客户端请求的协议，HTTP或HTTPS。

hostname

String

否

请求对应的加速域名。必须是加速项目中定义的加速域名之一。

uri

String

否

取值范围: <= 500 字符用于前缀匹配的URI，以'/'开头，可以以'*'结尾。

serverRegions

List

否

服务器所在区域，以ISO-3166-1 两位国家代码表示。例如，'US'代表'美国'。

clientRegions

List

否

客户端请求来源区域，以ISO-3166-1 两位国家代码表示。例如，'CN'代表'中国'。

clientIpRange

List

否

用于指定要匹配的客户端请求的开始和结束IP地址。必须是IPv4或IPv6格式。

action

Object

否

对于匹配到以上条件的请求所采取的相应操作。

statusCode

String

是

响应的HTTP状态码，范围必须在300-309、400-409或500-509之间，分别表示重定向或错误。

message

String

否

取值范围: <= 200 字符如果status字段的值在300-309范围内，message字段的值将在返回给客户端的Location响应头中。如果status字段的值在400-409或500-509范围内，则message字段的值将在返回给客户端的响应体中。

disableCertAutomation

Boolean

否

默认值: False 默认情况下，CDN Pro控制/.well-known/{acme-challenge, pki-validation}目录下的内容，以支持加速项目的证书自动更新功能。如果您需要自己在源站管理这两个目录，例如，为了实现您自己的证书自动更新机制，您可以将此字段设置为true来禁用默认行为。关于证书自动更新的更多信息，请参考'创建证书'接口中autoRenew字段的说明。

cacheKeyUri

String

否

取值范围: preRewrite,postRewrite 默认值: preRewrite 如果在加速项目的边缘逻辑中使用了'rewrite'指令，可使用该字段来控制客户端请求的URI如何合并到缓存键（Cache Key）中。默认值'preRewrite'指将改写前的URI放入缓存键，而'postRewrite'则使用改写后的URI。如果您的'rewrite'指令将多个不同的URI改写为相同的值，则使用'postRewrite'可以提高缓存命中率。

extraServicePorts

Object

否

除标准的80，443端口外，我们还支持一些扩展端口。可用该字段指定用于处理HTTP和HTTPS请求的扩展端口。

http

List

否

指定用于处理HTTP请求的端口列表（80端口除外）。可通过调用'获取系统配置'接口来查询系统支持的端口。如果您需要开通其他端口，请联系技术支持。

https

List

否

指定用于处理HTTPS请求的端口列表（443端口除外）。可通过调用'获取系统配置'接口来查询系统支持的端口。如果您需要开通其他端口，请联系技术支持。

loadBalancerLogic

String

否

取值范围: <= 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;}

tls0Rtt

Boolean

否

默认值: False 是否开启TLS 0-RTT功能。这是TLS 1.3版本支持的功能。启用该功能后，当用户频繁访问您的站点时，可提高访问响应速度。需要注意的是，启用该功能可能会加大站点遭受HTTP replay攻击的风险。

返回参数

响应头

参数名称	类型	描述
Location	String	通过Location响应头返回新建的加速项目版本的URL。URL中包含了加速项目的ID以及版本号。URL示例：`Location: http://open.chinanetcenter.com/cdn/properties/5dca2205f9e9cc0001df7b33/versions/2`

错误码

错误代码（code）	描述（message）	HTTP状态码	语义
InvalidOrigins	The origin hostHeader 'invalid' is invalid. It must be a valid hostname or a variable name ($ + a string consists of lower case a-z and '_' with length 3-60).	400	回源指定的hostHeader参数取值无效，必须是有效的域名或变量名。变量名只能包括小写字母和'_'，长度在3-60个字符。
OriginHostnameConflict	At least one of the hostnames is equal to an origin's server name.	400	加速域名与源站的server name冲突。
InvalidServicePort	The https service port 1234 is not supported.	400	不支持所指定的https特殊端口。
UnauthorizedDirective	The directive 'origin_fast_route' is not enabled for your account. Please contact our support team if you require it.	400	未取得origin_fast_route指令的授权。请联系我们的技术支持开通。
InvalidDirective	An 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文档查看支持的指令列表。
InvalidPropertyId	The specified property ID does not exist.	404	指定的加速项目ID不存在。

示例

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/{propertyID}/versions" \ -X "POST" \ -u "$username:$password" \ -H "Date: $date" \ -H "Accept: application/json" \ -d '{"syntaxVersion": 1, "edgeLogic": "location / {origin_pass my_origin_1572402826736;} return 200;", "origins": [{"servers": ["mwtrial.info"], "name": "my_origin_1572402826736"}], "description": "validPropertyVersionWithoutCertificate_PropertySteps", "hostnames": ["testdomain-t1572402826736.mwtrial.info"]}'

#!/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/{propertyID}/versions" \
-X "POST" \
-u "$username:$password" \
-H "Date: $date" \
-H "Accept: application/json" \
-d '{"syntaxVersion": 1, "edgeLogic": "location / {origin_pass my_origin_1572402826736;} return 200;", "origins": [{"servers": ["mwtrial.info"], "name": "my_origin_1572402826736"}], "description": "validPropertyVersionWithoutCertificate_PropertySteps", "hostnames": ["testdomain-t1572402826736.mwtrial.info"]}'

返回示例 复制代码 复制成功{ "code": "InvalidOrigins", "message": "The origin hostHeader 'invalid' is invalid. It must be a valid hostname or a variable name ($ + a string consists of lower case a-z and '_' with length 3-60)." }

{
    "code": "InvalidOrigins",
    "message": "The origin hostHeader 'invalid' is invalid. It must be a valid hostname or a variable name ($ + a string consists of lower case a-z and '_' with length 3-60)."
}

本篇文档内容对您是否有帮助？

有帮助

我要反馈

CDN

云视频

安全

计算

存储

网络

数据库

域名服务

管理与部署

灾备

互联网中间件

应用与服务

云备源

用户服务

API

备案

新建加速项目版本

适用产品

接口描述

请求参数

Path 参数

Body 参数

返回参数

响应头

错误码

示例

目录

热门产品与方案

快速入口

支持与服务

投资者关系

法律申明

关于网宿

联系我们

业务咨询