跳到主要内容
版本：3.9.x

内置变量

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

API7 网关支持三种类型的内置变量：

  • NGINX 变量
  • APISIX 变量
  • 自定义变量

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

NGINX 变量​

NGINX 提供用于获取请求和响应信息的变量。

常用变量包括：

变量描述
upstream_addr上游服务器的 IP 地址和端口，或 UNIX 域套接字路径。
remote_addr客户端地址。
request_method请求方法，例如 GET 或 POST。
request_uri完整的原始请求 URI，包括参数。
server_name接受请求的服务器名称。
status响应状态。在 NGINX 确定响应状态之前，该值可能为 000。请在响应阶段的上下文中使用，例如调试会话采样规则或日志插件；不要用于路由匹配。
uri当前规范化的请求 URI，在请求处理过程中可能发生变化。
http_user_agentUser-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 名称。
methodHTTP 请求方法，例如 GET 或 POST。等效的 NGINX 变量为 request_method。
balancer_ip上游服务器 IP。
balancer_port上游服务器端口。
consumer_name消费者用户名。
consumer_group_id消费者组 ID。
graphql_nameGraphQL 操作名称。
graphql_operationGraphQL 操作类型。
graphql_root_fieldsGraphQL 根字段。
route_id路由 ID。
route_name路由名称。
service_id服务 ID。
service_name服务名称。
resp_bodyHTTP 响应体。
mqtt_client_idMQTT 协议中的客户端 ID。
redis_cmd_lineRedis 命令。
rpc_timeRPC 请求往返时间。
external_user.*外部用户信息。openid-connect 等身份认证插件可以填充该变量，供其他插件使用。例如，当 key 设置为 ${external_user.preferred_username} 时，limit-count-advanced 可以按用户名执行限流。
upstream_unresolved_hostDNS 解析前配置的上游主机或域名（上游节点的 domain 或 host）。自 API7 企业版 3.9.15 起可用。
警告

http_* 用于读取 HTTP 请求头，并不是其他内置变量的前缀。例如，http_uri、http_method 和 http_status 分别读取名为 Uri、Method 和 Status 的请求头。应使用 uri、method 和 status 表示请求路径、请求方法和响应状态。

API7 网关在编译表达式时不会验证这类请求头是否存在。如果客户端未发送该请求头，期望其具有值的条件可能不会匹配，也不会报错。

求值顺序​

API7 网关按以下给定顺序对变量求值：

  1. 自定义变量
  2. APISIX 变量
  3. 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。