Token用戶端介面 - ApsaraMQ for MQTT

本文介紹雲Message QueueTT 版用戶端在Token模式下如何上傳Token、更新Token、監聽Token失效資訊和監聽Token非法資訊。

Token模式MQTT用戶端串連參數設定

MQTT支援三種模式的Token，每個用戶端每個類型至多申請一個Token，根據實際需要可能申請其中的一種或者多種，並使用。具體的類型如下表所示。

Token模式下MQTT用戶端的串連參數設定如下：

Username
由鑒權模式名稱、AccessKey ID、InstanceId三部分組成，以 “|” 分隔。Token模式下鑒權模式設定為”Token”。
舉例
一個用戶端的ClientId是GID_Test@@@0001，使用了執行個體ID是mqtt-xxxxx，使用了AccessKey ID是YYYYY，則Token模式的Username應該設定成“Token|YYYYY|mqtt-xxxxx”。
Password
用戶端需要使用的Token內容。具體設定方法是將所有的Token按照Token類型和Token內容依次使用“|”串連符拼接成一個完整的字串，不同類型之間的Token拼接順序無要求。
舉例1：用戶端只有一個讀類型的Token，Token字串為“123”，則Password為“R|123”。
舉例2：用戶端擁有2個類型的Token，讀類型的Token是“123”，寫類型的Token是“abcd”，則Password為“R|123|W|abcd”。
說明用戶端設定Token參數時需要保證嚴格按照約定規則，且需要保證所有Token有效，如果僅用部分Token合法，服務端仍然會判定非法。

正常情況下用戶端更換Token時需要中斷連線重新使用新的Token來串連，如果業務情境中不希望由於更換Token中斷用戶端的串連，可以使用動態更新Token的介面來動態替換服務端session內的Token資料。

動態更新Token本質上是由MQTT用戶端以約定的系統Topic發送一個特殊的訊息，將新的Token內容更新到服務端，用戶端需要保證在動態替換的同時，本地配置也要替換，防止下次串連初始化又使用了舊的Token資料。

內容資訊：

名稱	類型	說明
token	String	如果用戶端選用Token模式，則需要上傳Token字串。
type	String	Token類型，分為W、R、RW共三種，對應三種權限類別型的Token。一個用戶端最多擁有這3個Token，設定錯誤的類型會導致許可權校正錯誤。

傳回值：
普通的PubAck報文。用戶端必須等到該響應才能進行下一步Pub或者Sub操作，否則服務端仍然有可能使用舊的Token資料來做鑒權，可能會鑒權失敗導致串連斷開。

服務端為方便業務調試和監控，會在Token即將失效的時候以系統Topic的形式推播通知訊息到MQTT用戶端，用戶端可以監控該訊息來判斷是否有出現過Token即將到期的情況。

內容資訊：

名稱	類型	說明
expireTime	Long	該Token即將於什麼時候失效，格式為毫秒時間戳記，一般提前5分鐘通知，只通知一次，但服務端不保證一定會有通知。
type	String	Token類型，分為W、R、RW共三種，對應用戶端上傳的三種權限類別型的Token。

服務端為方便業務調試和監控，會在Token鑒權錯誤時以系統Topic的形式推播通知訊息到MQTT用戶端，用戶端可以監控該訊息來判斷是否有出現過Token不匹配等錯誤許可權的情況。

接收Topic：$SYS/tokenInvalidNotice
內容：JSONString
內容資訊：
名稱類型說明
code int Token校正失敗的類型。
type String Token類型，分為W、R、RW共三種，對應用戶端上傳的三種權限類別型的Token。

響應：

服務端校正Token失效，會導致鑒權失敗，服務端會主動取消連結。取消連結之前，服務端會給用戶端推送失敗的Code，用戶端根據Code即可判斷原因。