内置变量
API7 企业版中的内置变量是预定义的变量,可直接在配置中引用。它们常用于插件配置、路由匹配和日志定制。
API7 企业版支持两种类型的内置变量:
- NGINX 变量
- APISIX 变量
这些变量会按照变量解析顺序进行解析。
NGINX 变量
NGINX 提供了一组变量,可用于访问各种请求特定的信息。
一些常用的变量包括:
upstream_addrremote_addrrequest_uriserver_nameurihttp_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 路径的选择,例如 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 Enterprise 3.8.19 起可用)。该变量由 openid-connect 插件和开发者 OAuth 凭据注入,可供其他插件使用。例如,将 key 设置为 ${external_user.preferred_username} 时,limit-count-advanced 可以按用户名进行限流。 |
变量解析顺序
API7 企业版按以下顺序解析变量:
- APISIX 变量
- NGINX 变量
如果某个变量已在自定义变量中成功获取,API7 企业版将不再继续查找 APISIX 或 NGINX 中的同名变量。
换句话说,自定义变量会覆盖 APISIX 或 NGINX 中的同名变量,以确保更贴合您的实际业务需求。
变量语法
有效的变量名可以包含字母、下划线(_)和句点(.)。
使用反斜杠(\)转义的变量不会被当作变量,例如 \$variable_name。
简单形式与大括号形式
变量可以使用两种形式引用:
$variable_name${variable_name}
两种语法都受支持,但在某些上下文中必须使用大括号形式,以确保正确解析。
如果后面的字符不能作为变量名的一部分,无括号的 $variable 形式有效。例如,以下形式等价:
$http_host和${http_host}$arg_username-$arg_userid和${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。 |