WebHook

WebHook 是由 emqx_web_hook 插件提供的 将 EMQ X 中的钩子事件通知到某个 Web 服务 的功能。

WebHook 的内部实现是基于 钩子,但它更靠近顶层一些。它通过在钩子上的挂载回调函数,获取到 EMQ X 中的各种事件,并转发至 emqx_web_hook 中配置的 Web 服务器。

以 客户端成功接入(client.connected) 事件为例,其事件的传递流程如下:

  1. Client | EMQ X | emqx_web_hook | HTTP +------------+
  2. =============>| - - - - - - -> - - - - - - - ->===========> | Web Server |
  3. | Broker | | Request +------------+

WebHook 对于事件的处理是单向的,它仅支持将 EMQ X 中的事件推送给 Web 服务,并不关心 Web 服务的返回。 借助 Webhook 可以完成设备在线、上下线记录,订阅与消息存储、消息送达确认等诸多业务。

配置项

Webhook 的配置文件位于 etc/plugins/emqx_web_hook.conf

配置项类型可取值默认值说明
api.urlstring-http://127.0.0.1:8080事件需要转发的目的服务器地址
encode_payloadenumbase64, base62undefined消息类事件中的 Payload 字段进行编码,注释或其他则表示不编码

当消息内容是不可见字符(如二进制数据)时,为了能够在 HTTP 协议中传输,使用 encode_payload 是十分有用的。

触发规则

etc/plugins/emqx_web_hooks.conf 可配置触发规则,其配置的格式如下:

  1. ## 格式示例
  2. web.hook.rule.<Event>.<Number> = <Rule>
  3. ## 示例值
  4. web.hook.rule.message.publish.1 = {"action": "on_message_publish", "topic": "a/b/c"}
  5. web.hook.rule.message.publish.2 = {"action": "on_message_publish", "topic": "foo/#"}

Event 触发事件

目前支持以下事件:

名称说明执行时机
client.connect处理连接报文服务端收到客户端的连接报文时
client.connack下发连接应答服务端准备下发连接应答报文时
client.connected成功接入客户端认证完成并成功接入系统后
client.disconnected连接断开客户端连接层在准备关闭时
client.subscribe订阅主题收到订阅报文后,执行 client.check_acl 鉴权前
client.unsubscribe取消订阅收到取消订阅报文后
session.subscribed会话订阅主题完成订阅操作后
session.unsubscribed会话取消订阅完成取消订阅操作后
message.publish消息发布服务端在发布(路由)消息前
message.delivered消息投递消息准备投递到客户端前
message.acked消息回执服务端在收到客户端发回的消息 ACK 后
message.dropped消息丢弃发布出的消息被丢弃后

Number

同一个事件可以配置多个触发规则,配置相同的事件应当依次递增。

Rule

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

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

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

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

这样 Webhook 仅会转发与 a/b/cfoo/# 主题匹配的消息,例如 foo/bar 等,而不是转发 a/b/dfo/bar

Webhook 事件参数

事件触发时 Webhook 会按照配置将每个事件组成一个 HTTP 请求发送到 api.url 所配置的 Web 服务器上。其请求格式为:

  1. URL: <api.url> # 来自于配置中的 `api.url` 字段
  2. Method: POST # 固定为 POST 方法
  3. Body: <JSON> # Body 为 JSON 格式字符串

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

client.connect

Key类型说明
actionstring事件名称
固定为:”client_connect”
clientidstring客户端 ClientId
usernamestring客户端 Username,不存在时该值为 “undefined”
ipaddressstring客户端源 IP 地址
keepaliveinteger客户端申请的心跳保活时间
proto_verinteger协议版本号

client.connack

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

client.connected

Key类型说明
actionstring事件名称
固定为:”client_connected”
clientidstring客户端 ClientId
usernamestring客户端 Username,不存在时该值为 “undefined”
ipaddressstring客户端源 IP 地址
keepaliveinteger客户端申请的心跳保活时间
proto_verinteger协议版本号
connected_atinteger时间戳(秒)

client.disconnected

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

client.subscribe

Key类型说明
actionstring事件名称
固定为:”client_subscribe”
clientidstring客户端 ClientId
usernamestring客户端 Username,不存在时该值为 “undefined”
topicstring将订阅的主题
optsjson订阅参数

opts 包含

Key类型说明
qosenumQoS 等级,可取 0 1 2

client.unsubscribe

Key类型说明
actionstring事件名称
固定为:”client_unsubscribe”
clientidstring客户端 ClientId
usernamestring客户端 Username,不存在时该值为 “undefined”
topicstring取消订阅的主题

session.subscribed:同 client.subscribe,action 为 session_subscribed

session.unsubscribed:同 client.unsubscribe,action 为 session_unsubscribe

session.terminated: 同 client.disconnected,action 为 session_terminated

message.publish

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

message.delivered

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

message.acked

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