EMQX Platform 文档

简体中文

English

简体中文

English

Appearance

联系我们

客户端接入接口说明 ​

创建连接 ​

仅在 连接模式 下可用。

该接口用于向 CoAP 网关创建客户端连接。当开启 CoAP 网关的认证功能后，网关会对该请求中的 clientid, username, password 进行验证，以防止非法用户登录系统。

请求参数表：

  • 方法（Method）: POST
  • 请求路径（URI）：mqtt/connection{?QueryString*}，其中 QueryString 可用参数为：
    • clientid：必填参数；UTF8 字符串，网关以该字符串作为该连接的唯一标识。
    • username：可选参数，UTF8 字符串，用于连接认证。
    • password：可选参数，UTF8 字符串，用于连接认证。
  • 消息体（Payload）：为空。

返回结果：

  • 返回码（Return Code）：
    • 2.01：连接创建成功，并在消息体中返回本次连接的 Token 字符串。
    • 4.00：错误的请求格式，并在消息体中返回具体的错误信息。
    • 4.01：请求格式正确，但登录鉴权失败。并在消息体中返回具体的错误信息。
  • 消息体（Payload）：当返回码为 2.01时，消息体为 Token，否则为 ErrorMessage。
    • Token：用于后续请求使用的令牌字符串。
    • ErrorMessage: 错误说明，例如 Login Failed: not_authorized。

以 libcoap 为例：

bash
# 使用 clientid 为 123，用户名密码为 admin/public 发起创建连接请求
# 返回 Token 为 3404490787
coap-client -m post -e "" "coap://${your-deployment-connection-address}/mqtt/connection?clientid=123&username=admin&password=public"

3404490787

TIP

连接创建成功后，您可以在对应部署详情网关页面中检查 CoAP 网关的客户端列表中是否已存在该客户端。

断开连接 ​

仅在 连接模式 下可用。

该接口用于关闭 CoAP 客户端连接。

请求参数表：

  • 方法（Method）: DELETE
  • 请求路径（URI）：mqtt/connection{?QueryString*}，其中 QueryString 可用参数为：
    • clientid：必填参数；UTF8 字符串，网关以该字符串作为该连接的唯一标识。
    • token：必填参数；使用由创建连接方法返回的 Token 字符串。
  • 消息体（Payload）：为空。

返回结果：

  • 返回码（Return Code）：
    • 2.01：关闭连接成功。
    • 4.00：错误的请求格式，并在消息体中返回具体的错误信息。
    • 4.01：请求格式正确，但登录鉴权失败。并在消息体中返回具体的错误信息。
  • 消息体（Payload）：当返回码为 2.01 时，消息体为空；否则为具体的错误消息。

例如：

bash
coap-client -m delete -e "" "coap://${your-deployment-connection-address}/mqtt/connection?clientid=123&token=3404490787"

心跳 ​

仅在 连接模式 下可用。

该接口用于维持 CoAP 客户端与网关的连接。当心跳超期后，网关会删除该客户端的会话、订阅关系，并释放所有的资源。

请求参数表：

  • 方法（Method）: PUT
  • 请求路径（URI）：mqtt/connection{?QueryString*}，其中 QueryString 可用参数为：
    • clientid：必填参数；UTF8 字符串，网关以该字符串作为该连接的唯一标识。
    • token：必填参数；使用由创建连接方法返回的 Token 字符串。
  • 消息体（Payload）：为空。

返回结果：

  • 返回码（Return Code）：
    • 2.01：更新成功。
    • 4.00：错误的请求格式，并在消息体中返回具体的错误信息。
    • 4.01：请求格式正确，但登录鉴权失败。并在消息体中返回具体的错误信息。
  • 消息体（Payload）：当返回码为 2.01 时，消息体为空；否则为具体的错误消息。

例如：

bash
coap-client -m put -e "" "coap://${your-deployment-connection-address}/mqtt/connection?clientid=123&token=3404490787"

TIP

心跳间隔时间由 CoAP 网关设置中的 heartbeat 配置决定，默认为 30 秒。

消息发布 ​

该接口用于 CoAP 客户端为指定主题发送消息。在 连接模式 下需要额外携带身份信息。

请求参数表：

  • 方法（Method）：POST
  • 请求路径（URI）：ps/{+topic}{?QueryString*}，其中：
    • {+topic} 为需要发布的主题，例如向 coap/test 主题发布消息，那么请求路径为 ps/coap/test
    • {?QueryString*} 为请求参数
      • clientid： 连接模式 下为必填参数，无连接模式 下为可选参数。
      • token： 仅用于 连接模式，必填参数；
      • retain：是否作为保留消息进行发布；布尔类型，可选参数，默认为 false。
      • qos：消息 QoS，用于标识该消息的 QoS 等级，仅影响 MQTT 客户端如何接收该消息；枚举类型，可选值为 0、 1、 2
      • expiry：消息超期时间，单位秒；默认为 0 表示永不超期
  • 消息体（Payload）：消息内容

返回结果：

  • 返回码（Return Code）：
    • 2.04：发送成功。
    • 4.00：错误的请求格式，并在消息体中返回具体的错误信息。
    • 4.01：请求格式正确，但鉴权失败。并在消息体中返回具体的错误信息。
  • 消息体（Payload）：当返回码为 2.04 时，消息体为空；否则为具体的错误消息

例如，无连接模式 下为 coap/test 发送一条消息：

bash
coap-client -m post -e "Hi, this is libcoap" "coap://${your-deployment-connection-address}/ps/coap/test"
连接模式下则需要携带 `clientid` 和 `token`
bash
coap-client -m post -e "Hi, this is libcoap" "coap://${your-deployment-connection-address}/ps/coap/test?clientid=123&token=3404490787"

订阅主题 ​

该接口用于 CoAP 客户端订阅指定主题。在 连接模式 下需要额外携带身份信息。

请求参数表：

  • 方法（Method）：GET
  • 选项值（Options）：需设置 observer 为 0
  • 请求路径（URI）：ps/{+topic}{?QueryString*}，其中：
    • {+topic} 为需要订阅主题，例如订阅 coap/test 主题，则请求路径为 ps/coap/test。
    • {?QueryString*}为请求参数。
      • clientid： 连接模式下为必填参数，无连接模式下为可选参数。
      • token： 仅用于 连接模式，必填参数；
      • qos：订阅 QoS，用于指示网关以那种消息类型（CON 或 NON）来投递后续接收的该消息；枚举类型，可选值为：
        • 0，1，2：设置为qos0，qos1 或 qos2。如果设置为 qos0 表示该主题上的消息会以 NON 消息进行投递；qos1，qos2 表示该主题上的消息会以 CON 消息进行投递。
  • 消息体（Payload）：空

返回结果：

  • 返回码（Return Code）：
    • 2.05：订阅成功。
    • 4.00：错误的请求格式，并在消息体中返回具体的错误信息。
    • 4.01：请求格式正确，但鉴权失败。并在消息体中返回具体的错误信息。
  • 消息体（Payload）：当返回码为 2.05 时，消息体为空；否则为具体的错误消息。

例如，无连接模式 下订阅主题 coap/test ：

bash
coap-client -m get -s 60 -O 6,0x00 -o - -T "obstoken" "coap://${your-deployment-connection-address}/ps/coap/test"

连接模式 下则需要携带 clientid 和 token：

bash
coap-client -m get -s 60 -O 6,0x00 -o - -T "obstoken" "coap://${your-deployment-connection-address}/ps/coap/test?clientid=123&token=3404490787"

取消订阅 ​

该接口用于 CoAP 客户端取消订阅指定主题。 目前，取消订阅操作仅在 连接模式 下可用。

请求参数表：

  • 方法（Method）：GET
  • 请求路径（URI）：ps/{+topic}{?QueryString*}，其中：
    • {+topic} 为需要取消订阅主题，例如取消订阅 coap/test 主题，则请求路径为 ps/coap/test
    • {?QueryString*}为请求参数。
      • clientid： 连接模式下为必填参数，无连接模式下为可选参数。
      • token： 仅用于 连接模式，必填参数。
  • 消息体（Payload）：空

返回结果：

  • 返回码（Return Code）：
    • 2.07：取消订阅成功。
    • 4.00：错误的请求格式，并在消息体中返回具体的错误信息。
    • 4.01：请求格式正确，但鉴权失败。并在消息体中返回具体的错误信息。
  • 消息体（Payload）：当返回码为 2.07 时，消息体为空；否则为具体的错误消息。

例如，连接模式 下取消订阅主题 coap/test ：

bash
coap-client -m get -O 6,0x01 "coap://${your-deployment-connection-address}/ps/coap/test?clientid=123&token=3404490787"

短参数名称 ​

为节省报文大小，CoAP 网关支持短参数名称。例如，参数 clientid=barx 可以写作 c=bar。所有支持的短 参数名称见下表：

参数名称短参数名称
clientidc
usernameu
passwordp
tokent
qosq
retainr