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.

Parameter	Data Type	Requirement	Description
domain	string	Required	Domain names. Separate domain names by commas (,). Up to 10 domain names at a time. For example, `aa.qingcdn.com,bb.qingcdn.com.`
config	array	Required	Specify 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

Parameter	Data Type	Requirement	Description
default_master	string	Required	Default 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_slave	string	Optional	Backup 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_mode	string	Optional	Select 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_https	string	Optional	Specify whether HTTPS should be used when contacting the origin. The options are `yes,no` . Can only be used when `origin_mode=custom`
port	int	Optional	Specify the port number to use when contacting the origin. Default is port 80. Can only be used when`origin_mode=custom` (0- 65535)

Origin_Host

Parameter	Data Type	Requirement	Description
host	string	Required	Specify what the host header should be when contacting the origin, for example, `"test.qingcdn.com"`

Refer

Referer-based Hotlink Protection

Parameter	Data Type	Requirement	Description
type	int	Required	Types of protection: `1`: meaning blacklist, and `2`: meaning whitelist.
list	array	Required	The 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_empty	boolean	Optional	The 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

Parameter	Data Type	Requirement	Description
type	int	Required	Types of caching rules: `1`: file extension, `2`: directory, `3`: complete path match, `4`: Regular expression (RegEx).
pattern	string	Required	Caching 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.
time	int	Required	Caching 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`.
timeunit	string	Optional	Unit 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_cache`	string	Optional	Ignore 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_expired`	string	Optional	Ignore 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_query`	string	Optional	Ignore 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_method	string	是	缓存类型， `ext`:文件名后缀， `dir`:目录， `route`:完整路径匹配，`regex`:正则
pattern	string	是	缓存规则，多个以逗号分隔, 例如: 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_ignore	string	否	是否忽略大小写，yes忽略，no不忽略。默认yes
expire	int	是	缓存时间, 配合expire_unit使用, 最大时间不超过2年, `当time=0时, 不对指定pattern进行缓存(即禁止缓存)`
expire_unit	string	否	缓存时间单位，默认值为s, 可选值有`(Y年,M月,D日,h时,i分,s秒)`
ignore_no_cache_headers	string	否	是否忽略源站响应头中的不缓存信息<br/>如Cache-Control:no-cache等, 默认值为`no`, 可选参数: `no,yes` `ignore_no_cache_headers=no`:表示不忽略 `ignore_no_cache_headers=yes`:表示忽略
follow_expired	string	否	是否遵循源站缓存时间, 默认值为`no`, 可选参数: `no,yes` `follow_expired=no`:表示不循源 `follow_expired=yes`:表示循源
cache_query_params	string	否	问号后参数处理方式, 默认值为`do_nothing`, 可选参数: `do_nothing,remove` `do_nothing`:表示缓存带参数 `remove`:缓存去参数
back_source_query_params	string	否	问号后参数处理方式, 默认值为`do_nothing`, 可选参数: `do_nothing,remove` `do_nothing`:表示回源带参数 `remove`:回源去参数
priority	int	否	排序值，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

Parameter	Data Type	Requirement	Description
list	array	Required	Ip 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

Parameter	Data Type	Requirement	Description
list	array	Required	ip 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

Parameter	Data Type	Requirement	Description
type	string	Not Required	Default 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).
list	array	Required	Response 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:

Parameter	Data Type	Requirement	Description
cert_id	int	Required	Specify the HTTPS certificate ID.
http2	string	Optional	Options are `on,off`, `on` = turn on http2, `off` = turn off http2.

Visit_Timestamp

Timestamp-based Hotlink Protection

Parameter	Data Type	Requirement	Description
pattern	string	Required	RegEx to match desired URLs. The format should follow `$scheme://$domain/$uri?$args. .*` matches all incoming URLs.
time_format	string	Required	Time format. The options are `timestamp_hex, date_minute` (YYYYmmddHHii, such as 201805211010), and `timestamp` (decimal timestamp)
key	string	Required	Key value(s) to be used to generate a signature. Separate multiple values by commas.
deadtime	int	Required	URL time-to-live in seconds. The value has to be greater than 0. The URL will be invalidated after the TTL expires.
req_uri_type	int	Required	URL 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_type	int	Optional	Specify 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.
style	string	Optional	Parameter encryption combination, `$ourkey $uri $time`. The three variable’s order is adjustable, ($ourkey, $uri, $time). Temporarily not supporting additional fields or information.
timename	string	Optional	The default value is `time`. The parameter name used in the url is only need when passing the parameter via query.
keyname	string	Optional	The 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

Parameter	Data Type	Requirement	Description
protocol	string	Required	Forbid access protocol, options are `http,https`.

Cache_Error_Code

Parameter	Data Type	Requirement	Description
bcache	string	Required	Cache control, options are `on, off`.
code	array	Required	Status 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_time	int	Optional	Use `cache time` along with `cache_unit`. Maxmium time can not exceed 2 years. Note: when `bcache=on`, the vaue must be update.
cache_unit	string	Optional	cache time unit, options are `(year,month,day,hour,minute,second)` Note: when `bcache=on`, the vaue must be update.

Video_Drag

Parameter	Data Type	Requirement	Description
url	string	Required	For example: .(mp4	flv	f4v	m4v).
mp4	string	Required	mp4 drag switch, options are `on,off`.
flv	string	Required	flv drag switch, options are `on,off`.
start	string	Required	`start` parameters, for example: `start`, the parameter options are : 'letters, numbers, underscores. Note: The value cannot begin with a number'.
end	string	Required	`end` parameters, for example: `end`, the parameter options are : 'letters, numbers, underscores. Note: The value cannot begin with a number'.

Compress_response

Parameter	Data Type	Requirement	Description
content_type	array	Required	Matching header, for example `["text/plain","application/x-javascript"]`
min_size	int	Required	Minimum size, for example `2`. Use it along `min_size_unit`,indicate what is the minimum size to compress
min_size_unit	string	Required	Minimum size unit, for example `KB`. Options are `KB/MB`

Visit_Deny_Whitelist

Parameter	Data Type	Requirement	Description
url	string	Required	Must be filled, setting url address:/user/get?index
turn_on	boolean	Required	Options 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 Code	Description
404	Bad request URLs.
401	Authorization Error: Invalid token or lack of access.
400	Bad request parameters.
200	Success.
5xx	Please contact your account team.