(高清版)GB∕T 38052.3-2019 智能家用電器系統(tǒng)互操作 第3部分：服務(wù)平臺(tái)間接口規(guī)范

智能家用電器系統(tǒng)互操作第3部分：服務(wù)平臺(tái)間接口規(guī)范Part3:Interfacespecificationbetweenser國(guó)家市場(chǎng)監(jiān)督管理總局GB/T38052.3—2019 I 2規(guī)范性引用文件 2 2 2 3 3 5 5 5 6 77.4設(shè)備管理服務(wù)接口 7.5信息同步服務(wù)接口 7.6編碼解析服務(wù)接口 8RetCode說(shuō)明 本部分為GB/T38052的第3部分。1GB/T38052.1智能家用電器系統(tǒng)互操作第1部分：術(shù)語(yǔ)HTTPS:有安全套接層的超文本傳輸協(xié)議(HyperTextTransferProtocoloverSecureSocket2圖1。4行業(yè)服務(wù)平臺(tái)接口采用HTTPS方式，接口提供的統(tǒng)一接入點(diǎn)為https://domain:port/p廠商服務(wù)平臺(tái)接口采用HTTPS方式，接口3服務(wù)平臺(tái)間接口使用的數(shù)據(jù)類型見(jiàn)表1。中文名稱說(shuō)明字符串弱類型語(yǔ)言(如Php、Python等)中的字符串Java中的Int、Byte、Short、時(shí)間戳指格林威治時(shí)間，即1970年01月01日00時(shí)00分00秒000毫秒(北京時(shí)間1970年01月01日08時(shí)00分00秒000毫秒)起至?xí)r間的總毫秒數(shù)，文本表達(dá)對(duì)應(yīng)JSON中的“對(duì)象符號(hào)”,方便平臺(tái)與家電間多個(gè)JSON對(duì)象符號(hào)的集合，應(yīng)由平臺(tái)及家電自行解析為本地?cái)?shù)據(jù)類型使用消息結(jié)構(gòu)見(jiàn)表2,HTTPBody由消息頭和消息體組成，其中消息頭和消息體的數(shù)據(jù)是基于JSON消息頭格式見(jiàn)表3。4中文名稱說(shuō)明98其他情況取值唯一命令方向211——行業(yè)平臺(tái)到其他平臺(tái)命令12——其他平臺(tái)到行業(yè)平臺(tái)命令其他：預(yù)留1至少支持以下方式的一種：其他：預(yù)留1其他：預(yù)留時(shí)間戳8時(shí)間戳，精確到毫秒，時(shí)間為該消息生成時(shí)間5參數(shù)名說(shuō)明應(yīng)采用非對(duì)稱加密算法保證MessageBody信息在傳輸過(guò)程的機(jī)密性。公鑰最低安全長(zhǎng)度不低于2048位，宜使用RSA算法。b)IP驗(yàn)證僅為初步驗(yàn)證請(qǐng)求來(lái)源的合法性方法。收集所有相關(guān)廠商服務(wù)平臺(tái)的IP,創(chuàng)建廠商服行業(yè)服務(wù)平臺(tái)對(duì)于來(lái)自單一請(qǐng)求方的請(qǐng)求有請(qǐng)求限制。對(duì)于不同的請(qǐng)求配額，超過(guò)限制的請(qǐng)求將被行業(yè)服務(wù)平臺(tái)拒絕服務(wù)。請(qǐng)求頻率的上限、配額再6a)平臺(tái)管理服務(wù)接口；b)用戶管理服務(wù)接口；的平臺(tái)唯一標(biāo)識(shí)碼(UPlatID)。廠商服務(wù)平臺(tái)中保留該UPlatID的信息，在廠商服務(wù)平臺(tái)實(shí)現(xiàn)互聯(lián)通信中使用UPlatID標(biāo)識(shí)該廠商服務(wù)平臺(tái)。行業(yè)服務(wù)平臺(tái)可通過(guò)UPlatID對(duì)接入平臺(tái)的操作權(quán)限和服廠商服務(wù)平臺(tái)平臺(tái)注冊(cè)請(qǐng)求行業(yè)服務(wù)平臺(tái)平臺(tái)注冊(cè)應(yīng)答服務(wù)平臺(tái)注冊(cè)接口見(jiàn)表5。請(qǐng)求參數(shù)(廠商服務(wù)平臺(tái)向行業(yè)服務(wù)平臺(tái)發(fā)起請(qǐng)求):數(shù)據(jù)類型說(shuō)明服務(wù)平臺(tái)類型(廠商服務(wù)平臺(tái)默認(rèn)為01),見(jiàn)響應(yīng)參數(shù)(行業(yè)服務(wù)平臺(tái)向廠商服務(wù)平臺(tái)響應(yīng)):數(shù)據(jù)類型說(shuō)明a)廠商服務(wù)平臺(tái)與行業(yè)服務(wù)平臺(tái)通過(guò)合約關(guān)系進(jìn)行平臺(tái)注冊(cè)，行業(yè)服務(wù)平臺(tái)為廠商服務(wù)平臺(tái)分配了UPlatID。d)行業(yè)服務(wù)平臺(tái)給廠商控制終端用戶分配一個(gè)UUserID,廠商服務(wù)平臺(tái)中建立UUserID和78注冊(cè)互聯(lián)互通用戶請(qǐng)求參數(shù)(廠商服務(wù)平臺(tái)向行業(yè)服務(wù)平臺(tái)發(fā)起互聯(lián)互通用戶注冊(cè)請(qǐng)求):數(shù)據(jù)類型說(shuō)明互聯(lián)互通用戶名響應(yīng)參數(shù)(行業(yè)服務(wù)平臺(tái)向廠商服務(wù)平臺(tái)響應(yīng)互聯(lián)互通用戶注冊(cè)):數(shù)據(jù)類型說(shuō)明驗(yàn)證碼確認(rèn)互聯(lián)互通用戶注銷(xiāo)接口見(jiàn)表7?；ヂ?lián)互通用戶注銷(xiāo)注銷(xiāo)跨平臺(tái)用戶請(qǐng)求參數(shù)(廠商服務(wù)平臺(tái)向行業(yè)服務(wù)平臺(tái)發(fā)起互聯(lián)互通用戶注銷(xiāo)請(qǐng)求):數(shù)據(jù)類型說(shuō)明響應(yīng)參數(shù)(行業(yè)服務(wù)平臺(tái)向廠商服務(wù)平臺(tái)響應(yīng)互聯(lián)互通用戶注銷(xiāo)):數(shù)據(jù)類型說(shuō)明9a)用戶使用A廠商控制終端通過(guò)掃描條碼或二維碼的方式獲取B廠商家電的UDeviceID,且用戶A添加B廠商家電請(qǐng)求UUserID、UDeviceIDB廠商服務(wù)終端a)用戶使用A廠商控制終端通過(guò)掃描條碼或二維碼的方式獲取B廠商家電的UDeviceID,且c)B廠商服務(wù)平臺(tái)確認(rèn)該UDeviceID是否有屬主UserID,如B廠商服務(wù)平臺(tái)確認(rèn)該UDeviceID已有屬主UserID,則B廠商服務(wù)平臺(tái)將核對(duì)該屬主UserID注冊(cè)時(shí)預(yù)留的手機(jī)號(hào)碼以及家電的屬主用戶名和密碼，經(jīng)B廠商服務(wù)平臺(tái)驗(yàn)證正確后，在B廠商服務(wù)平臺(tái)中建立BB廠商服務(wù)平臺(tái)根據(jù)UUserID建立B平B廠商家電有屬并通過(guò)屬主確認(rèn)用戶A添加B家電請(qǐng)求第三方用戶注冊(cè)接口見(jiàn)表8。廠商服務(wù)平臺(tái)通過(guò)行業(yè)服務(wù)平臺(tái)向第三方廠商服務(wù)平請(qǐng)求參數(shù)(廠商服務(wù)平臺(tái)通過(guò)行業(yè)服務(wù)平臺(tái)向第三方廠商服務(wù)平臺(tái)發(fā)起用戶注冊(cè)請(qǐng)求):數(shù)據(jù)類型說(shuō)明用戶唯一碼用戶名響應(yīng)參數(shù)(第三方廠商服務(wù)平臺(tái)通過(guò)行業(yè)服務(wù)平臺(tái)向廠商服務(wù)平臺(tái)響應(yīng)用戶注冊(cè)請(qǐng)求):數(shù)據(jù)類型說(shuō)明b)廠商控制終端向廠商服務(wù)平臺(tái)發(fā)送請(qǐng)求注銷(xiāo)該UUserID,廠商平臺(tái)確定該UUserID非本廠商直接管理的用戶，則向行業(yè)服務(wù)平臺(tái)發(fā)送注銷(xiāo)請(qǐng)求，行業(yè)服務(wù)平臺(tái)c)該用戶的管理廠商平臺(tái)向該UUserID注冊(cè)的手機(jī)號(hào)碼發(fā)送驗(yàn)證碼，A廠商控制終端輸入正確e)將UUserID相關(guān)的用戶和設(shè)備信息同步給行業(yè)服務(wù)平臺(tái)和A廠商服務(wù)平臺(tái)。使用廠商控制終端注銷(xiāo)第三方用戶流程見(jiàn)圖7。第三方用戶注銷(xiāo)接口見(jiàn)表9。第三方用戶注銷(xiāo)廠商服務(wù)平臺(tái)通過(guò)行業(yè)服務(wù)平臺(tái)向第三方廠商服務(wù)平臺(tái)進(jìn)行第三方用戶注銷(xiāo)請(qǐng)求參數(shù)(廠商服務(wù)平臺(tái)通過(guò)行業(yè)服務(wù)平臺(tái)向第三方廠商服務(wù)平臺(tái)發(fā)起用戶注銷(xiāo)請(qǐng)求):數(shù)據(jù)類型說(shuō)明用戶唯一碼用戶名響應(yīng)參數(shù)(第三方廠商服務(wù)平臺(tái)通過(guò)行業(yè)服務(wù)平臺(tái)向廠商服務(wù)平臺(tái)響應(yīng)用戶注銷(xiāo)):數(shù)據(jù)類型說(shuō)明/user/verificationCod請(qǐng)求參數(shù)(用戶申請(qǐng)驗(yàn)證碼):數(shù)據(jù)類型說(shuō)明響應(yīng)參數(shù)(被請(qǐng)求方反饋驗(yàn)證碼):數(shù)據(jù)類型說(shuō)明表11手機(jī)驗(yàn)證碼驗(yàn)證接口/user/verificationCo請(qǐng)求參數(shù)(用戶輸入驗(yàn)證碼):數(shù)據(jù)類型說(shuō)明響應(yīng)參數(shù)(被請(qǐng)求方驗(yàn)證):數(shù)據(jù)類型說(shuō)明跨平臺(tái)用戶獲取家電的UDeviceID,通過(guò)行業(yè)服務(wù)平臺(tái)和廠商服務(wù)平臺(tái)上進(jìn)行該用戶和家電的綁再實(shí)現(xiàn)對(duì)該設(shè)備的綁定。流程見(jiàn)圖8。a)用戶使用A廠商控制終端通過(guò)掃描條碼或二維碼的方式獲取B廠商家電的UDeviceID,且UDeviceID需采用明碼方式編碼。b)A廠商控制終端將UUserID和UDeviceID通過(guò)A廠商服務(wù)平臺(tái)將請(qǐng)求發(fā)送到行業(yè)服務(wù)平臺(tái)，而行業(yè)服務(wù)平臺(tái)對(duì)UDeviceID進(jìn)行編碼解析，獲取到B廠商服務(wù)平臺(tái)地址信息，將UUserID和UDeviceID綁定請(qǐng)求信息發(fā)送到B廠商服務(wù)平臺(tái)。c)B廠商平臺(tái)確定該UUserID已經(jīng)與本平臺(tái)中的UserID相關(guān)聯(lián)，則建立UUserID和屬主B廠商服務(wù)跨平臺(tái)用戶和家電綁定接口見(jiàn)表12。表12跨平臺(tái)用戶和家電綁定接口/user/thirdpartyBin請(qǐng)求參數(shù)(廠商服務(wù)平臺(tái)通過(guò)行業(yè)服務(wù)平臺(tái)向第三方廠商服務(wù)平臺(tái)發(fā)起家電綁定請(qǐng)求):數(shù)據(jù)類型說(shuō)明響應(yīng)參數(shù)(第三方廠商服務(wù)平臺(tái)通過(guò)行業(yè)服務(wù)平臺(tái)向廠商服務(wù)平臺(tái)響應(yīng)家電綁定請(qǐng)求):數(shù)據(jù)類型說(shuō)明綁定。流程見(jiàn)圖9。a)用戶使用A廠商控制終端啟動(dòng)用戶和家電解綁程序。b)A廠商控制終端將UUserID和UDeviceID通過(guò)A廠商服務(wù)平臺(tái)將請(qǐng)求發(fā)送到行業(yè)服務(wù)平臺(tái)，而行業(yè)服務(wù)平臺(tái)對(duì)UDeviceID進(jìn)行編碼解析，獲取到B廠商服務(wù)平臺(tái)地址信息，將UUserID和UDeviceID解綁請(qǐng)求信息發(fā)送到B廠商服務(wù)平臺(tái)。c)B廠商平臺(tái)發(fā)送驗(yàn)證碼給該UUserID注冊(cè)的手機(jī)號(hào)碼發(fā)送驗(yàn)證碼，平臺(tái)確認(rèn)用戶輸入正確的驗(yàn)證碼后，解除UUserID和UDeviceID的綁定關(guān)系，相關(guān)聯(lián)的從屬用戶也同時(shí)解除與該終端A廠商服務(wù)B廠商服務(wù)平臺(tái)用戶A和B家電解除綁定請(qǐng)求→跨平臺(tái)用戶和家電解綁接口見(jiàn)表13。表13跨平臺(tái)用戶和家電解綁接口/user/thirtyPartyUnbind解除跨平臺(tái)用戶和家電之間的綁定關(guān)系請(qǐng)求參數(shù)(廠商服務(wù)平臺(tái)通過(guò)行業(yè)服務(wù)平臺(tái)向第三方廠商服務(wù)平臺(tái)發(fā)起家電解綁請(qǐng)求):說(shuō)明響應(yīng)參數(shù)(第三方廠商服務(wù)平臺(tái)通過(guò)行業(yè)服務(wù)平臺(tái)向廠商服務(wù)平臺(tái)響應(yīng)家電解綁請(qǐng)求):說(shuō)明跨平臺(tái)用戶通過(guò)獲取廠商家電的描述文件，解析生成相關(guān)的操作界面?？缃K端-用戶A申請(qǐng)下載B家電描述文件用戶A申請(qǐng)下載B家電描述文件圖10行業(yè)服務(wù)平臺(tái)提供設(shè)備描述文件流程A廠商控制A廠商服務(wù)用戶A查詢B家電描述文件→查詢?cè)O(shè)備描述文件接口見(jiàn)表14。表14查詢?cè)O(shè)備描述文件接口請(qǐng)求參數(shù)(廠商服務(wù)平臺(tái)通過(guò)行業(yè)服務(wù)平臺(tái)向第三方廠商服務(wù)平臺(tái)發(fā)起查詢?cè)O(shè)備描述文件請(qǐng)求):說(shuō)明響應(yīng)參數(shù)(第三方廠商服務(wù)平臺(tái)通過(guò)行業(yè)服務(wù)平臺(tái)向廠商服務(wù)平臺(tái)響應(yīng)查詢?cè)O(shè)備描述文件):說(shuō)明請(qǐng)求參數(shù)(廠商服務(wù)平臺(tái)通過(guò)行業(yè)服務(wù)平臺(tái)向第三方廠商服務(wù)平臺(tái)發(fā)起獲取設(shè)備描述文件請(qǐng)求):數(shù)據(jù)類型說(shuō)明響應(yīng)參數(shù)(第三方廠商服務(wù)平臺(tái)通過(guò)行業(yè)服務(wù)平臺(tái)向廠商服務(wù)平臺(tái)響應(yīng)獲取設(shè)備描述文件):數(shù)據(jù)類型說(shuō)明A廠商服務(wù)B家電狀態(tài)設(shè)備狀態(tài)查詢接口見(jiàn)表16。表16設(shè)備狀態(tài)查詢接口設(shè)備狀態(tài)查詢請(qǐng)求參數(shù)(廠商服務(wù)平臺(tái)通過(guò)行業(yè)服務(wù)平臺(tái)向第三方廠商服務(wù)平臺(tái)發(fā)起家電狀態(tài)查詢請(qǐng)求):說(shuō)明需要查詢狀態(tài)的家電唯一標(biāo)識(shí)碼響應(yīng)參數(shù)(第三方廠商服務(wù)平臺(tái)通過(guò)行業(yè)服務(wù)平臺(tái)向廠商服務(wù)平臺(tái)響應(yīng)家電狀態(tài)查詢):說(shuō)明需要查詢狀態(tài)的家電唯一標(biāo)識(shí)碼00——狀態(tài)匯報(bào)信息用戶通過(guò)行業(yè)服務(wù)平臺(tái)對(duì)其他廠商的家電進(jìn)行操作。流程見(jiàn)圖13。B家電狀態(tài)B家電狀態(tài)B家電狀態(tài)B廠商家電B圖13跨廠商平臺(tái)的家電操作流程跨廠商平臺(tái)的家電操作接口見(jiàn)表17。表17跨廠商平臺(tái)的家電操作接口對(duì)家電進(jìn)行操作。此操作需提供由用戶登錄后平臺(tái)頒發(fā)的AccessToken,且僅限于用戶請(qǐng)求參數(shù)(廠商服務(wù)平臺(tái)通過(guò)行業(yè)服務(wù)平臺(tái)向第三方廠商服務(wù)平臺(tái)發(fā)起家電操作請(qǐng)求):說(shuō)明需要操作的家電唯一標(biāo)識(shí)碼響應(yīng)參數(shù)(第三方廠商服務(wù)平臺(tái)通過(guò)行業(yè)服務(wù)平臺(tái)向廠商服務(wù)平臺(tái)響應(yīng)家電操作):說(shuō)明需要操作的家電唯一標(biāo)識(shí)碼設(shè)備廠商服務(wù)平臺(tái)周期性的從設(shè)備獲得狀態(tài)信息，并將設(shè)備的狀態(tài)態(tài)上報(bào)流程見(jiàn)圖14。A圖14跨廠商平臺(tái)的家電狀態(tài)上報(bào)流程家電狀態(tài)上報(bào)接口見(jiàn)表18。/devices/deviceStat設(shè)備廠商服務(wù)平臺(tái)主動(dòng)向需求方平臺(tái)上報(bào)家電狀態(tài)信息請(qǐng)求參數(shù)(第三方廠商服務(wù)平臺(tái)通過(guò)行業(yè)服務(wù)平臺(tái)向廠商服務(wù)平臺(tái)發(fā)起家電狀態(tài)上報(bào)請(qǐng)求):數(shù)據(jù)類型說(shuō)明00——狀態(tài)匯報(bào)信息01——家電上下線事件通知響應(yīng)參數(shù)(廠商服務(wù)平臺(tái)通過(guò)行業(yè)服務(wù)平臺(tái)向第三方廠商服務(wù)平臺(tái)響應(yīng)家電狀態(tài)上報(bào)):數(shù)據(jù)類型說(shuō)明AA制A務(wù)行業(yè)服務(wù)平臺(tái)B務(wù)B廠商家電圖15跨廠商平臺(tái)的家電故障報(bào)警流程家電故障報(bào)警接口見(jiàn)表19。設(shè)備廠商服務(wù)平臺(tái)主動(dòng)向需求方平臺(tái)上報(bào)家電狀態(tài)信息請(qǐng)求參數(shù)(第三方廠商服務(wù)平臺(tái)通過(guò)行業(yè)服務(wù)平臺(tái)向廠商服務(wù)平臺(tái)發(fā)起家電故障報(bào)警請(qǐng)求)數(shù)據(jù)類型說(shuō)明設(shè)備報(bào)警信息數(shù)據(jù)，見(jiàn)GB/T36428響應(yīng)參數(shù)(廠商服務(wù)平臺(tái)通過(guò)行業(yè)服務(wù)平臺(tái)向第三方廠商服務(wù)平臺(tái)響應(yīng)家電故障報(bào)警):數(shù)據(jù)類型說(shuō)明綁定授權(quán)關(guān)系等信息應(yīng)在不同的平臺(tái)中保持同步。一旦有用戶和設(shè)備信息的和用戶唯一標(biāo)識(shí)碼(UUserID)的映射表，還應(yīng)在各服信息同步服務(wù)行業(yè)平臺(tái)側(cè)接口見(jiàn)表20。信息同步服務(wù)行業(yè)平臺(tái)側(cè)接口設(shè)備廠商服務(wù)平臺(tái)主動(dòng)向需求平臺(tái)上報(bào)同步信息請(qǐng)求參數(shù)(設(shè)備廠商服務(wù)平臺(tái)通過(guò)行業(yè)服務(wù)平臺(tái)向其他廠商服務(wù)平臺(tái)發(fā)起信息同步請(qǐng)求):數(shù)據(jù)類型說(shuō)明響應(yīng)參數(shù)(廠商服務(wù)平臺(tái)通過(guò)行業(yè)服務(wù)平臺(tái)向第三方廠商服務(wù)平臺(tái)響應(yīng)信息同步):數(shù)據(jù)類型說(shuō)明則行業(yè)服務(wù)平臺(tái)通過(guò)向編碼解析平臺(tái)發(fā)送編碼查詢請(qǐng)求獲取該編圖16。表21編碼解析接口請(qǐng)求參數(shù)(廠商服務(wù)平臺(tái)向行業(yè)服務(wù)平臺(tái)發(fā)送編碼解析的請(qǐng)求):數(shù)據(jù)類型說(shuō)明需解析的編碼響應(yīng)參數(shù)(行業(yè)服務(wù)平臺(tái)向廠商服務(wù)平臺(tái)響應(yīng)編碼解析的結(jié)果):數(shù)據(jù)類型說(shuō)明返回值中文說(shuō)明RetCode(十進(jìn)制)返回值英文說(shuō)明1234567Userregistrationfai89ApplicationuninstallfailedEncryptionprotocolnegoiationf時(shí)間戳不在有效范圍內(nèi)UPlatformregistrationfaiUUserregistrationfaiThird-partyuserregistrationfCancellationfailed,third-partUUserpasswordmodificationfaiDeleteusertofamily表22(續(xù))返回值中文說(shuō)明RetCode(十進(jìn)制)返