Development Document

Modify Configuration Download PDF Document

Endpoint

Request URL: domain/config (POST)

Endpoint Domain Name: cdn.api.baishan.com
Endpoint Version: v2

Endpoint Description

Modify existing configurations, including features like caching rules, origin setting, IP blacklist, referer-based whitelist and blacklist, and referer-based hotlink protection.

Note: Each user account can make up to 30 calls/minute for this API. Multiple changes can be submitted together or separately. When all changes are submitted together, one change’s failure/exception can cause all changes to fail.

API Parameters

Notice: Please request the API token from your account team.

Request Parameters (POST)

Add request parameters to the URL query strings, i.e. ?key1=value1&key2=value2.

ParameterData TypeRequirementDescription
domainstringRequiredDomain names. Separate domain names by commas (,). Up to 10 domain names at a time. For example, aa.qingcdn.com,bb.qingcdn.com.
configarrayRequiredSpecify the config rule(s) that you’d like to look up. The default is to return all config rules. For example:["referer","origin","ip_black_list","cache_rule","origin_host"]

Origin Settings

ParameterData TypeRequirementDescription
default_masterstringRequiredDefault origin. Can provide up to six (6) IPs or domain names, separated by commas (,). For example, "133.233.133.33,133.233.22.33".
default_slavestringOptionalBackup origin. Can provide up to six IPs or domain names, separated by commas (,). For example, "133.233.133.33,133.233.22.33". Backup origins MUST be different from the default origins.
origin_modestringOptionalSelect the protocol Baishan servers should use to contact the origin with. The values can be http, https, default, custom.
origin_mode=http: forward requests to the origins via HTTP and port 80.
origin_mode=https: forward requests to the origins via HTTPS and port 443.
origin_mode=default: forward requests to the origins via the same protocol as the end user’s request.
origin_mode=custom: customize ori_https and port number.
ori_httpsstringOptionalSpecify whether HTTPS should be used when contacting the origin. The options are yes,no . Can only be used when origin_mode=custom
portintOptionalSpecify the port number to use when contacting the origin. Default is port 80. Can only be used whenorigin_mode=custom (0- 65535)

Origin_Host

ParameterData TypeRequirementDescription
hoststringRequiredSpecify what the host header should be when contacting the origin, for example, "test.qingcdn.com"

Refer

Referer-based Hotlink Protection

ParameterData TypeRequirementDescription
typeintRequiredTypes of protection:
1: meaning blacklist, and
2: meaning whitelist.
listarrayRequiredThe whitelist or blacklist. Multiple entries can be separated by commas (,). Wildcard values must start with *. For example,["*.aaa.qingcdn.com","www.qingcdn.com","*.test.com"] "*.test.com"includes any matching host headers as well as test.coms
allow_emptybooleanOptionalThe value is true by default. true = allow the connection even when the referer header is empty, and false = block the connections if the referer header is empty.

Cache_Rule

ParameterData TypeRequirementDescription
typeintRequiredTypes of caching rules:
1: file extension,
2: directory,
3: complete path match,
4: Regular expression (RegEx).
patternstringRequiredCaching rules separated by a commas. For example,
When type=1,jpg,png,gif,
When type=2,/product/index,/test/index,/user/index,
When type=3,/index.html,/test/*.jpg,/user/get?index,
When type=4, see RegEx Explanation section below. The caching rules will be applied if an URL matches the RegEx. By default, query string is a part of the cache key, expires header is ignored, but no-cache header is prioritized and honored.] "*.test.com" includes any matching host headers and empty host headers.
timeintRequiredCaching time-to-live (TTL). Use with the timeunit parameter below. The maximum TTL is 2 years. If time=0, a no-cache rule is applied to the specified pattern.
timeunitstringOptionalUnit of the TTL value above. The unit is s (second) by default. Other options are Y,M,D,h,i,s (year, month, day, hour, minute, second).
ignore_no_cachestringOptionalIgnore the no-cache header from the origin. The value is off by default. Only valid when TTL>0. It can be set to on,off.
ignore_expiredstringOptionalIgnore the expires header from the origin. The value is The value is on by default. Only valid when TTL>0. It can be set to on,off.
ignore_querystringOptionalIgnore query string when caching. The value is off by default. Only valid when TTL>0. It can be set to on,off.

RegEx: If none of the default match patterns are suitable, RegEx can be an alternative option. However, improper use of RegEx can cause unexpected failures, so it is only advisable to be used by experienced users. Please make sure that you thoroughly understand the expression before applying it to your configuration. Setting the match pattern rule to RegEx means the entire request URL will be compared against the specified regular expression, including protocol, domain name, port number (if any), path, and query string. If the match is successful, the TTL set for the pattern will be applied.
Example 1: .*\.(gif|png|jpg)$will match all URLs that have gif, png, and jpg extensions.
Example 2: ^https?://[^/]+/dir1/dir2/(dir3_1|dir3_2)\.htmlwill match for /dir1/dir2/dir3_1.html and /dir1/dir2/dir3_2.html under the current host name.

//adding cache rules
curl -X POST "https://cdn.api.baishan.com/v2/domain/config"\
  -H 'content-type: application/json' \
  -d '{
    "token":"xxx",
    "domains":"aa.qingcdn.com",
    "config": {
        "cache_rule":[
            {
                "type":1,
                "pattern":"jpg,png,gif",
                "time":3600
            },
            {
                "type":1,
                "pattern":"avi,mp4,mpeg",
                "time":3600
            }
        ]
    }
}'

Cache_Rule_List (new)

参数名数据类型是否必须说明
match_methodstring缓存类型,
ext:文件名后缀,
dir:目录,
route:完整路径匹配,regex:正则
patternstring缓存规则,多个以逗号分隔, 例如:
type=ext时jpg,png,gif
type=dir时/product/index,/test/index,/user/index
type=route时/index.html,/test/*.jpg,/user/get?index
type=regex时 例子见下面说明 设置对应的正则, 设置了正则后, 对请求访问的url与正则做匹配, 匹配成功则使用该缓存规则.
默认是带参数缓存,忽略过期时间,不忽略 不缓存头
case_ignorestring是否忽略大小写,yes忽略,no不忽略。默认yes
expireint缓存时间, 配合expire_unit使用, 最大时间不超过2年,
当time=0时, 不对指定pattern进行缓存(即禁止缓存)
expire_unitstring缓存时间单位,默认值为s, 可选值有(Y年,M月,D日,h时,i分,s秒)
ignore_no_cache_headersstring是否忽略源站响应头中的不缓存信息<br/>如Cache-Control:no-cache等, 默认值为no, 可选参数: no,yes
ignore_no_cache_headers=no:表示不忽略
ignore_no_cache_headers=yes:表示忽略
follow_expiredstring是否遵循源站缓存时间, 默认值为no, 可选参数: no,yes
follow_expired=no:表示不循源
follow_expired=yes:表示循源
cache_query_paramsstring问号后参数处理方式, 默认值为do_nothing, 可选参数: do_nothing,remove
do_nothing:表示缓存带参数
remove:缓存去参数
back_source_query_paramsstring问号后参数处理方式, 默认值为do_nothing, 可选参数: do_nothing,remove
do_nothing:表示回源带参数
remove:回源去参数
priorityint排序值,priority值越低,优先级越高
# 添加缓存规则(可以为多个缓存规则)
curl -X POST "http://cdn.api.baishan.com/v2/domain/config"\
  -H 'content-type: application/json' \
  -d '{
    "token":"xxx",
    "domains":"test.aa.qingcdn.com",
    "config": {
        "cache_rule_list":[
            {
            "match_method":"dir",
            "pattern":"/www/html,/www/aaa",
            "case_ignore":"no",
            "priority":13,
            "expire":60,
            "expire_unit":"i",
            "ignore_no_cache_headers":"yes", 
            "follow_expired":"no",
            "cache_query_params":"do_nothing",
            "back_source_query_params":"do_nothing"
            },
            {
            "match_method":"ext",
            "pattern":"php,jsp,asp,aspx",
            "case_ignore":"no",
            "priority":15,
            "expire":3600,
            "expire_unit":"s",
            "ignore_no_cache_headers":"yes", 
            "follow_expired":"no",
            "cache_query_params":"remove",
            "back_source_query_params":"remove"
            }
        ]
    }
}'

Note:If both ip_black_list and ip_white_list are configuring at the same time, neither configuration would be successful.

IP_Black_List

ParameterData TypeRequirementDescription
listarrayRequiredIp blacklist with entries separated by commas. Up to 200 entries. For example, ["1.1.1.0/24", "2.2.2.2", "3.3.3.3"]. /8, /16, and /24 CIDR blocks are supported, but no repetition is allowed.Note: setting blacklist will remove whitelist

IP_White_List

ParameterData TypeRequirementDescription
listarrayRequiredip whitelist with entries separated by commas. Up to 200 entries. For example, ["1.1.1.0/24", "2.2.2.2", "3.3.3.3"]. /8, /16, and /24 CIDR blocks are supported, but no repetition is allowed.Note: setting whitelist will remove blacklist

Add_Response_Header

ParameterData TypeRequirementDescription
typestringNot RequiredDefault setting is reset, the options are reset,add,remove. reset can reset the previous header with a new header; add can add a new header or replace the previous exist header;remove can delete the response header (add and reset respond differently).
listarrayRequiredResponse header list: type,reset,add.For example, [{"name":"Content-Type","value":"text/html.."},{"name":"Cache-Control","value":"max-age..."}], when type = remove, just send header name, such as ["Content-Type","Cache-Control"].
#add response header 
curl -X POST "https://cdn.api.baishan.com/v2/domain/config"\
    -H "Content-Type: application/json"\
    -d '{
    "token":"xxx",
    "domains":"aa.qingcdn.com",
    "config": {
        "add_response_head": {
            "type":"add",
            "list":[
                {
                    "name":"Content-Type", 
                    "value":"text/html; charset=ISO-8859-4"
                },
                {
                    "name":"Cache-Control", 
                    "value":"max-age=300, must-revalidate"
                }
            ]
        }
    }
}'

#delete response header
curl -X POST "https://cdn.api.baishan.com/v2/domain/config"\
    -H "Content-Type: application/json"\
    -d '{
    "token":"xxx",
    "domains":"aa.qingcdn.com",
    "config": {
        "add_response_head": {
            "type":"remove",
            "list":["Content-Type","Cache-Control"]
        }
    }
}'

HTTPS

Certificate Settings:

ParameterData TypeRequirementDescription
cert_idintRequiredSpecify the HTTPS certificate ID.
http2stringOptionalOptions are on,off, on = turn on http2, off = turn off http2.

Visit_Timestamp

Timestamp-based Hotlink Protection

ParameterData TypeRequirementDescription
patternstringRequiredRegEx to match desired URLs. The format should follow $scheme://$domain/$uri?$args. .* matches all incoming URLs.
time_formatstringRequiredTime format. The options are timestamp_hex, date_minute (YYYYmmddHHii, such as 201805211010), and timestamp (decimal timestamp)
keystringRequiredKey value(s) to be used to generate a signature. Separate multiple values by commas.
deadtimeintRequiredURL time-to-live in seconds. The value has to be greater than 0. The URL will be invalidated after the TTL expires.
req_uri_typeintRequiredURL match mode types. Currently support the four types below:
1: $scheme://$domain/$uri?$args&{keyname}= $key&{timename}=$time&$args
2:$scheme://$domain/$uri?$args&{timename}=$time&{keyname}=$key&$args
3:$scheme://$domain/$time/$key/$uri?$args
4:$scheme://$domain/$key/$time/$uri?$args
origin_typeintOptionalSpecify whether to include key/signature when contacting the origin. Options are 1,2. The value is 1 by default, to not include the key/signature. 2 means include key/signature.
stylestringOptionalParameter encryption combination, $ourkey $uri $time. The three variable’s order is adjustable, ($ourkey, $uri, $time). Temporarily not supporting additional fields or information.
timenamestringOptionalThe default value is time. The parameter name used in the url is only need when passing the parameter via query.
keynamestringOptionalThe default value is key. A hash of (path, key, time) is generated with md5 signature and passed in the URL query by parameter name.

Forbid_HTTP/HTTPS

ParameterData TypeRequirementDescription
protocolstringRequiredForbid access protocol, options are http,https.

Cache_Error_Code

ParameterData TypeRequirementDescription
bcachestringRequiredCache control, options are on, off.
codearrayRequiredStatus code, can be imported multiple times, seperated with commas , options are 400,403,404,414,500,501,502,503,504,506,5xx where 5xx includes 500,501,502,503,504,506, for eample ["400","403","5xx"].
cache_timeintOptionalUse cache time along with cache_unit. Maxmium time can not exceed 2 years.
Note: when bcache=on, the vaue must be update.
cache_unitstringOptionalcache time unit, options are (year,month,day,hour,minute,second)
Note: when bcache=on, the vaue must be update.

Video_Drag

ParameterData TypeRequirementDescription
urlstringRequiredFor example: .(mp4flvf4vm4v).
mp4stringRequiredmp4 drag switch, options are on,off.
flvstringRequiredflv drag switch, options are on,off.
startstringRequiredstart parameters, for example: start, the parameter options are : 'letters, numbers, underscores. Note: The value cannot begin with a number'.
endstringRequiredend parameters, for example: end, the parameter options are : 'letters, numbers, underscores. Note: The value cannot begin with a number'.

Compress_response

ParameterData TypeRequirementDescription
content_typearrayRequiredMatching header, for example ["text/plain","application/x-javascript"]
min_sizeintRequiredMinimum size, for example 2. Use it along min_size_unit,indicate what is the minimum size to compress
min_size_unitstringRequiredMinimum size unit, for example KB. Options are KB/MB

Visit_Deny_Whitelist

ParameterData TypeRequirementDescription
urlstringRequiredMust be filled, setting url address:/user/get?index
turn_onbooleanRequiredOptions are true、false, ture= open current url whitelist, false = remove current referer whitelist setting.
#add referer whitelist
curl -X POST "https://cdn.api.baishan.com/v2/domain/config"\
    -H "Content-Type: application/json"\
    -d '{
    "token":"xxx",
    "domains":"aa.qingcdn.com",
    "config": {
        "visit_deny_whitelist": [
            {"url":"/user/get?index","turn_on":true},
            {"url":"/contract/get?index","turn_on":true}
        ]
    }
}'

#remove referer whitelist
curl -X POST "https://cdn.api.baishan.com/v2/domain/config"\
    -H "Content-Type: application/json"\
    -d '{
    "token":"xxx",
    "domains":"aa.qingcdn.com",
    "config": {
        "visit_deny_whitelist": [
            {"url":"/user/get?index","turn_on":false},
            {"url":"/contract/get?index","turn_on":false}
        ]
    }
}'

The parameter after whitelist setting successful

{
    "code": 0,//0 means success
    "data": {
        "config": {
            "visit_deny_whitelist": {
                "url": [
                    "/user/get?index",
                    "/contract/get?index"
                ]
            },
            ...
        }
    }
}

Sample Request

curl -X POST "https://cdn.api.baishan.com/v2/domain/config"\
    -H "Content-Type: application/json"\
    -d '{
    "token":"xxx",
    "domains":"aa.qingcdn.com,bb.qingcdn.com",
    "config": {
        "origin": {
            "default_master": "133.233.133.33",
            "default_slave": "12.13.41.21"
        },
        "origin_host": {
            "host": "test.qingcdn.com"
        },
        "referer": {
            "type": 1,
            "list": [
                "*.qingcdn.com",
                "new.vx.qingcdn.com"
            ],
            "allow_empty": false
        },
        "ip_black_list": {
            "list": [
                "14.12.11.0/24",
                "1.2.3.1"
            ]
        },
        "ip_white_list": {
            "list": [
                "14.12.11.0/24",
                "1.2.3.1"
            ]
        },
        "add_response_head":{
            "type":"add",
            "list":[
                {
                    "name":"Content-Type", 
                    "value":"text/html; charset=ISO-8859-4"
                },
                {
                    "name":"Cache-Control", 
                    "value":"max-age=300, must-revalidate"
                }
            ]
        },
        "https":{
            "cert_id":123
        },
        "visit_timestamp": {
            "pattern": ".*",
            "time_format": "timestamp",
            "key": "c3RyaWN0b",
            "keyname": "sign",
            "timename": "time",
            "deadtime": "3600",
            "req_uri_type": "2",
            "origin_type": "2",
            "error_page": "",
            "style": "$ourkey$uri$time"
        },
        "cache_rule": [
            {
                "type": "2",
                "pattern": "/product/index,/test/index,/user/index",
                "time": 86400,
                "timeunit": "s"
            },
            {
                "type": "1",
                "pattern": "jpg,png,gif",
                "time": 86400,
                "timeunit": "s"
            },
            {
                "type": "3",
                "pattern": "/index.html,/test/*.jpg,/user/get?index",
                "time": 86400,
                "timeunit": "s"
            }
        ],
        "video_drag": {
            "url": "\\.(mp4|flv|f4v|m4v)",
            "mp4": "off",
            "flv": "off",
            "start": "start",
            "end": "end"
        },
        "compress_response": {
            "content_type": [
                "text/plain",
                "application/x-javascript"
            ],
            "min_size": "2",
            "min_size_unit": "KB"
        }
    }
}'

Sample Response

Json format.

{
    "code": 0, //0 means success
    "data": {
        "config": {
            "origin": {
                "default_master": "133.233.133.33",
                "default_slave": "12.13.41.21"
            },
            ...
        }
    }
}

Response Header

HTTP/1.0 200 OK
Api-Id: 221328331
Content-Type: application/json; charset=utf-8
X-Ratelimit-Grad: minute   
X-Ratelimit-Limit: 50      
X-Ratelimit-Remaining: 29  
X-Retry-After: 43          

HTTP Status Codes

Error CodeDescription
404Bad request URLs.
401Authorization Error: Invalid token or lack of access.
400Bad request parameters.
200Success.
5xxPlease contact your account team.
CopyRight © 2015-2022 BaishanCloud . All Rights Reserved.