查询加速项目的版本配置详情-网宿科技

返回文档中心

API中心

适用产品

CDN Pro

接口描述

获取加速项目版本的详细配置信息。

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

调用频率

单用户调用频率：300/5min

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

请求参数

Path 参数

参数名称	描述
*propertyIdString	加速项目ID。
*versionString	加速项目版本。必须是大于等于1的整数值，但可以指定'latest'来查询最新版本。

返回参数

Body 参数

参数名称描述

versionInteger

版本号。

configsObject

描述加速项目的所有配置信息。

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_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	数据包往返目的地所用的时间，以微秒为单位。

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 awsS3.accessKey awsS3.secretKey 此外，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的源，但这会降低安全性。

tlsCertificateId1Integer

指该加速项目用到的证书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	网站建设
23	WAP
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

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

statusString

响应的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攻击的风险。

statusObject

状态信息。

lastValidationStatusString

该版本最近一次配置验证的结果。

frozenBoolean

该版本是否被冻结。当一个版本部署到演练或生产环境后，该版本即被冻结，不可更改。

creationTimeString

该版本创建时间。

lastUpdateTimeString

该版本最近一次更新时间。

inProductionBoolean

该版本是否部署到生产环境。

inStagingBoolean

该版本是否部署到演练环境。

错误码

错误代码（code）	描述（message）	HTTP状态码	语义
InvalidVersion	The version number must be a positive integer or "latest".	400	加速项目版本必须是正整数或者'latest'。
InvalidPropertyId	The specified property ID does not exist.	404	指定的加速项目ID不存在。

示例

200

请求示例 复制代码 复制成功#!/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/{version}" \ -X "GET" \ -u "$username:$password" \ -H "Date: $date" \ -H "Accept: application/json"

#!/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/{version}" \
-X "GET" \
-u "$username:$password" \
-H "Date: $date" \
-H "Accept: application/json"

返回示例 复制代码 复制成功{ "version": 1, "configs": { "description": "validPropertyVersionAllFields_PropertySteps", "cacheKeyHostname": "testdomain-t1572403678265.mydomain.info", "tlsCertificateId": "b0b3f432ccbaafb5693ce13d", "tlsMinVersion": "1.1", "tlsMaxVersion": "1.2", "tlsCiphers": "ALL:-MD5", "syntaxVersion": 1, "hasBeian": false, "schemeInCacheKey": false, "hostnames": [ "testdomain-t1572403678233.mydomain.info", "testdomain-t1572403678265.mydomain.info" ], "origins": [ { "name": "my_origin_1572403678233", "supportedProtocol": "both", "hostHeader": "autohostheader.com", "directConnection": "alwaysDirect", "servers": [ "mydomain.info" ] } ], "loadBalancerHashKey": "$http_hashvalue", "edgeLogic": "location / {origin_pass my_origin_1572403678233;} return 200;", "allowProtocolDowngrade": false }, "status": { "lastValidationStatus": "NotValidated", "frozen": false, "creationTime": "2019-10-30T02:47:59Z", "lastUpdateTime": "2019-10-30T02:47:59Z", "inProduction": false, "inStaging": false } }

{
    "version": 1,
    "configs": {
        "description": "validPropertyVersionAllFields_PropertySteps",
        "cacheKeyHostname": "testdomain-t1572403678265.mydomain.info",
        "tlsCertificateId": "b0b3f432ccbaafb5693ce13d",
        "tlsMinVersion": "1.1",
        "tlsMaxVersion": "1.2",
        "tlsCiphers": "ALL:-MD5",
        "syntaxVersion": 1,
        "hasBeian": false,
        "schemeInCacheKey": false,
        "hostnames": [
            "testdomain-t1572403678233.mydomain.info",
            "testdomain-t1572403678265.mydomain.info"
        ],
        "origins": [
            {
                "name": "my_origin_1572403678233",
                "supportedProtocol": "both",
                "hostHeader": "autohostheader.com",
                "directConnection": "alwaysDirect",
                "servers": [
                    "mydomain.info"
                ]
            }
        ],
        "loadBalancerHashKey": "$http_hashvalue",
        "edgeLogic": "location / {origin_pass my_origin_1572403678233;} return 200;",
        "allowProtocolDowngrade": false
    },
    "status": {
        "lastValidationStatus": "NotValidated",
        "frozen": false,
        "creationTime": "2019-10-30T02:47:59Z",
        "lastUpdateTime": "2019-10-30T02:47:59Z",
        "inProduction": false,
        "inStaging": false
    }
}

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/{version}" \
-X "GET" \
-u "$username:$password" \
-H "Date: $date" \
-H "Accept: application/json"

返回示例 复制代码 复制成功{ "code": "InvalidVersion", "message": "The version number must be a positive integer or \"latest\"." }

{
    "code": "InvalidVersion",
    "message": "The version number must be a positive integer or \"latest\"."
}

404

#!/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/{version}" \
-X "GET" \
-u "$username:$password" \
-H "Date: $date" \
-H "Accept: application/json"

返回示例 复制代码 复制成功{ "code": "InvalidPropertyId", "message": "The specified property ID does not exist." }

{
    "code": "InvalidPropertyId",
    "message": "The specified property ID does not exist."
}

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

有帮助

我要反馈

查询加速项目的版本配置详情

适用产品

接口描述

调用频率

请求参数

Path 参数

返回参数

Body 参数

错误码

示例

目录

热门产品与方案

快速入口

支持与服务

投资者关系

法律申明

关于网宿

联系我们

业务咨询