All Products
Search

This Product

    ApsaraVideo VOD:Request processing functions

    Document Center

    ApsaraVideo VOD:Request processing functions

    Last Updated:Jul 10, 2026

    Syntax, parameters, return values, and examples of request processing functions.

    add_req_header

    Item Description
    Syntax add_req_header(name, value [, append])
    Description Adds a request header to requests before they are redirected to the origin server.
    Parameter
    • name: the name of the request header that you want to add. Data type: string.
    • value: the value of the request header that you want to add. Data type: string.
    • append: specifies whether to append a request header with the specified value if a request header with the same name already exists. Valid values: true and false. Default value: false. Data type: Boolean. If you set this parameter to false, the specified value will overwrite the value of the existing request header.
    Return value Returns true by default and returns false if the specified request header is invalid.
    Example 
    add_req_header('USER-DEFINED-REQ-1', '1')
add_req_header('USER-DEFINED-REQ-1', 'x', true)
add_req_header('USER-DEFINED-REQ-2', '2')
del_req_header('USER-DEFINED-REQ-2')

Note: The following request headers are added:
USER-DEFINED-REQ-1: 1
USER-DEFINED-REQ-1: x

The USER-DEFINED-REQ-2 header is added and then deleted. Therefore, the USER-DEFINED-REQ-2 request header is not included in requests that are redirected to the origin server.

    del_req_header

    Item Description
    Syntax del_req_header(name)
    Description Deletes a request header from requests before they are redirected to the origin server.
    Parameter name: the name of the request header that you want to delete. Data type: string.
    Return value Returns true by default and returns false if the specified request header is invalid.
    Example 
    add_req_header('USER-DEFINED-REQ-1', '1')
add_req_header('USER-DEFINED-REQ-1', 'x', true)
add_req_header('USER-DEFINED-REQ-2', '2')
del_req_header('USER-DEFINED-REQ-2')

Note: The following request headers are added:
USER-DEFINED-REQ-1: 1
USER-DEFINED-REQ-1: x

The USER-DEFINED-REQ-2 header is added and then deleted. Therefore, the USER-DEFINED-REQ-2 request header is not included in requests that are redirected to the origin server.

    add_rsp_header

    Item Description
    Syntax add_rsp_header(name, value [, append])
    Description Adds a response header.
    Parameter
    • name: the name of the response header that you want to add. Data type: string.
    • value: the value of the response header that you want to add. Data type: string.
      You can specify one of the following expressions for the value parameter to enable the value to be dynamically replaced in the response phase:
      • ${x}: replaced with the value of ngx.var.x.
      • @{y}: replaced with the value of response header y.
    • append: specifies whether to append a response header with the specified value if a response header with the same name already exists. Valid values: true and false. Default value: false. Data type: Boolean. If you set this parameter to false, the specified value will overwrite the value of the existing response header.
    Return value Returns true by default and returns false if the specified response header is invalid.
    Example 
    add_rsp_header('USER-DEFINED-RSP-1', '1')
add_rsp_header('USER-DEFINED-RSP-1', 'x', true)
add_rsp_header('USER-DEFINED-RSP-2', '2')
del_rsp_header('USER-DEFINED-RSP-2')

Note: The following response headers are added:
USER-DEFINED-RSP-1: 1
USER-DEFINED-RSP-1: x

The USER-DEFINED-RSP-2 header is added and then deleted. Therefore, the USER-DEFINED-RSP-2 header is not included in the responses.

    del_rsp_header

    Item Description
    Syntax del_rsp_header(name)
    Description Deletes a response header.
    Parameter name: the name of the response header that you want to delete. Data type: string.
    Return value Returns true by default and returns false if the specified response header is invalid.
    Example 
    add_rsp_header('USER-DEFINED-RSP-1', '1')
add_rsp_header('USER-DEFINED-RSP-1', 'x', true)
add_rsp_header('USER-DEFINED-RSP-2', '2')
del_rsp_header('USER-DEFINED-RSP-2')

The following response headers are added:
USER-DEFINED-RSP-1: 1
USER-DEFINED-RSP-1: x

The USER-DEFINED-RSP-2 header is added and then deleted. Therefore, the USER-DEFINED-RSP-2 header is not included in the responses.

    encode_args

    Item Description
    Syntax encode_args(d)
    Description Converts the k/v pairs in the dictionary specified by d to a URI-encoded string in the format of k1=v1&k2=v2.
    Parameter d: the dictionary that you want to convert.
    Return value Returns a URI-encoded string.
    Example 
    my_args = []
set(my_args, 'signature', 'da9dc4b7-87ae-4330-aaaf-e5454e2c2af1')
set(my_args, 'algo', 'private sign1')
my_args_str = encode_args(my_args)
add_rsp_header('X-DSL-ENCODE-ARGS', my_args_str)

to_args = decode_args(my_args_str)
if get(to_args, 'algo') {
    add_rsp_header('X-DSL-DECODE-ARGS-ALGO', get(to_args, 'algo'))
}
if get(to_args, 'signature') {
    add_rsp_header('X-DSL-DECODE-ARGS-SIGN', get(to_args, 'signature'))
}

Output: The following response headers are added:
X-DSL-ENCODE-ARGS: signature=da9dc4b7-87ae-4330-aaaf-e5454e2c2af1&algo=private%20sign1
X-DSL-DECODE-ARGS-ALGO: private sign1
X-DSL-DECODE-ARGS-SIGN: da9dc4b7-87ae-4330-aaaf-e5454e2c2af1

    decode_args

    Item Description
    Syntax decode_args(s)
    Description Converts a URI-encoded string in the format of k1=v1&k2=v2 to a string of dictionary type.
    Parameter s: the string that you want to convert.
    Return value Returns a dictionary object converted from the specified string.
    Example 
    my_args = []
set(my_args, 'signature', 'da9dc4b7-87ae-4330-aaaf-e5454e2c2af1')
set(my_args, 'algo', 'private sign1')
my_args_str = encode_args(my_args)
add_rsp_header('X-DSL-ENCODE-ARGS', my_args_str)

to_args = decode_args(my_args_str)
if get(to_args, 'algo') {
    add_rsp_header('X-DSL-DECODE-ARGS-ALGO', get(to_args, 'algo'))
}
if get(to_args, 'signature') {
    add_rsp_header('X-DSL-DECODE-ARGS-SIGN', get(to_args, 'signature'))
}

Output: The following response headers are added:
X-DSL-ENCODE-ARGS: signature=da9dc4b7-87ae-4330-aaaf-e5454e2c2af1&algo=private%20sign1
X-DSL-DECODE-ARGS-ALGO: private sign1
X-DSL-DECODE-ARGS-SIGN: da9dc4b7-87ae-4330-aaaf-e5454e2c2af1

    rewrite

    Item Description
    syntax rewrite(url, flag [, code])
    description Rewrites the URL or issues a redirect.
    parameter
    • url: The target URL. Type: string.
      • When flag is redirect or break, this parameter specifies the new URI path. Only the path is rewritten.
      • When enhance_redirect or enhance_break, this parameter specifies the new URI that replaces the original path and query parameters.
    • : The rewrite mode. Type: string.
      • code: Rewrites only the URI path and keeps the original query parameters. This action issues a redirect to the new URL. The default status code is . You can specify a different status code (301, 303, 307, or 308) by using the parameter.
      • break: Rewrites only the URI path to the specified url and keeps the original query parameters. The request processing continues internally with the new URI.
      • redirect: Similar to , but replaces both the URI path and query parameters with the provided .
      • break: Similar to , but replaces both the URI path and query parameters with the provided .
    • code: (Optional) The HTTP status code to use for redirects. Type: numeric.

      This parameter is effective only when flag is redirect or enhance_redirect.
    return value
    • trueFor rewrite operations ( and ), the function returns .
    • For redirect operations (redirect and enhance_redirect), the function does not return, as it terminates the request flow.
    example 
    if and($arg_mode, eq($arg_mode, 'rewrite:enhance_break')) {
  rewrite('/a/example/examplefile.txt?k=v', 'enhance_break')
}
// Rewrites the URI and query string for origin requests and cache lookups 
// to /a/example/examplefile.txt?k=v.

if and($arg_mode, eq($arg_mode, 'rewrite:enhance_redirect')) {
  rewrite('/a/example/examplefile.txt?k=v', 'enhance_redirect')
}
if and($arg_mode, eq($arg_mode, 'rewrite:enhance_redirect_301')) {
  rewrite('/a/example/examplefile.txt?k=v', 'enhance_redirect', 301)
}
// Issues a 302 (default) or 301 redirect to /a/example/examplefile.txt?k=v.

if and($arg_mode, eq($arg_mode, 'rewrite:break')) {
  rewrite('/a/example/examplefile.txt', 'break')
}
// Rewrites the URI path to /a/example/examplefile.txt for origin requests and 
// cache lookups, keeping the original query string.

if and($arg_mode, eq($arg_mode, 'rewrite:redirect')) {
  rewrite('/a/example/examplefile.txt', 'redirect')
}
if and($arg_mode, eq($arg_mode, 'rewrite:redirect_301')) {
  rewrite('/a/example/examplefile.txt', 'redirect', 301)
}
// Issues a 302 (default) or 301 redirect to /a/example/examplefile.txt, 
// keeping the original query string.

    say

    Item Description
    Syntax say(arg)
    Description Prints a response body and appends a newline character at the end of the output.
    Parameter arg: the content of the response body. Data type: any type.
    Return value None.
    Example 
    say('hello')
print('byebye')
print('byebye')

Output:
hello
byebyebyebye

    print

    Item Description
    Syntax print(arg)
    Description Prints a response body without appending a newline, unlike the say() function.
    Parameter arg: the content of the response body. Data type: any type.
    Return value None.
    Example 
    say('hello')
print('byebye')
print('byebye')

Output:
hello
byebyebyebye

    exit

    Item Description
    Syntax exit(code [, body])
    Description Ends the current request with the specified code. If body is specified, the response includes that body content.
    Parameter
    • code: the HTTP status code to return.
    • body: the response body.
    Return value None.
    Example
    • Example 1 
      if not($arg_key) {
    exit(403)
}
Note: If a request does not include the key parameter, the request is denied and the HTTP 403 status code is returned. 

if not($cookie_user) {
    exit(403, 'not cookie user')
}
Note: If a request does not include cookie_user, the request is denied and a response that contains the body "not cookie user" is returned with the HTTP 403 status code.

if not(0) {
    exit(403)
}
Note: The not(0) function returns a value of false.

if not(false) {
    exit(403)
}
Note: The not(false) function returns a value of true.
    • Example 2 
      pcs = capture_re($request_uri,'^/([^/]+)/([^/]+)([^?]+)\?(.*)')
sec1 = get(pcs, 1)
sec2 = get(pcs, 2)
sec3 = get(pcs, 3)
if or(not(sec1), not(sec2), not(sec3)) {
   add_rsp_header('X-TENGINE-ERROR', 'auth failed - missing necessary uri set')
   exit(403)
}
digest = md5(concat(sec1, sec3))
if ne(digest, sec2) {
    add_rsp_header('X-TENGINE-ERROR', 'auth failed - invalid digest')
    exit(403)
}

    get_rsp_header

    Item Description
    Syntax get_rsp_header(str)
    Description Retrieves a response header.
    Parameter str: the response header that you want to obtain. Data type: string.
    Return value Returns the value of the specified response header.
    • If the specified response header exists, the response header is returned. The data type of the response header is dictionary or string.
    • If the specified response header does not exist, a value of false is returned.
    Example 
    ct = get_rsp_header('content-type')
if ct {
    add_rsp_header('origin-content-type', 'is')
} else {
      add_rsp_header('origin-content-type', 'no')
}

    add_rsp_cookie

    Item Description
    Syntax add_rsp_cookie(k, v [,properties])
    Description Sets the response cookie. Each time the function is called, a new Set-Cookie response header is generated.
    Parameter
    • k: the name of the cookie.
    • v: the value of the cookie.
    • properties: the properties of the cookie. This parameter is optional. For more information, see Set-Cookie.
    Return value Returns true if the cookie is set, or false if the operation fails.
    Example 
    add_rsp_cookie('user', 'edgescript')

add_rsp_cookie('login_time', tostring(now()), [
    'path' = '/'
])

expires = cookie_time(time())
add_rsp_cookie('psid', 'SDF93745HFSDF2934JKHG', [
    'path' = '/play',
    'domain' = 'foo.com',
    'secure' = true,
    'httponly' = true,
    'expires' = expires,
    'max_age' = 100,
    'samesite' = 'Strict',
    'extension' = 'xxt3s'
])
    Response:
    Set-Cookie: user=edgescript
Set-Cookie: login_time=1582538968.912; Path=/
Set-Cookie: psid=SDF93745HFSDF2934JKHG; Expires=Mon, 24-Feb-20 10:09:28 GMT; Max-Age=100; Domain=foo.com; Path=/play; Secure; HttpOnly; SameSite=Strict; xxt3s