From ac1bdee3ee77dd0349b02bf4f32de8bc818202f4 Mon Sep 17 00:00:00 2001 From: DDDHuang <44492639+DDDHuang@users.noreply.github.com> Date: Mon, 18 Apr 2022 17:11:31 +0800 Subject: [PATCH] fix: config docs for banned api & auto sub --- .../i18n/emqx_auto_subscribe_i18n.conf | 85 +++++++++++++++++++ .../src/emqx_auto_subscribe_schema.erl | 21 ++--- .../i18n/emqx_management_i18n.conf | 54 ++++++++++++ 3 files changed, 148 insertions(+), 12 deletions(-) create mode 100644 apps/emqx_auto_subscribe/i18n/emqx_auto_subscribe_i18n.conf create mode 100644 apps/emqx_management/i18n/emqx_management_i18n.conf diff --git a/apps/emqx_auto_subscribe/i18n/emqx_auto_subscribe_i18n.conf b/apps/emqx_auto_subscribe/i18n/emqx_auto_subscribe_i18n.conf new file mode 100644 index 000000000..f8b66c751 --- /dev/null +++ b/apps/emqx_auto_subscribe/i18n/emqx_auto_subscribe_i18n.conf @@ -0,0 +1,85 @@ +emqx_auto_subscribe_schema { + auto_subscribe { + desc { + en: """After the device logs in successfully, the subscription is automatically completed for the device through the pre-defined subscription representation. Supports the use of placeholders.""" + zh: """设备登陆成功之后，通过预设的订阅表示符，为设备自动完成订阅。支持使用占位符。""" + } + lable { + en: """Auto Subscribe""" + zh: """自动订阅""" + } + } + + topic { + desc { + en: """Topic name, placeholders are supported. For example: client/${clientid}/username/${username}/host/${host}/port/${port} +Required field, and cannot be empty string""" + zh: """订阅标识符，支持使用占位符，例如 client/${clientid}/username/${username}/host/${host}/port/${port} +必填，且不可为空字符串""" + } + label { + en: """Topic""" + zh: """订阅标识符""" + } + } + + qos { + desc { + en: """Default value 0. Quality of service. +At most once (0) +At least once (1) +Exactly once (2)""" + zh: """缺省值为 0，服务质量， +QoS 0：消息最多传递一次，如果当时客户端不可用，则会丢失该消息。 +QoS 1：消息传递至少 1 次。 +QoS 2：消息仅传送一次。""" + } + label { + en: """Quality of Service""" + zh: """Quality of Service""" + } + } + + rh { + desc { + en: """Default value 0. This option is used to specify whether the server forwards the retained message to the client when establishing a subscription. +Retain Handling is equal to 0, as long as the client successfully subscribes, the server will send the retained message. +Retain Handling is equal to 1, if the client successfully subscribes and this subscription does not exist previously, the server sends the retained message. After all, sometimes the client re-initiate the subscription just to change the QoS, but it does not mean that it wants to receive the reserved messages again. +Retain Handling is equal to 2, even if the client successfully subscribes, the server does not send the retained message.""" + zh: """指定订阅建立时服务端是否向客户端发送保留消息， +可选值 0：只要客户端订阅成功，服务端就发送保留消息。 +可选值 1：客户端订阅成功且该订阅此前不存在，服务端才发送保留消息。毕竟有些时候客户端重新发起订阅可能只是为了改变一下 QoS，并不意味着它想再次接收保留消息。 +可选值 2：即便客户订阅成功，服务端也不会发送保留消息。""" + } + label { + en: """Retain Handling""" + zh: """Retain Handling""" + } + } + + rap { + desc { + en: """Default value 0. This option is used to specify whether the server retains the RETAIN mark when forwarding messages to the client, and this option does not affect the RETAIN mark in the retained message. Therefore, when the option Retain As Publish is set to 0, the client will directly distinguish whether this is a normal forwarded message or a retained message according to the RETAIN mark in the message, instead of judging whether this message is the first received after subscribing(the forwarded message may be sent before the retained message, which depends on the specific implementation of different brokers)." + zh: "缺省值为 0，这一选项用来指定服务端向客户端转发消息时是否要保留其中的 RETAIN 标识，注意这一选项不会影响保留消息中的 RETAIN 标识。因此当 Retain As Publish 选项被设置为 0 时，客户端直接依靠消息中的 RETAIN 标识来区分这是一个正常的转发消息还是一个保留消息，而不是去判断消息是否是自己订阅后收到的第一个消息（转发消息甚至可能会先于保留消息被发送，视不同 Broker 的具体实现而定）。" + } + label { + en: """Retain As Publish""" + zh: """Retain As Publish""" + } + } + + nl { + desc { + en: """Default value 0. +MQTT v3.1.1： if you subscribe to the topic published by yourself, you will receive all messages that you published. +MQTT v5: if you set this option as 1 when subscribing, the server will not forward the message you published to you.""" + zh: """缺省值为0， +MQTT v3.1.1：如果设备订阅了自己发布消息的主题，那么将收到自己发布的所有消息。 +MQTT v5：如果设备在订阅时将此选项设置为 1，那么服务端将不会向设备转发自己发布的消息""" + } + label { + en: """No Local """ + zh: """No Local """ + } + } +} diff --git a/apps/emqx_auto_subscribe/src/emqx_auto_subscribe_schema.erl b/apps/emqx_auto_subscribe/src/emqx_auto_subscribe_schema.erl index 245339ee1..0084e5f80 100644 --- a/apps/emqx_auto_subscribe/src/emqx_auto_subscribe_schema.erl +++ b/apps/emqx_auto_subscribe/src/emqx_auto_subscribe_schema.erl @@ -17,6 +17,7 @@ -behaviour(hocon_schema). +-include_lib("hocon/include/hoconsc.hrl"). -include_lib("typerefl/include/types.hrl"). -include_lib("emqx/include/emqx_placeholder.hrl"). @@ -38,28 +39,24 @@ fields("auto_subscribe") -> fields("topic") -> [ {topic, sc(binary(), #{ example => topic_example(), - desc => "Topic name, placeholders is supported. For example: " - ++ binary_to_list(topic_example())})} + desc => ?DESC("topic")})} , {qos, sc(emqx_schema:qos(), #{ default => 0, - desc => "Quality of service. MQTT definition."})} + desc => ?DESC("qos")})} , {rh, sc(range(0,2), #{ default => 0, - desc => "Retain handling. MQTT 5.0 definition."})} + desc => ?DESC("rh")})} , {rap, sc(range(0, 1), #{ default => 0, - desc => "Retain as Published. MQTT 5.0 definition."})} + desc => ?DESC("rap")})} , {nl, sc(range(0, 1), #{ default => 0, - desc => "Not local. MQTT 5.0 definition."})} + desc => ?DESC(nl)})} ]. -desc("auto_subscribe") -> - "Configuration for `auto_subscribe` feature."; -desc("topic") -> - ""; -desc(_) -> - undefined. +desc("auto_subscribe") -> ?DESC("auto_subscribe"); +desc("topic") -> ?DESC("topic"); +desc(_) -> undefined. topic_example() -> <<"/clientid/", ?PH_S_CLIENTID, diff --git a/apps/emqx_management/i18n/emqx_management_i18n.conf b/apps/emqx_management/i18n/emqx_management_i18n.conf new file mode 100644 index 000000000..b0e41684a --- /dev/null +++ b/apps/emqx_management/i18n/emqx_management_i18n.conf @@ -0,0 +1,54 @@ +emqx_management { + banned { + as { + desc { + en: """Banned type clientid, username, peerhost""" + zh: """黑名单类型，可选 clientid、username、peerhost""" + } + label { + en: """Banned Type""" + zh: """黑名单类型""" + } + } + who { + desc { + en: """Client info as banned type""" + zh: """设备信息""" + } + label { + en: """Banned Info""" + zh: """黑名单信息""" + } + } + by { + desc { + en: """Commander""" + zh: """黑名单创建者""" + } + label { + en: """Commander""" + zh: """黑名单创建者""" + } + } + at { + desc { + en: """Create banned time, rfc3339, now if not specified""" + zh: """黑名单创建时间，默认为当前""" + } + label { + en: """Create banned time""" + zh: """黑名单创建时间""" + } + } + until { + desc { + en: """Cancel banned time, rfc3339, now + 5 minute if not specified""" + zh: """黑名单结束时间，默认为创建时间 + 5 分钟""" + } + label { + en: """Cancel banned time""" + zh: """黑名单结束时间""" + } + } + } +}