内置变量

API7 企业版中的内置变量是可以在配置中直接引用的预定义变量。它们通常用于插件配置、路由匹配和日志自定义。

API7 企业版支持两种类型的内置变量：

• NGINX 变量
• APISIX 变量

这些变量按照特定的顺序进行求值。

NGINX 变量

NGINX 提供了一组变量，可用于访问各种特定的请求信息。

一些常用的变量包括：

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

有关更多信息，请参阅 NGINX 变量的完整列表。

APISIX 变量

除了 NGINX 变量 之外，APISIX 还提供了各种内置变量：

变量名称	描述
post_arg_*	内容类型为 application/x-www-form-urlencoded 时的 HTTP POST 表单数据。星号将替换为 POST 表单数据的实际名称。
post_arg.*	内容类型为 application/json、application/x-www-form-urlencoded 或 multipart/form-data 时的 HTTP POST 请求体参数。星号替换为 POST 参数的实际名称。支持类似 JSON path 的选择器，如 post_arg.model.version 和 post_arg.messages[*].content[*].type。
arg_*	URL 查询字符串。星号替换为实际的查询参数名称。
http_*	HTTP 请求头。星号替换为实际的请求头名称。
cookie_*	请求 Cookie。星号替换为实际的 Cookie 名称。
balancer_ip	上游服务器 IP。
balancer_port	上游服务器端口。
consumer_name	消费者用户名。
consumer_group_id	消费者组 ID。
graphql_name	GraphQL 操作名称。
graphql_operation	GraphQL 操作类型。
graphql_root_fields	GraphQL 根字段。
route_id	路由 ID。
route_name	路由名称。
service_id	服务 ID。
service_name	服务名称。
resp_body	HTTP 响应体。
mqtt_client_id	MQTT 协议中的客户端 ID。
redis_cmd_line	Redis 命令。
rpc_time	RPC 请求往返时间。
external_user.*	外部用户信息（从 API7 企业版 3.8.19 开始提供）。该变量由 openid-connect 插件和开发者 OAuth 凭证注入，可供其他插件使用。例如，当 key 设置为 ${external_user.preferred_username} 时，limit-count-advanced 可以按用户名执行速率限制。

评估顺序

API7 企业版按以下给定顺序评估变量：

1. APISIX 变量
2. NGINX 变量

如果在自定义变量中成功获取到变量值，API7 企业版将不再继续在 APISIX 变量或 NGINX 变量中查找。

换句话说，自定义变量将覆盖在 APISIX 变量或 NGINX 变量中定义的同名变量，以更好地满足你特定用例的需求。

变量语法

有效的变量名称可以包含字母、下划线（_）和句点（.）。

使用反斜杠（\）转义的变量不被视为变量，例如 \$variable_name。

简单格式和带括号格式

变量可以通过两种格式进行引用：

• $variable_name
• ${variable_name}

这两种语法都受支持；然而，在某些上下文中需要带括号的格式以确保正确的解析。

如果后面的字符不能作为变量名的一部分，无括号的 $variable 格式是有效的。例如，以下格式是等效的：

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

当变量后跟一个可能属于变量名的字符（例如字母）时，解析器会将其错误地解释为较长的变量名。例如，对于 https://$http_baseurl.com，解析器会将整个字符串 http_baseurl.com 视为变量，这是不正确的。在这种情况下，你应该使用带括号的格式 https://${http_baseurl}.com 以清楚地界定变量。

如果你使用 ?? 运算符，你也需要带括号的格式。

使用 ?? 提供默认值

你可以使用 ?? 运算符为变量指定默认值。如果该变量未定义或没有值，则将使用运算符之后的值。

示例	行为
${http_username ?? anonymous}	如果 HTTP 请求头 username 有值则使用它；否则使用字符串 anonymous。
${http_count ?? 10}	如果 HTTP 请求头 count 有值则使用它；否则使用数字 10。