Built-In Variables

Built-in variables in API7 Enterprise are pre-defined variables that can be directly referenced in configurations. They are often used in plugin configurations, route matching, and log customization.

API7 Enterprise supports two types of built-in variables:

• NGINX Variables
• APISIX Variables

These variables are evaluated in a given order.

NGINX Variables

NGINX provides a set of variables that can be used to access various request-specific information.

Some commonly used variables include:

• upstream_addr
• remote_addr
• request_uri
• server_name
• uri
• http_user_agent

See the complete list of NGINX variables for more information.

APISIX Variables

In addition to NGINX variables, APISIX offers a variety of built-in variables:

Variable Name	Description
post_arg_*	HTTP POST form data when the content type is application/x-www-form-urlencoded. The asterisk is to be replaced with the actual name of the POST form data.
post_arg.*	HTTP POST body parameter when the content type is application/json, application/x-www-form-urlencoded, or multipart/form-data. The asterisk is to be replaced with the actual name of the POST parameter. Supports JSON path-like selection, such as post_arg.model.version and post_arg.messages[*].content[*].type.
arg_*	URL query string. The asterisk is to be replaced with the actual query parameter name.
http_*	HTTP request header. The asterisk is to be replaced with the actual name of the header.
cookie_*	Request cookie. The asterisk is to be replaced with the actual name of the cookie.
balancer_ip	Upstream server IP.
balancer_port	Upstream server port.
consumer_name	Consumer username.
consumer_group_id	Consumer group ID.
graphql_name	GraphQL operation name.
graphql_operation	GraphQL operation type.
graphql_root_fields	GraphQL root fields.
route_id	Route ID.
route_name	Route name.
service_id	Service ID.
service_name	Service name.
resp_body	HTTP response body.
mqtt_client_id	Client ID in MQTT protocol.
redis_cmd_line	Redis command.
rpc_time	RPC request round-trip time.
external_user.*	External user information (available starting from API7 Enterprise 3.8.19). This variable is injected by the openid-connect plugin and by developer OAuth credentials, making it available to other plugins. For example, limit-count-advanced can enforce rate limiting by username when key is set to ${external_user.preferred_username}.

Evaluation Order

API7 Enterprise evaluates variables in the given order:

1. APISIX Variables
2. NGINX Variables

If a variable is successfully sourced in custom variables, API7 Enterprise will not continue to look in APISIX variables or NGINX variables.

In other words, custom variables will overwrite variables of the same names defined in APISIX variables or NGINX variables, to better meet requirements of your specific use cases.

Variable Syntax

A valid variable name can include letters, underscores (_), and periods (.).

Escaped variables with a backslash (\) are not treated as variables, for example, \$variable_name.

Simple and Braced Forms

A variable can be referenced in two forms:

• $variable_name
• ${variable_name}

Both syntaxes are supported; however, the braced form is required in certain contexts to ensure correct parsing.

The unbraced form $variable is valid when the following character cannot be part of a variable name. For example, the following forms are equivalent:

• $http_host and ${http_host}
• $arg_username-$arg_userid and ${arg_username}-${arg_userid}

When a variable is followed by a character that could belong to a variable name (such as a letter), the parser will incorrectly interpret it as a longer variable name. For example, with https://$http_baseurl.com, the parser would treat the entire string http_baseurl.com as the variable, which is incorrect. In this case, you should use the braced form https://${http_baseurl}.com to clearly delimit the variable.

You would also need the braced form if you use the ?? operator.

Default Values with ??

You can specify a default value for a variable using the ?? operator. If the variable is undefined or has no value, the value after the operator will be used.

Example	Behavior
${http_username ?? anonymous}	If the HTTP request header username has a value, it is used; otherwise use anonymous.
${http_count ?? 10}	If the HTTP request header count has a value, it is used; otherwise use 10.