Skip to content

WebHook

NanoMQ 提供了可拓展的事件驱动型 WebHook 接口,用户可通过规则配置 WebHook 的触发事件或消息主题。Webhook 的配置文件位于 etc/nanomq.conf。NanoMQ 提供了两个版本的配置文件,您可根据需要及部署版本选择:

通过 HOCON 格式配置

启用 Webhook

添加 webhook 对应的选项到 etc/nanomq.conf 即可, 如下:

bash
webhook {
    ......
}

注意 对于 0.14 ~ 0.18 版本,还需通过 webhook.enable = true 选项启用相关功能。具体可参考 配置 - v0.14

规则语法

Webhook 支持两个配置参数:

  • event :字符串,取固定值
  • topic :字符串,主题过滤器,只有当消息主题与规则中指定的主题匹配时,才会触发消息的转发动作。

语法

bash
## 格式示例
webhook {
	## 此处可以添加多条规则
	event = [
    	{
        	<Rule>
    	}
	]
}

示例

我们希望将 a/b/cfoo/# 主题下的消息转发到 Web 服务器上,其配置应该为:

bash
webhook {
	url = "http://127.0.0.1:80"
	headers.content-type = "application/json"
	body.encoding = plain
	pool_size = 32
	
	event = [
		{ 
			event = "on_message_publish"
			topic = "a/b/c"
		}
		{
			event = "on_message_publish"
			topic = "foo/#"
		}
	]
}

触发事件

NanoMQ目前支持三类触发事件:

名称说明执行时机
on_client_connack下发连接应答服务端准备下发连接应答报文时
on_client_disconnected连接断开客户端连接在准备关闭时
on_message_publish消息发布服务端在发布(路由)消息前

事件参数

当某个事件被触发时,WebHook 会将该事件封装成一个 HTTP 请求,并将该请求发送到一个由预设 URL 确定的网络服务器上,其请求格式为:

bash
URL: <url>      # 来自于配置中的 `url` 字段
Method: POST    # 固定为 POST 方法

Body: <JSON>    # Body 为 JSON 格式字符串

对于不同的事件,请求 Body 体内容有所不同,下表列举了各个事件中 Body 的参数列表:

on_client_connack

Key类型说明
actionstring事件名称 固定为:"client_connack"
clientidstring客户端 ClientId
usernamestring客户端 Username,不存在时该值为 "undefined"
keepaliveinteger客户端申请的心跳保活时间
proto_verinteger协议版本号 ( 3 | 4 | 5 )
conn_ackstring"success" 表示成功,其它表示失败的原因

on_client_disconnected

Key类型说明
actionstring事件名称 固定为:"client_disconnected"
clientidstring客户端 ClientId
usernamestring客户端 Username,不存在时该值为 "undefined"
reasonstring错误原因

on_message_publish

Key类型说明
actionstring事件名称 固定为:"message_publish"
from_client_idstring发布端 ClientId
from_usernamestring发布端 Username ,不存在时该值为 "undefined"
topicstring订阅的主题
qosenumQoS 等级,可取 0、1、2
retainbool是否为保留消息
payloadstring消息 Payload
tsinteger消息的时间戳 (毫秒)

配置多条触发规则

配置示例:

bash
webhook {
	url = "http://127.0.0.1:80"
	headers.content-type = "application/json"
	body.encoding = plain
	pool_size = 32
	
	event = [
		{ 
			event = "on_message_publish"
			topic = "a/b/c"
		}
		{
			event = "on_client_connack"
		}
	]
}

其中,

event:WebHook 触发事件,类型为 string,支持的事件包括:

  • on_client_connack:客户端建立连接
  • on_client_disconnected:客户端断开连接
  • on_message_publish:消息发布

topic:消息的发布主题,类型为 string

通过 KV 格式配置

启用 WebHook

bash
web.hook.enable = true

规则语法

WebHook 规则的值为一个 JSON 字符串,其中可用的 Key 有:

  • action :字符串,取固定值
  • topic :字符串,表示一个主题过滤器,操作的主题只有与该主题匹配才能触发事件的转发

语法

bash
web.hook.rule.<Event>.<Number>=<Rule>

注意:我们可以为同一个事件可以配置多个触发规则,并通过数字进行区分。

示例

例如,我们只将与 a/b/c 和 foo/# 主题匹配的消息转发到 Web 服务器上,其配置应该为:

bash
web.hook.rule.message.publish.1={"action": "on_message_publish", "topic": "a/b/c"}
web.hook.rule.message.publish.2={"action": "on_message_publish", "topic": "foo/#"}

这样 WebHook 仅会转发与 a/b/cfoo/# 主题匹配的消息,例如 foo/bar 等。

触发事件

目前支持以下事件:

名称说明执行时机
client.connack下发连接应答服务端准备下发连接应答报文时
client.disconnected连接断开客户端连接在准备关闭时
message.publish消息发布服务端在发布(路由)消息前

事件参数

当某个事件被触发时,WebHook 会将该事件封装成一个 HTTP 请求,并将该请求发送到一个由预设 URL 确定的网络服务器上,其请求格式为:

bash
URL: <url>      # 来自于配置中的 `url` 字段
Method: POST    # 固定为 POST 方法

Body: <JSON>    # Body 为 JSON 格式字符串

对于不同的事件,请求 Body 体内容有所不同,下表列举了各个事件中 Body 的参数列表:

client.connack

Key类型说明
actionstring事件名称 固定为:"client_connack"
clientidstring客户端 ClientId
usernamestring客户端 Username,不存在时该值为 "undefined"
keepaliveinteger客户端申请的心跳保活时间
proto_verinteger协议版本号 ( 3 | 4 | 5 )
conn_ackstring"success" 表示成功,其它表示失败的原因

client.disconnected

Key类型说明
actionstring事件名称 固定为:"client_disconnected"
clientidstring客户端 ClientId
usernamestring客户端 Username,不存在时该值为 "undefined"
reasonstring错误原因

message.publish

Key类型说明
actionstring事件名称 固定为:"message_publish"
from_client_idstring发布端 ClientId
from_usernamestring发布端 Username,不存在时该值为 "undefined"
topicstring订阅的主题
qosenumQoS 等级,可取 0 1 2
retainbool是否为 Retain 消息
payloadstring消息 Payload
tsinteger消息的时间戳(毫秒)