Configures features for one or more domain names.

Note
  • You can configure features for at most 50 domain names in each API call.
  • The maximum number of times that each user can call this operation per second is 30.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter Type Required Example Description
Action String Yes BatchSetDcdnDomainConfigs

The operation that you want to perform. Set the value to BatchSetDcdnDomainConfigs.

DomainNames String Yes example.com,example.org

The accelerated domain names. Separate domain names with commas (,).

Functions String Yes [{"functionArgs":[{"argName":"domain_name","argValue":"example.com"}],"functionName":"set_req_host_header"}]

The list of features. Format:

[{"functionArgs":[{"argName":"parameter name","argValue":"parameter value"}],"functionName":"feature name"}]

The following table describes how to set and query a configid.

API operation

Description

BatchSetDcdnDomainConfigs

Adds a configuration record. After you call this API operation, a configid is generated.

DescribeDcdnDomainConfigs

Queries a configuration record. After you call this API operation, the configid of the queried configuration record is returned.

BatchSetDcdnDomainConfigs

Modifies a configuration record. You must specify a configid when you call this API operation.

DeleteDcdnSpecificConfig

Deletes a configuration record. You must specify a configid when you call this API operation.

Usage notes for configid:
  • How a configid is generated: Call the BatchSetDcdnDomainConfigs operation to configure a feature for a domain name. If the call is successful, a configid is generated and returned.
    • Sample request:
      action: BatchSetDcdnDomainConfigs
      params: {"Functions":[{"functionArgs":[{"argName":"value","argValue":"test"},{"argName":"key","argValue":"User-Agent"}],"functionName":"set_req_header"}],"domainNames":"example.com"}
      product: dcdn
    • Sample success response:
      {
          "code": "200", 
          "data": {
      "DomainConfigList": {
                  "DomainConfigModel": [
                      {
                          "FunctionName": "set_req_header", 
                          "DomainName": "example.aliyundoc.com", 
                          "ConfigId": 19571990834****
                      }
                  ]
              }, 
              "RequestId": "4FF61A1D-E697-5E6C-9E5D-7D1E1529****"
          }, 
          "httpStatusCode": "200", 
          "requestId": "4FF61A1D-E697-5E6C-9E5D-7D1E1529****", 
          "successResponse": true
      }
    • Add multiple rules

      Some features support more than one rule. The following example shows how to add multiple rules at a time:

      Example: Configure the set_resp_header feature for the domain name example.aliyundoc.com and add the following two rules:

      • Rule 1: key=123,value=123
      • Rule 2: key=test,value=test
        
                    action: BatchSetDcdnDomainConfigs
                    params: {
                        "domainNames": "example.aliyundoc.com", 
                        "functions": [
                            {
                                "functionArgs": [
                                    {
                                        "ArgValue": "123", 
                                        "ArgName": "key"
                                    }, 
                                    {
                                        "ArgValue": "123", 
                                        "ArgName": "value"
                                    }
                                ], 
                                "functionName": "set_resp_header"
                            }, 
                            {
                                "functionArgs": [
                                    {
                                        "ArgValue": "test", 
                                        "ArgName": "key"
                                    }, 
                                    {
                                        "ArgValue": "test", 
                                        "ArgName": "value"
                                    }
                                ], 
                                "functionName": "set_resp_header"
                            }
                        ]
                    }
                    product: dcdn
                    
                    
      • Add multiple configuration records
        Some features, such as filetype_based_ttl_set, support multiple configuration records. If you want to update one of the configuration records, specify the configId of the configuration record.
        
                [
                {
                    "functionArgs": [
                            {
                                "argName": "file_type", 
                                "argValue": "jpg"
                            }, 
                            {
                                "argName": "ttl", 
                                "argValue": "18"
                            }
                        ], 
                        "functionName": "filetype_based_ttl_set", 
                        "configId": 5068995
                    }
                ]
                
  • How to query the configid of a configuration record: Call the DescribeDcdnDomainConfigs operation. If the call is successful, the configid of the queried configuration record is returned.
    • Sample request:
      action: DescribeDcdnDomainConfigs
          params: {"domainName":"example.aliyundoc.com","functionNames":"set_req_header"}
          product: dcdn
    • Sample response:
      {
              "code": "200", 
              "data": {
                  "RequestId": "51B7DF03-A7AE-56ED-BF1E-D16F6A6B****", 
                  "DomainConfigs": {
                      "DomainConfig": [
                          {
                              "Status": "configuring", 
                              "FunctionName": "set_req_header", 
                              "FunctionArgs": {
                                  "FunctionArg": [
                                      {
                                          "ArgValue": "test", 
                                          "ArgName": "value"
                                      }, 
                                      {
                                          "ArgValue": "User-Agent", 
                                          "ArgName": "key"
                                      }
                                  ]
                              }, 
                              "ConfigId": 19572306654****
                          }
                      ]
                  }
              }, 
              "httpStatusCode": "200", 
              "requestId": "51B7DF03-A7AE-56ED-BF1E-D16F6A6B****", 
              "successResponse": true
          }
  • How to use a configid:
    • If you want to update a configuration record, call the DescribeDcdnDomainConfigs operation and specify the configid of the configuration record.
      action: BatchSetDcdnDomainConfigs
      params: {
          "Functions": [
              {
                  "functionArgs": [
                      {
                          "argName": "value", 
                          "argValue": "123456"
                      }, 
                      {
                          "argName": "key", 
                          "argValue": "User-Agent"
                      }
                  ], 
                  "functionName": "set_req_header", 
                  "configId": 19571990834****
              }
          ], 
          "domainNames": "example.com"
      }
      product: dcdn
    • If you want to delete a configuration record, call the DescribeDcdnDomainConfigs operation and specify the configid of the configuration record.
      
      action: DeleteSpecificConfig
      params: {
          "configId": 19571990834****, 
          "functionName": "set_req_header", 
          "domainName": "example.aliyundoc.com"
      }
      product: dcdn
                                  

The following table describes the supported features.

Feature

Parameter

referer_white_list_set: configures a referer whitelist for hotlink protection.

refer_domain_allow_list: specifies the referers to be added to the whitelist. Separate multiple referers with commas (,).

allow_empty: specifies whether requests with an empty referer header are allowed to access resources cached on Dynamic Route for CDN (DCDN). Valid values: on and off.

referer_black_list_set: configures a referer blacklist for hotlink protection.

refer_domain_deny_list: specifies the referers to be added to the blacklist. Separate multiple referers with commas (,).

allow_empty: specifies whether requests with an empty referer header are allowed to access the resources that are cached on DCDN. Valid values: on and off.

filetype_based_ttl_set: configures an expiration rule for specific file types.

ttl: specifies the time period after which the cached resources expire. Unit: seconds.

file_type: specifies the file types. Separate multiple file types with commas (,), for example, TXT,JPG.

weight: specifies the weight of the expiration rule.

path_based_ttl_set: configures an expiration rule for a specific directory.

ttl: specifies the time period after which the cached resources expire. Unit: seconds.

path: specifies a directory. It must start with a forward slash (/).

weight: specifies the weight of the expiration rule.

oss_auth: configures authentication for requests destined for an Object Storage Service (OSS) bucket.

oss_bucket_id: specifies the endpoint of an OSS bucket.

ip_black_list_set: configures an IP address blacklist.

ip_list: specifies the IP addresses that you want to add to the blacklist. Separate multiple IP addresses with commas (,).

ip_allow_list_set: configures an IP address whitelist.

ip_list: specifies the IP addresses that you want to add to the whitelist. Separate multiple IP addresses with commas (,).

error_page: redirects an error page to a specific page.

error_code: specifies an HTTP status code.

rewrite_page: specifies the page to which error pages are redirected when a specific error occurs.

set_req_host_header: configures a custom header for requests that are redirected to the origin server.

domain_name: specifies a domain name that is used as the origin host.

set_hashkey_args: ignores URL parameters.

hashkey_args: specifies the parameters that you want to reserve. Separate multiple parameters with commas (,). You can specify at most 10 parameters to be reserved.

disable: A value of on indicates all parameters are ignored. A value of off indicates all parameters are reserved. The hashkey_args setting has a higher priority. Even if you set the disable parameter to on, the parameters specified in hashkey_args are reserved.

keep_oss_args: specifies whether to reserve all the origin parameters in back-to-origin requests. A value of on indicates that all the origin parameters in back-to-origin requests are reserved. A value of off indicates that only the parameters specified in hashkey_args are reserved.

aliauth: configures URL signing.

auth_type: specifies the signing type. A value of no_auth disables authentication. A value of type_a indicates type A signing. A value of type_b indicates type B signing. A value of type_c indicates type C signing.

auth_key1: specifies the primary cryptographic key. The cryptographic key must be 16 to 32 characters in length, and can contain letters and digits.

auth_key2: specifies the secondary cryptographic key. The cryptographic key must be 16 to 32 characters in length, and can contain letters and digits.

ali_auth_delta: specifies the custom buffer time for signing.

set_resp_header: sets an HTTP response header. To verify the setting, you can check responses in a browser.

key: specifies a response header. This parameter is required.

value: specifies the value of the response header. This parameter is required. Enter null if you want to delete the header.

header_operation_type: specifies the action to be performed on the request header. Valid values: add, delete, modify, and rewrite.

duplicate: specifies whether to allow duplicate response headers. Valid values: on and off.

header_source: specifies the response header before the replacement.

header_destination: specifies the response header after the replacement.

match_all: specifies whether to match all queries. Valid values: on and off.

access_origin_control: specifies whether to enable cross-origin resource sharing (CORS). Valid values: on and off.

https_force: redirects requests from HTTP to HTTPS.

enable: specifies whether to enable this feature. Valid values: on and off.

https_force: redirects requests from HTTPS to HTTP.

enable: specifies whether to enable this feature. Valid values: on and off.

https_option: sets basic HTTPS parameters.

http2: specifies whether to enable HTTP/2. Valid values: on and off.

ocsp_stapling: specifies whether to enable Online Certificate Status Protocol (OCSP) stapling. Valid values: on and off.

forward_scheme: configures the static origin protocol policy.

enable: specifies whether to enable this feature. Valid values: on and off.

scheme_origin: specifies the origin protocol policy. Valid values: http, https, and follow.

dynamic: configures the DCDN service.

enable: specifies whether to enable the feature. This parameter is required. Valid values: on and off.

static_route_type: specifies the filename extension for static content.

static_route_url: specifies the URI of the static content.

static_route_path: specifies the path of the static content.

dynamic_route_origin: specifies the scheme of the back-to-origin route. Valid values: http, https, follow, and follow-port.

dynamic_route_round_robin: specifies whether to enable load balancing. Valid values: on and off.

dynamic_route_adapt_cache: specifies whether to enable adaptive caching. Valid values: on and off.

set_req_header: customizes an HTTP header for requests that are redirected to the origin server.

key: specifies the name of the request header.

value: specifies the value of the header.

l2_oss_key: retrieves content from private OSS buckets.

private_oss_auth: specifies whether to enable this feature. Valid values: on and off.

range: configures object chunking.

enable: specifies whether to enable the feature. Valid values: on and off.

video_seek: configures video seeking.

enable: specifies whether to enable the feature. This parameter is required. Valid values: on and off.

flv_seek_by_time: specifies whether to enable Flash Video (FLV) seeking by time. Valid values: on and off.

mp4_seek_start: customizes MP4 video start parameters.

mp4_seek_end: customizes MP4 video end parameters.

flv_seek_start: customizes FLV video start parameters.

flv_seek_end: customizes FLV video end parameters.

websocket: configures the WebSocket protocol.

enabled: specifies whether to enable the feature. This parameter is required. Valid values: on and off.

origin_scheme: specifies the origin protocol policy. Valid values: http, https, and follow.

heartbeat: specifies the heartbeat interval. Unit: seconds. Valid values: 1 to 300. Default value: 60.

ali_remove_args: deletes URL parameters.

ali_remove_args: specifies the parameters to be deleted. Separate multiple parameters with spaces. The remaining parameters are used as the URL parameters in hashkey_args. The ali_remove_args parameter is required.

keep_oss_args: specifies whether to reserve URL parameters in requests before they are redirected to origin servers. A value of on indicates that all URL parameters are reserved in requests before they are redirected to origin servers. A value of off indicates that only the parameters in hashkey_args are reserved.

https_tls_version: configures the Transport Layer Security (TLS) protocol.

tls10: specifies whether to enable TLS 1.0. Valid values: on and off. Default value: on.

tls11: specifies whether to enable TLS 1.1. Valid values: on and off. Default value: on.

tls12: specifies whether to enable TLS 1.2. Valid values: on and off. Default value: on.

tls13: specifies whether to enable TLS 1.3. Valid values: on and off. Default value: off.

HSTS: configures HTTP Strict Transport Security (HSTS).

enabled: specifies whether to enable the feature. This parameter is required. Valid values: on and off. Default value: off.

https_hsts_max_age: specifies the validity period of the HSTS policy. This parameter is required. Unit: milliseconds. We recommend that you set the value to 5184000000. This value equals 60 days.

https_hsts_include_subdomains: specifies whether the HSTS header contains the includeSubDomains parameter. Valid values: on and off. Proceed with caution when you enable this feature. Make sure that HTTPS is enabled for all the subdomains of the accelerated domain name. Otherwise, the HTTPS URLs to which requests are redirected from the subdomains become inaccessible.

filetype_force_ttl_code: configures an expiration rule for file status codes.

file_type: specifies the file types. You can specify one or more file types. Separate multiple file types with commas (,), for example, TXT,JPG. This parameter is required.

code_string: specifies the HTTP status codes. Separate multiple status codes with commas (,). This parameter is required. Example: 302=0,301=0,4xx=2.

path_force_ttl_code: configures an expiration rule for directory status codes.

path: specifies a directory. It must start with a forward slash (/), for example, /image. This parameter is required.

code_string: specifies the HTTP status codes. Separate multiple status codes with commas (,). This parameter is required. Example: 302=0,301=0,4xx=2.

gzip: configures gzip compression.

enable: specifies whether to enable this feature. This parameter is required. Valid values: on and off.

tesla: configures page optimization.

enable: specifies whether to enable this feature. This parameter is required. Valid values: on and off.

trim_js: specifies whether to optimize the JavaScript code of HTML pages. Valid values: on and off.

trim_css: specifies whether to optimize the CSS code of HTML pages. Valid values: on and off.

https_origin_sni: configures origin Server Name Indication (SNI) settings.

enabled: specifies whether to enable the feature. Valid values: on and off.

https_origin_sni: specifies the origin SNI settings. This parameter is required.

protogw: configures IP address acceleration.

realip: specifies the transparent proxy mode for the origin server to obtain the real IP addresses of the clients. This parameter is required. Valid values: off, toa, and pp.

port: specifies the service port. This parameter is required.

patten: specifies the mode string.

host_redirect: configures the rewrite feature.

regex: specifies the URL that you want to rewrite, for example, ^/$.

replacement: specifies the final URL, for example, /go/act/sale/tbzlsy.php.

flag: Valid values are redirect and break.

forward_timeout: configures the timeout period for requests that are redirected to the origin server.

forward_timeout: specifies a time period in seconds. We recommend that you set a value that is not greater than 100.

ipv6: configures IPv6.

switch: specifies whether to enable the feature. This parameter is required. Valid values: on and off.

region: specifies the region where you want to enable IPv6. You can enter a wildcard character (*) to specify all regions.

edge_function: configures EdgeScript.

rule: specifies domain-specific language (DSL)-based scripts. This parameter is required.

pri: specifies the priority of the DSL script. This parameter is required.

enable: specifies whether to enable the script. This parameter is required. Valid values: on and off.

name: specifies the name of the script.

pos: specifies the position where the script is executed. For the accelerated domain names of DCDN, only the value of head is supported. The value of foot is not supported.

brk: After the current script is matched, the scripts after the specified position are skipped.

option: specifies an extension that is used to perform response header debugging.

grammar: specifies an extension that is used to specify the scripting language. Valid values: es2 and js. You can leave this parameter empty.

jsmode: specifies an extension that is used to manage the domain name whitelist in JavaScript. Valid value: redirect and bypass.

brotli: configures Brotli compression.

enable: specifies whether to enable this feature. This parameter is required. Valid values: on and off.

brotli_level: specifies the compression level. Valid values: 1 to 11.

ali_ua: configures a User-Agent blacklist or whitelist.

ua: specifies user agents. You can enter wildcard characters (*) or multiple values. Separate values with vertical bars (|). Example: *curl*|*IE*|*chrome*|*firefox*.

type: specifies the type of the list, which can be blacklist or whitelist. The whitelist and blacklist are mutually exclusive.

Response parameters

Parameter Type Example Description
RequestId String 04F0F334-1335-436C-A1D7-6C044FE73368

The ID of the request.

Examples

Sample requests

http(s)://dcdn.aliyuncs.com/?Action=BatchSetDcdnDomainConfigs
&DomainName=example.com,example.org
&Functions=[{"functionArgs":[{"argName":"domain_name","argValue":"example.com"}],"functionName":"set_req_host_header"}]
&<Common request parameters>

Sample success responses

XML format

<BatchSetDcdnDomainConfigsResponse>
  <RequestId>04F0F334-1335-436C-A1D7-6C044FE73368</RequestId>
  <DomainConfigModel>
        <DomainName>example.com</DomainName>
        <ConfigId>1234567</ConfigId>
        <FunctionName>set_req_host_header</FunctionName>
  </DomainConfigModel>
</BatchSetDcdnDomainConfigsResponse>

JSON format

{
    "RequestId": "04F0F334-1335-436C-A1D7-6C044FE73368",
    "DomainConfigModel": [
        {
            "DomainName": "example.com",
            "ConfigId": 1234567,
            "FunctionName": "set_req_host_header"
        }
    ]
}

Error codes

HttpCode Error code Error message Description
400 InvalidFunctions.Malformed The specified Functions is invalid. The error message returned because the value specified for the Functions parameter is invalid. Specify a valid value.
400 InvalidArgValue.Malformed The specified ArgValue is invalid. The error message returned because the value specified for the ArgValue parameter is invalid. Specify a valid value.
400 Invalid%s.ValueNotSupported [%s] is not supported. The error message returned because the specified configuration is not supported.
400 Invalid%s.Malformed The specified ArgValue [%s] is invalid. The error message returned because the value specified for the ArgValue parameter is invalid. Specify a valid value.
400 MissingParameter You must specify ArgValue. The error message returned because one or more required parameters are not specified.

For a list of error codes, visit the API Error Center.