跳到主要内容
版本:3.20.0

注册自定义变量

插件配置通常需要当前请求的相关值,例如请求头、路由详情或上游信息。APISIX 为常用值提供了内置变量。如果内置变量未提供所需的值,可以注册一个 Lua 函数来获取它。

自定义变量常用于在日志中记录路由上下文。以下示例演示如何在 APISIX 启动时或通过无服务器函数注册匹配路由的标签,并将标签加入 http-logger 的输出。最后一节演示如何用同样的方式为 proxy-rewrite 提供从路径中捕获的值。

前置条件​

  • 按照快速入门教程启动 APISIX。
  • 安装 cURL 以发送请求。
  • 准备一个记录 POST 请求的 HTTP 端点,并将其 URL 导出为 REMOTE_SERVER_ADDR。
  • 如果启用了 Admin API 身份验证,请将管理员角色的密钥导出为 ADMIN_API_KEY。

创建服务​

先创建一个服务,将请求日志发送到准备好的端点,并将请求代理至 httpbin.org:

curl "http://127.0.0.1:9180/apisix/admin/services" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
--data-binary @- <<EOF
{
"id": "srv_custom_var",
"plugins": {
"http-logger": {
"uri": "${REMOTE_SERVER_ADDR}"
}
},
"upstream": {
"nodes": {
"httpbin.org:80": 1
}
}
}
EOF

注册路由标签变量​

服务已可以发送日志。接下来,选择何时注册路由标签变量:

方式适用场景所需条件
启动钩子APISIX 一启动就需要使用该变量能够访问 APISIX 文件系统和静态配置,并在修改后重载 APISIX
无服务器函数需要随路由或服务管理变量注册需要一个在其他插件读取变量之前运行的无服务器前置函数

任选一种方式注册变量,然后继续配置日志格式。两种方式都能让日志插件读取匹配路由的标签。

在启动时注册​

如果需要在 APISIX 处理请求前使用该变量,请使用启动钩子。以下命令使用 Docker 快速入门中名为 apisix-quickstart 的容器。

将以下模块保存为 custom_variables.lua:

custom_variables.lua
require "apisix"
local core = require "apisix.core"

core.ctx.register_var("a6_route_labels", function(ctx)
local route = ctx.matched_route and ctx.matched_route.value
if route and route.labels then
return route.labels
end
return nil
end)

return true

启动钩子在 APISIX 初始化的早期阶段运行,因此该模块先导入 apisix,再导入 apisix.core。

将模块复制到 Docker 快速入门容器中:

docker exec apisix-quickstart mkdir -p /opt/apisix-custom
docker cp custom_variables.lua apisix-quickstart:/opt/apisix-custom/custom_variables.lua

编辑前,将当前生效的配置复制到当前目录:

docker cp apisix-quickstart:/usr/local/apisix/conf/config.yaml ./config.yaml

配置 Lua 模块搜索路径和启动钩子:

config.yaml
apisix:
extra_lua_path: "/opt/apisix-custom/?.lua"
lua_module_hook: custom_variables

将这些字段合并到 config.yaml 现有的 apisix 对象中。Lua 搜索路径用于定位自定义模块,模块钩子在 APISIX 初始化时加载该模块。

将更新后的配置复制回容器,验证配置,然后重载 APISIX:

docker cp config.yaml apisix-quickstart:/usr/local/apisix/conf/config.yaml
docker exec apisix-quickstart apisix test
docker exec apisix-quickstart apisix reload

如果使用其他部署方式,请将 Lua 模块挂载或复制到 APISIX 实例中,修改当前生效的 config.yaml,然后重载 APISIX。通过 Admin API 重载插件时,启动钩子不会重新加载。

有关加载自定义 Lua 代码的更多信息,请参阅使用 Lua 创建自定义插件。

通过无服务器函数注册​

如果需要随路由或服务管理变量注册,请使用无服务器函数插件。无服务器函数在配置的插件执行阶段之前或之后运行。

配置中的无服务器函数以 Lua 字符串表示。将本例使用的函数展开后,Lua 代码如下:

return function()
local core = require "apisix.core"

core.ctx.register_var("a6_route_labels", function(ctx)
local route = ctx.matched_route and ctx.matched_route.value
if route and route.labels then
return route.labels
end
return nil
end)
end

以下请求将函数绑定到服务。该函数在 rewrite 阶段运行,使 http-logger 在记录请求时能够读取路由标签:

curl "http://127.0.0.1:9180/apisix/admin/services/srv_custom_var" -X PATCH \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"plugins": {
"serverless-pre-function": {
"phase": "rewrite",
"functions": [
"return function() local core = require \"apisix.core\" core.ctx.register_var(\"a6_route_labels\", function(ctx) local route = ctx.matched_route and ctx.matched_route.value if route and route.labels then return route.labels end return nil end) end"
]
}
}
}'

配置日志格式​

完成任意一种注册方式后,将自定义变量加入 http-logger 的插件元数据:

curl "http://127.0.0.1:9180/apisix/admin/plugin_metadata/http-logger" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"log_format": {
"host": "$host",
"client_ip": "$remote_addr",
"labels": "$a6_route_labels"
}
}'

此日志格式包含用于记录主机和客户端地址的标准 NGINX 变量,以及自定义的路由标签变量。

创建路由​

为服务创建一条路由。自定义变量将返回在此处设置的标签:

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"id": "route_custom_var",
"uri": "/get",
"service_id": "srv_custom_var",
"labels": {
"key": "test_a6_route_labels"
}
}'

验证日志中的变量​

向路由发送请求:

curl "http://127.0.0.1:9080/get"

HTTP 日志端点应收到一个 POST 请求,其请求体类似如下:

[
{
"labels": {
"key": "test_a6_route_labels"
},
"service_id": "srv_custom_var",
"client_ip": "172.21.0.1",
"route_id": "route_custom_var",
"host": "127.0.0.1"
}
]

可以通过 labels 字段确认自定义变量返回了匹配路由的标签。

在插件运行前注册路由参数​

_meta.pre_function 钩子可以在插件运行前立即注册变量。以下配置使 proxy-rewrite 可以使用捕获的用户 ID,这个示例可以独立于前面的日志配置使用。

配置 radixtree_uri_with_parameter 路由器:

config.yaml
apisix:
router:
http: radixtree_uri_with_parameter

将路由器设置加入当前部署的生效配置,然后重载 APISIX。

如果使用 Docker 快速入门,请按照在启动时注册中的顺序复制、验证配置并重载 APISIX,这次只添加上面的路由器设置。

proxy-rewrite 使用的前置函数如下:

return function(conf, ctx)
local core = require "apisix.core"

core.ctx.register_var("user_id", function(ctx)
return ctx.curr_req_matched.user_id
end)
end

创建一条路由,从路径中捕获 user_id,将其注册为变量,并使用 proxy-rewrite 重写 URI:

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"id": "pre-func-route",
"uri": "/anything/:user_id/hello",
"plugins": {
"proxy-rewrite": {
"_meta": {
"pre_function": "return function(conf, ctx) local core = require \"apisix.core\" core.ctx.register_var(\"user_id\", function(ctx) return ctx.curr_req_matched.user_id end) end"
},
"uri": "/anything/$user_id/world"
}
},
"upstream": {
"type": "roundrobin",
"nodes": {
"httpbin.org:80": 1
}
}
}'

路由配置的工作过程如下:

  • 路由从 /anything/:user_id/hello 捕获用户 ID。
  • 前置函数将捕获的值注册为 user_id 变量。
  • proxy-rewrite 将该变量代入 /anything/$user_id/world。

以 johndoe 作为路径参数发送请求:

curl -i "http://127.0.0.1:9080/anything/johndoe/hello"

响应应包含重写后的 URL:

{
"url": "http://127.0.0.1/anything/johndoe/world"
}

该响应表明 proxy-rewrite 使用了自定义变量 user_id。