128 lines
5.0 KiB
Plaintext
128 lines
5.0 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"
|
||
}
|
||
}
|
||
clientid {
|
||
desc {
|
||
en: "Each message can be published as if it is done on behalf of an MQTT client whos ID can be specified in this field."
|
||
zh: "每个消息都可以带上一个 MQTT 客户端 ID，用于模拟 MQTT 客户端的发布行为。"
|
||
}
|
||
}
|
||
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: "失败的详细原因。"
|
||
}
|
||
}
|
||
}
|