Configures a domain name to be accelerated in the staging environment.

Note 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 software development kits (SDKs).

Request parameters

Parameter Type Required Example Description
Action String Yes SetCdnDomainStagingConfig

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

DomainName String Yes example.com

The accelerated domain name. You can specify only one domain name.

Functions String Yes [{"functionArgs":[{"argName":"enable","argValue":"on"},{"argName":"pri","argValue":"1"},{"argName":"rule","argValue":"xxx"}],"functionName":"edge_function"}]

The features that you want to configure, which can be queried by calling BatchSetCdnDomainConfig. Format:


[{"functionArgs":[{"argName":"Parameter key","argValue":"Parameter value"},{"argName":"xx","argValue":"xx"}],"functionName": Feature name"}]
                                

Separate parameters with commas (,).

Descriptions of functions

Some features, such as EdgeScript functions (edge_function), support more than one configuration record. To update one of the configuration records, set the ConfigId parameter to specify the record.


[{"functionArgs":[{"argName":"enable","argValue":"on"},{"argName":"pri","argValue":"1"},{"argName":"rule","argValue":"yyy"}],"ConfigId":123456,"functionName":"edge_function"}]
            

Note: Specify parameter values in a string.

Feature

Parameter

referer_white_list_set: configures a referer whitelist.

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

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

referer_black_list_set: configures a referer blacklist.

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

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

filetype_based_ttl_set: sets a time-to-live (TTL) value for specified file types.

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

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

weight: specifies the weight. Maximum value: 99. Minimum value: 1. A greater value indicates a higher priority.

path_based_ttl_set: sets an expiration rule for specified directories.

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

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

weight: the weight of the directory expiration. Maximum value: 99. Minimum value: 1. A greater value indicates a higher priority.

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

oss_bucket_id: specifies the endpoint of the OSS bucket.

ip_black_list_set: configures an IP blacklist.

ip_list: specifies the IP addresses to be added to the blacklist. Separate IP addresses with commas (,).

ip_allow_list_set: configures an IP whitelist.

ip_list: specifies the IP addresses to be added to the whitelist. Separate IP addresses with commas (,).

ip_white_list_set: configures an IP whitelist for rate limiting.

ip_list: specifies the IP addresses to be added to the whitelist. Separate IP addresses with commas (,).

error_page: redirects requests to a specified error page.

error_code: specifies the HTTP status code.

rewrite_page: specifies the error page to which requests are redirected when the specified HTTP status code occurs.

set_req_host_header: configures custom headers 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: retains specified URL parameters.

hashkey_args: specifies the URL parameters to be retained. Separate multiple parameters with commas (,). You can specify up to 10 parameters to be retained.

disable: A value of on indicates that all URL parameters are deleted. A value of off indicates that all URL parameters are retained. The hashkey_args setting has a higher priority. Even if you have set this parameter to on, the parameters specified in hashkey_args are retained.

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

aliauth: configures Alibaba Cloud authentication.

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

auth_key1: specifies the primary cryptographic key. auth_key2: specifies the secondary cryptographic key.

ali_auth_delta: customizes the buffer time for authentication.

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

key: specifies the 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 a request header. Valid values: add, delete, modify, and rewrite. add: adds a request header. delete: deletes a request header. modify: modifies a request header. rewrite: replaces a request header.

duplicate: specifies whether duplicate response headers are allowed. Valid values: on and off.

header_source: searches for the source of the request header.

header_destination: replaces the request header.

match_all: specifies whether to match all requests. 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.

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

set_req_header is supported by version 1. We recommend that you use origin_request_header, which is supported by version 2 and provides more features.

key: specifies the name of the request header.

value: specifies the value of the request 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 to retrieve content from the origin server based on HTTP range requests.

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

video_seek: configures video seeking.

enable: specifies whether to enable this 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.

ali_remove_args: deletes URL parameters.

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

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

https_tls_version: configures the TLS protocol.

tls10: configures TLS 1.0. Valid values: on and off. Default value: on.

tls11: configures TLS 1.1. Valid values: on and off. Default value: on.

tls12: configures TLS 1.2. Valid values: on and off. Default value: on.

tls13: configures TLS 1.3. Valid values: on and off. Default value: off.

HSTS: configures HSTS.

enabled: specifies whether to enable this 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: seconds. We recommend that you set the value to 5184000. 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: specifies a time-to-live (TTL) value for HTTP status codes based on file types.

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

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

path_force_ttl_code: specifies a TTL value for HTTP status codes based on directories.

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 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 HTML optimization.

enable: specifies whether to enable the 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 this feature. This parameter is required. Valid values: on and off.

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

limit_rate: configures traffic throttling for individual requests.

ali_limit_rate: specifies the maximum amount of data that can be transmitted per second after traffic throttling is triggered, such as 200 KB or 1 MB. Unit: byte/s. This parameter is required.

ali_limit_rate_after: specifies the maximum amount of data that can be transmitted before traffic throttling is triggered. Unit: byte/s.

traffic_limit_arg: specifies the name of the URL parameter based on which traffic throttling is triggered. Example: rate.

traffic_limit_unit: specifies the unit for traffic throttling. Valid values: k, m, and g. For example, when the ali_limit_rate_after parameter is set to 1, the maximum data transfer rate can be 1 MB/s, 1 KB/s, or 1 GB/s.

ali_limit_start_hour: specifies the start time of traffic throttling. Valid values: 0 to 24. Default: 0. The start time must be earlier than the end time.

ali_limit_end_hour: specifies the end time of traffic throttling. Valid values: 0 to 24. Default: 24. The end time must be later than the start time.

brotli: configures Brotli compression.

enable: specifies whether to enable the 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 whitelist or blacklist.

ua: specifies the user agents that you want to add to the list.

type: specifies the type of the user agent list. Valid values: black and white.

set_l2_req_header: configures HTTP headers for requests that are sent to L2 CDN nodes.

set_l2_req_header is supported by version 1. We recommend that you use origin_request_header, which is supported by version 2 and provides more features.

key: specifies the name of the header.

value: specifies the value of the header. Enter null if you want to delete the header.

host_redirect: configures URL rewrite.

regex: specifies the URL to be rewritten, for example, ^/$.

replacement: specifies the new 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.

ali_video_split: configures audio extraction.

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

ipv6: configures IPv6.

switch: specifies whether to enable IPv6. A value of on enables IPv6. A value of off disables IPv6. This parameter is required.

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

ali_video_preview: configures video preview.

enable: specifies whether to enable this feature. This parameter is required. Valid values: on and off. The video preview feature supports the TS and MP3 formats. For FLV and MP4 video files, visitors can advance and rewind videos.

ali_video_preview_argument: specifies the length of the videos that can be previewed by visitors. The parameter value must be measured in seconds. This parameter is required.

default_ttl_code: sets a TTL value for specified HTTP status codes.

default_ttl_code: specifies a TTL value for HTTP status codes. Unit: seconds. Example: 4xx=3, 200=3600, and 5xx=1. Separate HTTP status codes with commas (,). This parameter is required.

back_to_origin_argument_rewrite: configures parameter rewrite.

Action priorities: Add > Delete > Reserve > Modify. Separate parameters with spaces.

delete_argument: specifies the parameters to be deleted.

save_argument: specifies the parameters to be retained. Only the specified parameters are retained. The Add and Delete rules take effect at the same time.

ignore_all_argument: specifies whether to delete all parameters in requests that are redirected to the origin server. Valid values: on and off. However, parameters added by the Add action are reserved.

add_argument: specifies parameters to be added. The Add action has the highest priority.

modify_argument: specifies parameters to be modified. The Modify action has the lowest priority. Parameters specified by the Delete action are not reserved.

back_to_origin_url_rewrite: configures URL rewrite.

source_url: specifies the URL to be rewritten. This parameter is required.

target_url: specifies the final URL. This parameter is required.

flag: specifies an action. Valid values: null, break, and enhance_break. null: continues to apply subsequent rewrite rules after applying the current rule. break: stops applying subsequent rewrite rules after applying the current rule. enhance_break: applies the current rewrite rule to both the URL and its parameters, and then stops applying subsequent rules. This action is also effective on FLV streaming.

edge_function: configures EdgeScript.

Required parameters:

rule: the domain-specific language (DSL) script.

pri: the priority of the script.

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

Optional parameters:

name: the name of the rule. The name supports only letters and underscores (_).

pos: specifies the position where the script is executed.

brk: specifies that after the current script is matched, the subsequent scripts at the specified position are skipped.

option: specifies extensions that are used to perform response header debugging.

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

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

follow_302: configures 302 redirects.

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

max_tries: The maximum number of back-to-origin times. Default value: 2. Valid values: 1 to 6. Number of back-to-origin times - 1 = Number of 302 redirects.

retain_args: Valid values are on and off. If you set the value to on, request parameters are retained in 302 redirects. Default value: off.

retain_header: Valid values are on and off. If you set the value to on, request headers are retained in 302 redirects. Default value: off.

aws_s3_bucket: specifies the Amazon Web Services (AWS) Simple Storage Service (S3) buckets that require authentication.

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

bucketname: specifies the names of the AWS S3 buckets.

accesskey: required. It specifies the access key issued by AWS.

secretkey: specifies the AWS access key secret. This parameter is required.

region: specifies the Region where the AWS S3 bucket is deployed. This parameter is required.

origin_request_header: configures HTTP request headers.

header_operation_type: specifies the action to be performed on the request header. Valid values: add, delete, modify, and rewrite. add: adds a header. delete: deletes a header. modify: modifies a header. rewrite: rewrites a header. This parameter is required.

header_name: required. It specifies the key of the request header.

header_value: specifies the value of the request header.

duplicate: specifies whether duplicate request headers are allowed. Valid values: on and off.

header_source: searches for the source of the response header.

header_destination: replaces the response header.

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

origin_response_header: configures HTTP response headers.

header_operation_type: specifies the action to be performed on the response header. This parameter is required. Valid values: add, delete, modify, and rewrite. add: adds a response header. delete: deletes a response header. modify: modifies a response header. rewrite: rewrites a response header.

header_name: required. It specifies the key of the response header.

header_value: specifies the value of the response header.

duplicate: specifies whether duplicate response headers are allowed. Valid values: on and off.

header_source: searches for the source of the response header.

header_destination: replaces the response header.

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

origin_dns_host: specifies the origin server.

ali_origin_dns_host: specifies the domain name used in back-to-origin DNS queries. This parameter is required.

self_defined_cachekey: specifies the custom cachekey.

uri: the URI.

args: parameter operations.

headers: the HTTP header.

variable: custom variables.

image_transform: CDN image conversion.

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

filetype: the image formats that support conversion. Separate formats with vertical bars (|). This parameter is required.

webp: specifies whether to automatically convert images to the WebP format if the client supports the WebP format. WebP images have smaller sizes. Valid values: on and off.

orient: specifies whether to enable automatic rotation for images. Valid values: on and off. This parameter takes effect for only images that support automatic rotation.

slim: specifies whether to enable image compression without changing the resolution, size, or format.

origin_host: specifies the origin host.

origin: the origin server. This parameter is required.

host: the host. This parameter is required.

ali_origin_port_scheme: specifies the port and protocol of the origin server.

port: This parameter is required. If you set scheme to follow, set the value in the http:80|https:443 format.

scheme: This parameter is required. Valid values: follow, http, and https.

cdn_remote_auth: the remote authentication feature.

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

remote_auth_addr: the address of the authentication server. This parameter is required. Format: <props>https://cdn.aliyun.com/auth or <props>http://123.123.123.123/auth.

remote_auth_method: the request method. This parameter is required. Valid values: get, post, and head.

remote_auth_type: the type of the authentication file. This parameter is required. A value of all specifies all types. Separate different file types with vertical bars (|). The value is case-sensitive. For example, jpg is different from JPG.

remote_auth_reserve_args: specifies whether to retain parameters. A value of all specifies to retain all parameters. Separate multiple parameters with vertical bars (|). A value of ali_delete_all_args specifies to delete all URL parameters. The value is case-sensitive. For example, key is different from KEY. This parameter is required.

remote_auth_custom_args: adds custom parameters. Separate parameters with vertical bars (|). The value is case-sensitive. For example, key is different from KEY. This parameter is optional.

remote_auth_reserve_header: specifies whether to retain request headers. A value of all specifies to retain all request headers. Separate request headers with vertical bars (|). A value of ali_delete_all_headers specifies to delete all request headers. The value is case-insensitive. For example, http_remote_addr is the same as HTTP_Remote_Addr. This parameter is required.

remote_auth_custom_header: adds custom request headers. Separate request headers with vertical bars (|). The value is case-insensitive. For example, http_remote_addr is the same as HTTP_Remote_Addr. This parameter is optional.

remote_auth_success_code: specifies the response code to return to CDN when the authentication is successful. This parameter is required. For example, if you set the value to 200, the authentication server will return the response code 200 to CDN when the authentication is successful.

remote_auth_fail_code: specifies the response code to return to CDN when the authentication fails. This parameter is required. For example, if you set the value to 403, the authentication server will return the response code 403 to CDN when the authentication fails.

remote_auth_fail_resp_code: specifies the response code to return to the user when the authentication fails. This parameter is required. For example, if you set the value to 403, CDN will return the response code 403 to the user when the authentication fails.

remote_auth_timeout: specifies the timeout period for authentication. This parameter is required. Unit: milliseconds. Example: 500. Maximum value: 3000.

remote_auth_timeout_action: specifies the action after the authentication times out. This parameter is required. Valid values: pass and reject. If you set the value to pass, CDN allows user requests after the authentication fails. If you set the value to reject, CDN returns the specified response code to the user and rejects user requests.

hls_token_rewrite: the M3U8 encryption and rewrite feature.

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

hls_token_arg_name: The name of the appended parameter. If you do not set the parameter, MtsHlsUriToken is used as the name of the appended parameter.

Response parameters

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

The ID of the request.

Examples

Sample requests

http(s)://cdn.aliyuncs.com/?Action=SetCdnDomainStagingConfig
&DomainName=example.com
&Functions=[{"functionArgs":[{"argName":"enable","argValue":"on"},{"argName":"pri","argValue":"1"},{"argName":"rule","argValue":"xxx"}],"functionName":"edge_function"}]
&<Common request parameters>

Sample success responses

XML format

<SetCdnDomainStagingConfigResponse>
  <RequestId>04F0F334-1335-436C-A1D7-6C044FE73368</RequestId>
</SetCdnDomainStagingConfigResponse>

JSON format

{
  "RequestId": "04F0F334-1335-436C-A1D7-6C044FE73368" 
}

Error codes

HttpCode Error code Error message Required
400 ConfigurationConflicts The staging environment has a configuration in effect and cannot modify the production environment configuration. The error message returned because the configurations of the staging environment are different from those of the production environment. You cannot directly modify the configurations of the production environment. Go to the staging environment to complete the configurations and publish the specified configurations to the production environment.

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