167 lines
7.8 KiB
Plaintext
167 lines
7.8 KiB
Plaintext
|
||
emqx_mgmt_api_publish {
|
||
publish_api {
|
||
desc {
|
||
en: """
|
||
Publish one message.<br/>
|
||
Possible HTTP status response codes are:<br/>
|
||
<code>200</code>: The message is delivered to at least one subscriber;<br/>
|
||
<code>202</code>: No matched subscribers;<br/>
|
||
<code>400</code>: Message is invalid. for example bad topic name, or QoS is out of range;<br/>
|
||
<code>503</code>: Failed to deliver the message to subscriber(s);<br/>
|
||
"""
|
||
zh: """
|
||
发布一个消息。<br/>
|
||
可能的 HTTP 状态码如下：<br/>
|
||
200: 消息被成功发送到至少一个订阅。<br/>
|
||
202: 没有匹配到任何订阅。<br/>
|
||
400: 消息编码错误，如非法主题，或 QoS 超出范围等。<br/>
|
||
503: 服务重启等过程中导致转发失败。<br/><br/>
|
||
"""
|
||
}
|
||
}
|
||
publish_bulk_api {
|
||
desc {
|
||
en: """
|
||
Publish a batch of messages.<br/>
|
||
Possible HTTP response status code are:<br/>
|
||
200: All messages are delivered to at least one subscriber;<br/>
|
||
202: At least one message was not delivered to any subscriber;<br/>
|
||
400: At least one message is invalid. For example bad topic name, or QoS is out of range;<br/>
|
||
503: Failed to deliver at least one of the messages;<br/>
|
||
|
||
In case there is at lest one invalid message in the batch, the HTTP response body
|
||
is the same as for <code>/publish</code> API.<br/>
|
||
Otherwise the HTTP response body is an array of JSON objects indicating the publish
|
||
result of each individual message in the batch.
|
||
"""
|
||
zh: """
|
||
批量发布一组消息。<br/>
|
||
可能的 HTTP 状态码如下：<br/>
|
||
200: 所有的消息都被成功发送到至少一个订阅。<br/>
|
||
202: 至少有一个消息没有匹配到任何订阅。<br/>
|
||
400: 至少有一个消息编码错误，如非法主题，或 QoS 超出范围等。<br/>
|
||
503: 至少有一个小因为服务重启的原因导致转发失败。<br/>
|
||
|
||
请求的 Body 或者 Body 中包含的某个消息无法通过 API 规范的类型检查时，HTTP 响应的消息与发布单个消息的 API
|
||
<code>/publish</code> 是一样的。
|
||
如果所有的消息都是合法的，那么 HTTP 返回的内容是一个 JSON 数组，每个元素代表了该消息转发的状态。
|
||
|
||
"""
|
||
}
|
||
}
|
||
|
||
topic_name {
|
||
desc {
|
||
en: "Topic Name"
|
||
zh: "主题名称"
|
||
}
|
||
}
|
||
qos {
|
||
desc {
|
||
en: "MQTT message QoS"
|
||
zh: "MQTT 消息的 QoS"
|
||
}
|
||
}
|
||
payload {
|
||
desc {
|
||
en: "The MQTT message payload."
|
||
zh: "MQTT 消息体。"
|
||
}
|
||
}
|
||
retain {
|
||
desc {
|
||
en: "A boolean field to indicate if this message should be retained."
|
||
zh: "布尔型字段，用于表示该消息是否保留消息。"
|
||
}
|
||
}
|
||
payload_encoding {
|
||
desc {
|
||
en: "MQTT Payload Encoding, <code>base64</code> or <code>plain</code>. When set to <code>base64</code>, the message is decoded before it is published."
|
||
zh: "MQTT 消息体的编码方式，可以是 <code>base64</code> 或 <code>plain</code>。当设置为 <code>base64</code> 时，消息在发布前会先被解码。"
|
||
}
|
||
}
|
||
message_id {
|
||
desc {
|
||
en: "A globally unique message ID for correlation/tracing."
|
||
zh: "全局唯一的一个消息 ID，方便用于关联和追踪。"
|
||
}
|
||
}
|
||
reason_code {
|
||
desc {
|
||
en: """
|
||
The MQTT reason code, as the same ones used in PUBACK packet.<br/>
|
||
Currently supported codes are:<br/>
|
||
|
||
16(0x10): No matching subscribers;<br/>
|
||
131(0x81): Error happened when dispatching the message. e.g. during EMQX restart;<br/>
|
||
144(0x90): Topic name invalid;<br/>
|
||
151(0x97): Publish rate limited, or message size exceeded limit. The global size limit can be configured with <code>mqtt.max_packet_size</code><br/>
|
||
NOTE: The message size is estimated with the received topic and payload size, meaning the actual size of serialized bytes (when sent to MQTT subscriber)
|
||
might be slightly over the limit.
|
||
"""
|
||
zh: """
|
||
MQTT 消息发布的错误码，这些错误码也是 MQTT 规范中 PUBACK 消息可能携带的错误码。<br/>
|
||
当前支持如下错误码：<br/>
|
||
|
||
16(0x10)：没能匹配到任何订阅；<br/>
|
||
131(0x81)：消息转发时发生错误，例如 EMQX 服务重启；<br/>
|
||
144(0x90)：主题名称非法；<br/>
|
||
151(0x97)：受到了速率限制，或者消息尺寸过大。全局消息大小限制可以通过配置项 <code>mqtt.max_packet_size</code> 来进行修改。<br/>
|
||
注意：消息尺寸的是通过主题和消息体的字节数进行估算的。具体发布时所占用的字节数可能会稍大于这个估算的值。
|
||
"""
|
||
}
|
||
}
|
||
error_message {
|
||
desc {
|
||
en: "Describes the failure reason in detail."
|
||
zh: "失败的详细原因。"
|
||
}
|
||
}
|
||
message_properties {
|
||
desc {
|
||
en: "The Properties of the PUBLISH message."
|
||
zh: "PUBLISH 消息里的 Property 字段。"
|
||
}
|
||
}
|
||
msg_payload_format_indicator {
|
||
desc {
|
||
en: """0 (0x00) Byte Indicates that the Payload is unspecified bytes, which is equivalent to not sending a Payload Format Indicator.
|
||
|
||
1 (0x01) Byte Indicates that the Payload is UTF-8 Encoded Character Data. The UTF-8 data in the Payload MUST be well-formed UTF-8 as defined by the Unicode specification and restated in RFC 3629.
|
||
"""
|
||
zh: "载荷格式指示标识符，0 表示载荷是未指定格式的数据，相当于没有发送载荷格式指示；1 表示载荷是 UTF-8 编码的字符数据，载荷中的 UTF-8 数据必须是按照 Unicode 的规范和 RFC 3629 的标准要求进行编码的。"
|
||
}
|
||
}
|
||
msg_message_expiry_interval {
|
||
desc {
|
||
en: "Identifier of the Message Expiry Interval. If the Message Expiry Interval has passed and the Server has not managed to start onward delivery to a matching subscriber, then it MUST delete the copy of the message for that subscriber."
|
||
zh: "消息过期间隔标识符，以秒为单位。当消失已经过期时，如果服务端还没有开始向匹配的订阅者投递该消息，则服务端会删除该订阅者的消息副本。如果不设置，则消息永远不会过期"
|
||
}
|
||
}
|
||
msg_response_topic {
|
||
desc {
|
||
en: "Identifier of the Response Topic.The Response Topic MUST be a UTF-8 Encoded, It MUST NOT contain wildcard characters."
|
||
zh: "响应主题标识符， UTF-8 编码的字符串，用作响应消息的主题名。响应主题不能包含通配符，也不能包含多个主题，否则将造成协议错误。当存在响应主题时，消息将被视作请求报文。服务端在收到应用消息时必须将响应主题原封不动的发送给所有的订阅者。"
|
||
}
|
||
}
|
||
msg_correlation_data {
|
||
desc {
|
||
en: "Identifier of the Correlation Data. The Server MUST send the Correlation Data unaltered to all subscribers receiving the Application Message."
|
||
zh: "对比数据标识符，服务端在收到应用消息时必须原封不动的把对比数据发送给所有的订阅者。对比数据只对请求消息(Request Message)的发送端和响应消息(Response Message)的接收端有意义。"
|
||
}
|
||
}
|
||
msg_user_properties {
|
||
desc {
|
||
en: "The User-Property key-value pairs. Note: in case there are duplicated keys, only the last one will be used."
|
||
zh: "指定 MQTT 消息的 User Property 键值对。注意，如果出现重复的键，只有最后一个会保留。"
|
||
}
|
||
}
|
||
msg_content_type {
|
||
desc {
|
||
en: "The Content Type MUST be a UTF-8 Encoded String."
|
||
zh: "内容类型标识符，以 UTF-8 格式编码的字符串，用来描述应用消息的内容，服务端必须把收到的应用消息中的内容类型原封不动的发送给所有的订阅者。"
|
||
}
|
||
}
|
||
}
|