====== 快速连接MQTT消息云 ======

本文介绍如何使用MQTT客户端快速连接环信MQTT消息云
=====   1. 操作流程 =====
==== 1.1 开通MQTT业务 ====
开通环信MQTT消息云服务见[[https://docs-im.easemob.com/mqtt/qsopen|快速开通MQTT服务]] 章节

==== 1.2 下载MQTT客户端 ====
常见的MQTT客户端整理如下，下载客户端后可快速连接环信MQTT消息云：
|MQTT客户端|操作系统|下载地址|
|MQTT Explorer|Windows，macOS，Linux|[[https://mqtt-explorer.com|点击下载]]|
|MQTT.fx|Windows，macOS，Linux|[[https://mqttfx.jensd.de/index.php/download|点击下载]]|
|MQTT Box|Windows，macOS，Linux|[[https://workswithweb.com/mqttbox.html|点击下载]]|
|mqtt-spy|Windows，macOS，Linux|[[https://github.com/eclipse/paho.mqtt-spy/releases|点击下载]]|
|Mosquitto CLI|Windows，macOS，Linux|[[https://mosquitto.org/download/|点击下载]]|

=====   2. 接入指引 =====
==== 2.1 连接五要素 ====
MQTT客户端在连接环节需要5个基本参数，包括**连接地址（Host）、端口（Port）、clientID（MQTT client ID）、用户ID(Username)、token(Password)**。 \\
获取方式如下：\\
step1.进入console控制台，选择【MQTT】->【服务概览】；\\
step2.获取clientID，clientID由两部分组成，组织形式为“deviceID@AppID”，deviceID由用户自定义，AppID见【服务配置】下AppID； \\
step3.获取连接地址（Host）； \\
step4.获取端口（Port）； \\
step5.选择左侧菜单栏【应用概览】->【用户认证】； \\
step6.获取用户ID（Username）； \\
step7.获取token（Password）； \\
{{:playground:message:client6_n.jpg|}}
{{:playground:message:client7_n.jpg|}}
\\
==== 2.2 连接环信MQTT消息云 ====
本文以MQTT Explorer for MAC版本为例（可通过APP Store下载），注：Windows版客户端连接流程见链接[[https://www.imgeek.org/article/825357876|Windows连接流程]]。 \\
打开MQTT客户端软件，选择“+”新建图标。
{{:playground:message:client1_n.jpg|}} 
\\
step1.用户自定义连接名称; \\
step2.是否选择开启tls加密，取值：“开启”、“关闭”；\\
step3.选择连接协议，取值：“ws:(websocket)”、“mqtt:”，若step2选择开启tls，协议为“wss:”、“mqtts”; \\
step4.填写环信MQTT消息云连接地址（Host）； \\
step5.填写端口（Port）； \\
step6.填写用户ID（username）；  \\
step7.填写token（Password）；   \\
step8.选择【ADVANCE】，填写clientID，clientID由两部分组成，“deviceID@AppID”；  \\
step9.填写订阅主题名称，此例为“t/t1” ；\\
step10.填写后点击【ADD】按钮添加至订阅列表中； \\
step11. 填写clientID名称； \\
step12. 选择【BACK】按钮，返回至主页面；\\
step13. 选择主页面中【CONNECT】即可连接成功；\\
{{:playground:message:client2_n.jpg|}}. \\
{{:playground:message:client3_n.jpg|}}.  
==== 2.3 订阅/发布消息 ====
在创建一个MQTT 客户端，执行【连接环信MQTT消息云】流程；
=== 2.3.1 发布消息 ===
step1.填写发布的主题，本例中为“/t/t1”; \\
step2.选择消息体格式，取值：“raw”、“xml”、“json”；\\
step3.填写消息体内容，本例中为“hello world”; \\
step4.选择QoS等级，取值：“0:至多发送一次，不保留”、“1：至少一次，保留”、“2：仅发一次，保留”； \\
step5.选择是否为保留消息，取值：“0:不保留”、“1:保留，订阅客户端重新接入环信MQTT消息云时，可以接收保留消息”； \\
step6.发送消息；  \\
{{:playground:message:client4_n.jpg|}}
=== 2.3.2 订阅消息 ===
订阅/t/t1的MQTT客户端即可接收消息\\
{{:playground:message:client5_n.jpg|}}