小度音箱對接之DuerOS開放平臺智能家居技能協議分析

原創 麦粒橙 2020-06-21 08:02

本文，旨在分析DuerOS開放平臺中智能家居技能協議。
參考的官方地址： https://dueros.baidu.com/didp/doc/dueros-bot-platform/dbp-smart-home/protocol/intro-protocol_markdown
文中僅摘取了幾條協議舉例，具體參照官方文檔。

文章目錄

協議簡介

智能家居協議是DuerOS與智能家居技能之間的通訊協議。通過這些協議您可以輕鬆的通過語音控制家裏的智能設備，與設備進行交互。
智能家居協議使用HTTPS傳輸，協議採用JSON消息格式。

協議格式

智能家居協議指令（directives）由Header和Payload兩部分組成。

舉例如下：

{
    "header": {
        "namespace": "DuerOS.ConnectedHome.Control",
        "name": "TurnOnRequest",
        "messageId": "01ebf625-0b89-4c4d-b3aa-32340e894688",
        "payloadVersion": "1"
    },
    "payload": {
        "accessToken": "[OAuth token here]",
        "appliance": {
            "additionalApplianceDetails": {},
            "applianceId": "[Device ID for Light]"
        },
        "function": "light"
    }
}

Header信息

Header包含消息標識符、指令名稱、命令空間和payload版本信息。

消息格式

{
    "header": {        
        "namespace": "DuerOS.ConnectedHome.Discovery",
        "name": "DiscoverAppliancesRequest",
        "messageId": "6d6d6e14-8aee-473e-8c24-0d31ff9c17a2",
        "payloadVersion": "1"
    }
}

屬性說明

Header包含的屬性及屬性說明。

屬性 屬性說明 是否必須
namespace 指令的類別。 目前支持的類別有：
DuerOS.ConnectedHome.Discovery：發現設備指令。
DuerOS.ConnectedHome.Control：控制設備指令。
DuerOS.ConnectedHome.Query：查詢設備指令。		 是
name 指令的名稱。 是
messageId 消息的唯一標識符，長度小於128個字符。
messageId僅用於標識消息，無其他使用。
建議使用隨機生成的UUID作爲messageId。		 是
payloadVersion payload的版本號。 是

Payload信息

Payload的內容與Header中的name值相關，不同類型的指令，其payload內容也不相同。

舉例如下：

{
    "payload": {
        "accessToken": "[OAuth token here]",
        "appliance": {
            "additionalApplianceDetails": {},
            "applianceId": "[Device ID for Light]"
        },
        "function": "light"
    }
}

協議詳述

DuerOS對控制、查詢、屬性上報等消息進行了分類。根據不同的流程，使用不同的消息。

大致說明如下：

消息類型 說明 控制方向 舉例
發現設備 小度平臺向設備雲發現用戶的設備列表 小度–請求–>設備雲 小度，發現設備
控制消息 用戶對設備的控制類消息
由小度音箱或APP發起，發送到設備雲進行解析		 小度–請求–>設備雲 小度，打開油煙機
小度，回家模式
查詢消息 用戶查詢設備的狀態數據
由小度音箱或APP發起，發送到設備雲進行解析		 小度–請求–>設備雲 小度，查詢煙機風速
小度，查詢PM2.5
錯誤消息 控制、查詢消息，操作失敗時，響應給小度的錯誤消息 設備雲–響應–>小度
設備屬性主動上報 當手動或其他非小度平臺操作了設備後，通知到小度有屬性更新
小度收到通知後，再向設備雲請求設備屬性信息。		 設備雲–請求–>小度
小度–請求–>設備雲
設備信息同步消息 用戶設備信息發生變化時，通知給小度音箱 設備雲–請求–>小度
技能解綁消息通知 當用戶在技能商店解綁智能家居技能時，通知設備雲 小度–請求–>設備雲

發現設備

發現設備消息用於查找用戶可用的設備、可以使用的場景和設備分組信息，有DiscoverAppliancesRequest和DiscoverAppliancesResponse兩個指令。DiscoverAppliancesRequest指令是發出查找設備請求，DiscoverAppliancesResponse指令回覆查找到的設備。如果你的技能應用中的用戶設備信息變更時,可以通過DuerOS提供的異步接口發送通知，觸發用戶設備信息同步到DuerOS。

DiscoverAppliancesRequest

當用戶查找設備時，DuerOS會將該消息發送給技能。另外，用戶每次在DuerOS技能商店啓用你的技能時，此消息會自動觸發一次。

Header信息

屬性 取值
name DiscoverAppliancesRequest
namespace DuerOS.ConnectedHome.Discovery

Payload信息

屬性 描述 是否必須
accessToken 設備雲端獲取的access token。 是
openUid 被授權的百度賬號開放ID，與設備雲賬號一一對應。
設備雲端需要將該字段與用戶賬號一一對應起來存儲
其它協議中如果需要攜帶openUid字段時，則需要返回用戶賬號對應的openUid值。		 是

應用舉例
當用戶說“小度小度，發現設備”，DuerOS理解用戶爲發現設備意圖時或者當用戶在DuerOS技能商店裏啓用技能並授權完成之後會向技能發送該DiscoverAppliancesRequest消息。消息示例如下：

{
    "header": {
        "namespace": "DuerOS.ConnectedHome.Discovery",
        "name": "DiscoverAppliancesRequest",
        "messageId": "6d6d6e14-8aee-473e-8c24-0d31ff9c17a2",
        "payloadVersion": "1"
    },
    "payload": {
        "accessToken": "[OAuth Token here]",
        "openUid": "27a7d83c2d3cfbad5d387cd35f3ca17b"
    }
}

DiscoverAppliancesResponse

當DuerOS請求技能查找可用設備或可用場景時，技能會返回DiscoverAppliancesResponse消息。 如果查找到設備時，會返回設備的相關信息，包括actions、applianceTypes、additionalApplianceDetails、applianceId、friendlyDescription、friendlyName等屬性信息。如果沒有找到設備時，會返回空數組。

Header信息

屬性 取值
name DiscoverAppliancesResponse
namespace DuerOS.ConnectedHome.Discovery

Payload信息

1. 設備信息

屬性 描述說明 是否必須
discoveredAppliances 以對象數組返回客戶關聯設備雲帳戶的設備、場景。
如客戶關聯帳戶沒有設備、場景則返回空數組。
如果在發現過程中出現錯誤，字段值設置爲null, 用戶允許接入的最大的設備數量是300。		 是
discoveredAppliance.applianceTypes 支持的設備、場景類型。 是
discoveredAppliance.applianceId 設備標識符。
標識符在用戶擁有的所有設備上必須是唯一的。此外，標識符需要在同一設備的多個發現請求之間保持一致。
標識符可以包含任何字母或數字和以下特殊字符：_ - = # ; : ? @ &。標識符不能超過256個字符。		 是
discoveredAppliance.modelName 設備型號名稱，是字符串類型，長度不能超過128個字符。 是
discoveredAppliance.version 供應商提供的設備版本。是字符串類型，長度不能超過128個字符。 是
discoveredAppliance.friendlyName 用戶用來識別設備的名稱。
是字符串類型，不能包含特殊字符和標點符號，長度不能超過128個字符。		 是
discoveredAppliance.
friendlyDescription		 設備相關的描述。
描述內容需要提及設備廠商，使用場景及連接方式。
長度不超過128個字符。		 是
discoveredAppliance.isReachable 設備當前是否能夠到達。true表示設備當前可以到達，false表示當前設備不能到達。 是
discoveredAppliance.actions 設備支持的操作類型數組。詳細情況請參見 設備操作類型。 是
discoveredAppliance.
additionalApplianceDetails		 提供給設備雲使用，存放設備或場景相關的附加信息，是鍵值對。
DuerOS不解析或使用這些數據。該屬性的內容不能超過5000字節。		 是
內容可以爲空
discoveredAppliance.
manufacturerName		 設備廠商的名字。 是
discoveredAppliance.attributes 設備的屬性信息。
當設備沒有屬性信息時，協議中不需要傳入該字段。
每個設備允許同步的最大的屬性數量是10。
詳細信息請參考設備屬性及設備屬性上報。		 否
建議將設備屬性上報，方便用戶查詢
discoveredAppliance.attribute.name 屬性名稱，支持數字、字母和下劃線，長度不能超過128個字符。 是
discoveredAppliance.attribute.value 屬性值，支持多種json類型。 是
discoveredAppliance.attribute.scale 屬性值的單位名稱，支持數字、字母和下劃線，長度不能超過128個字符。 是
discoveredAppliance.attribute.
timestampOfSample		 屬性值取樣的時間戳，單位是秒。 是
discoveredAppliance.
attribute.
uncertaintyInMilliseconds		 屬性值取樣的時間誤差，單位是ms。
如果設備使用的是輪詢時間間隔的取樣方式，那麼uncertaintyInMilliseconds就等於時間間隔。如溫度傳感器每1秒取樣1次，那麼uncertaintyInMilliseconds的值就是1000。		 是

2. 分組信息

屬性 描述說明 是否必須
discoveredGroups discoveredGroups 對象的數組，該對象包含可發現分組，與用戶設備帳戶相關聯的。
如果沒有與用戶帳戶關聯的分組，此屬性應包含一個空數組。
如果發生錯誤，該屬性可以爲空數組[]。陣列中允許的最大項目數量爲10。		 是
discoveredGroups.groupName 用戶用來識別分組的名稱, 不應包含特殊字符或標點符號，長度不超過20字符。 是
discoveredGroups.applianceIds 分組所包含設備ID的數組，要求設備ID必須是已經發現的設備中的ID，否則會同步失敗
每個分組設備ID數量不超過50。		 是
discoveredGroups.groupNotes 分組備註信息，不能超過128個字符。 是
discoveredGroups.additionalGroupDetails 提供給技能使用的分組相關的附加信息的鍵值對。
該屬性的內容不能超過2000字符。而且DuerOS也不瞭解或使用這些數據。		 是，但可以爲空數組[]

說明：

  • 如果沒有找到設備或相關場景，此時返回的discoveredAppliances是一個空數組。如果查找設備過程中發生了錯誤，該字段值設置爲null。
  • 當applianceTypes=ACTIVITY_TRIGGER/SCENE_TRIGGER時，場景和模式不支持通過分組來控制，比如只支持“打開回家模式”，而不支持“打開客廳的回家模式”。

此處就不舉例了，示例較長。
參考官網： https://dueros.baidu.com/didp/doc/dueros-bot-platform/dbp-smart-home/protocol/discovery-message_markdown

控制消息

控制消息(Control Message)是對智能家居設備進行控制的消息。有門鎖設備控制消息、攝像機設備控制消息、燈光設備控制消息、溫度設備控制消息等。

目前支持以下設備控制消息：

在這裏插入圖片描述
在這裏插入圖片描述

以上描述及語料，純屬個人理解，具體看小度。

舉個例子

TurnOnRequest

當用戶想打開指定設備時，DuerOS會將該消息發送給技能。

Header信息

屬性 取值
name TurnOnRequest
namespace DuerOS.ConnectedHome.Control

Payload信息

屬性 描述說明 是否必須
accessToken 設備雲端獲取的access token。 是
appliance 設備操作的具體對象，包括applianceId和additionalApplianceDetails。 是
appliance.applianceId 設備標識符。標識符在用戶擁有的所有設備上必須是唯一的。此外，標識符需要在同一設備的多個發現請求之間保持一致。標識符可以包含任何字母或數字和以下特殊字符：_ - = # ; : ? @ &。標識符不能超過256個字符。 是
appliance.additionalApplianceDetails 提供給設備雲使用，存放設備或場景相關的附加信息，是鍵值對。DuerOS不解析或使用這些數據。該屬性的內容不能超過5000字節。 是，內容可以爲空
function 表示打開設備的子功能，例如，打開關閉竈臺的燈光、根據此字段識別此類的請求 否

應用舉例

當用戶說“小度小度，打開電燈”，DuerOS理解到用戶意圖後，向技能發送TurnOnRequest消息，消息示例如下。

{
    "header": {
        "namespace": "DuerOS.ConnectedHome.Control",
        "name": "TurnOnRequest",
        "messageId": "01ebf625-0b89-4c4d-b3aa-32340e894688",
        "payloadVersion": "1"
    },
    "payload": {
        "accessToken": "[OAuth token here]",
        "appliance": {
            "additionalApplianceDetails": {},
            "applianceId": "[Device ID for Light]"
        },
        "function": "light"
    }
}

TurnOnConfirmation

當請求的設備成功打開時，技能會發送該消息給DuerOS。

Header信息

屬性 取值
name TurnOnConfirmation
namespace DuerOS.ConnectedHome.Control

Payload信息

屬性 取值 是否必須
attributes 設備屬性信息，支持上報一個或多個屬性信息。請查看屬性信息附錄，瞭解設備的屬性和上報方式。 否，當設備屬性信息發生變化時，建議將屬性變更信息上報給DuerOS。

應用舉例

當電視成功打開時，技能向DuerOS發送TurnOnConfirmation消息，示例如下。

{
    "header": {
        "namespace": "DuerOS.ConnectedHome.Control",
        "name": "TurnOnConfirmation",
        "messageId": "26fa11a8-accb-4f66-a272-8b1ff7abd722",
        "payloadVersion": "1"
    },
    "payload": {
        "attributes": []
    }
}

查詢消息

查詢消息(Query Message)主要是通過智能家居設備查詢空氣質量、查詢空氣溼度、查詢設備溫度、查詢設備狀態等信息。目前支持以下查詢消息。

在這裏插入圖片描述

舉個例子

GetStateRequest

當用戶想了解設備狀態時，DuerOS會該將消息發送給技能，比如想要了解掃地機器人當前狀態(清掃中/充電中/回充中…)時，可以說，“小度小度, 掃地機器人在幹嗎?”， 這時技能會收到GetStateRequest消息。

Header信息

屬性 取值
name GetStateRequest
namespace DuerOS.ConnectedHome.Query

Payload信息

屬性 描述說明 是否必須
accessToken 設備雲端獲取的access token。 是
appliance 設備操作的具體對象。包括applianceId和additionalApplianceDetails。 是
appliance.applianceId 設備標識符。標識符在用戶擁有的所有設備上必須是唯一的。此外，標識符需要在同一設備的多個發現請求之間保持一致。標識符可以包含任何字母或數字和以下特殊字符：_ - = # ; : ? @ &。標識符不能超過256個字符。 是
appliance.additionalApplianceDetails 提供給設備雲使用，存放設備或場景相關的附加信息，是鍵值對。DuerOS不解析或使用這些數據。該屬性的內容不能超過5000字節。 是，內容可以爲空

應用舉例

用戶說“小度小度，掃地機器人在幹嗎?”，DuerOS接收到用戶意圖後，向技能發送GetStateRequest消息。消息示例如下。

{
    "header": {
        "namespace": "DuerOS.ConnectedHome.Query",
        "name": "GetStateRequest",
        "messageId": "01ebf625-0b89-4c4d-b3aa-32340e894688",
        "payloadVersion": "1"
    },
    "payload": {
        "accessToken": "[OAuth token here]",
        "appliance": {
            "additionalApplianceDetails": {},
            "applianceId": "[Device ID for Ceiling Fan]"
        }
    }
}

GetStateResponse

當技能查詢到設備當前狀態時，需要給DuerOS返回該消息，告知用戶當前掃地機器人的狀態。

Header信息

屬性 取值
name GetStateResponse
namespace DuerOS.ConnectedHome.Query

Payload信息

屬性 描述說明 是否必須
attributes 設備的屬性信息，最多支持上報10個屬性。 是
attribute.name 屬性名稱，這裏取"state"。 是
attribute.value 字符串，目前支持的屬性值如下:
CLEANING：清掃中
CHARGING：充電中
RECHARGING：回充中
SLEEPING：休眠中
STAND_BY：待命中
REPORT_ERROR：報錯
SHUT_DOWN：關機
REMOTE_CONTROLING：遙控中
PAUSED：已暫停
 是
attribute.scale 屬性值的單位名稱，這裏是空串’’。 是
attribute.timestampOfSample 屬性值取樣的時間戳，單位是秒。 是
attribute.uncertaintyInMilliseconds 屬性值取樣的時間誤差，單位是ms。 是

應用舉例

技能查詢到“掃地機器人當前的運行狀態是正在清掃時”，向DuerOS返回GetStateResponse消息，消息示例如下。

{
    "header": {
        "namespace": "DuerOS.ConnectedHome.Query",
        "name": "GetStateResponse",
        "messageId": "780013dd-99d0-4c69-9e35-db0457f9f2a7",
        "payloadVersion": "1"
    },
    "payload": {
        "attributes": [{
            "name": "state",
            "value": "CLEANING",
            "scale": "",
            "timestampOfSample":1496741861,
            "uncertaintyInMilliseconds": 10
        }]
    }
}

錯誤消息

當DuerOS向技能發送設備請求信息時，請求信息中可能存在設備不支持或者超出設備使用範圍等問題，此時技能會返回相應的錯誤類型和信息。技能不需要返回每個錯誤，僅返回錯誤對應的錯誤類型。本文列出了錯誤類型和詳細信息。

在這裏插入圖片描述
在這裏插入圖片描述

舉個例子

ValueOutOfRangeError

當用戶請求中對設備的設置參數超過設備支持的參數範圍時，DuerOS就會收到該錯誤消息。

Header信息

屬性 取值
name ValueOutOfRangeError
namespace DuerOS.ConnectedHome.Control

Payload信息

屬性 描述說明 是否必須
minimumValue 設備的允許設置參數的最小值，是64位雙精度值類型。 是
maximumValue 設備的允許設置參數的最大值，是64位雙精度值類型。 是

應用舉例

如用戶想把空調溫度設置爲10度，但是空調的溫度範圍是17到30度，此時技能就會發送該消息給DuerOS，說明用戶輸入參數範圍錯誤。消息示例如下。

{
    "header":{
        "namespace":"DuerOS.ConnectedHome.Control",
        "name":" ValueOutOfRangeError",
        "messageId":"697fe957-c842-4545-a159-8a8c75fbe5bd"，
        "payloadVersion":"1",
    },
    "payload":{
        "minimumValue":17.0,
        "maximumValue":30.0
    }
}

設備屬性主動上報

當用戶手動操作設備或者通過第三方app修改設備狀態，如手動關閉廚房燈，手動切換電風扇模式，使用第三方app修改設備名稱等，這些情況下DuerOS不會感知到設備屬性變化，需要設備雲主動上報設備屬性。

流程：

  1. 技能主動向DuerOS發送請求消息，請求DuerOS同步設備屬性信息。

  2. DuerOS收到請求後向技能發送ReportStateRequest消息，請求技能上報相應的屬性信息

  3. 技能收到請求後，將向DuerOS發送ReportStateResponse消息，上報屬性信息。

主動上報請求消息

當用戶手動操作設備或者通過第三方app修改設備狀態時，技能會主動上報屬性信息，發送上報請求消息。

接口地址

https://xiaodu.baidu.com/saiya/smarthome/changereport

請求方式

POST請求方式。

Head說明

參數名稱 取值
Content-Type application/json

參數信息

1. Header信息

屬性 取值
namespace DuerOS.ConnectedHome.Control
name ChangeReportRequest

2. Payload信息

屬性 描述說明 是否必須
botId 設備雲技能ID。 是
openUid 用戶被授權的百度賬號開放ID，與設備雲賬號一一對應。 是
appliance 上報的設備對象，包括applianceId和attributeName。 是
appliance.applianceId 設備標識符。標識符在用戶擁有的所有設備上必須是唯一的。此外，標識符需要在同一設備的多個發現請求之間保持一致。標識符可以包含任何字母或數字和以下特殊字符：_ - = # ; : ? @ &。標識符不能超過256個字符。 是
appliance.attributeName 設備的屬性名稱，每次僅請求上報一個屬性。 是

請求示例

curl -v "https://xiaodu.baidu.com/saiya/smarthome/changereport" -H 'Content-Type:application/json' -d
'{
    "header": {
        "namespace": "DuerOS.ConnectedHome.Control",
        "name": "ChangeReportRequest",
        "messageId": "01ebf625-0b89-4c4d-b3aa-32340e894688",
        "payloadVersion": "1"
    },
    "payload": {
        "botId": "5385e18b-619a-abcd-ed10-33a7d69780a6",
        "openUid": "27a7d83c2d3cfbad5d387cd35f3ca17b",
        "appliance": {
            "applianceId": "[Device ID for Light]",
            "attributeName": "powerState"
        }
    }
}

說明

  • 這裏主動上報的屬性，屬性值是通過ReportStateRequest查詢到的，所以需要在ReportStateRequest協議實現中支持上對於上報屬性的查詢。

請求返回消息

當技能主動發起上報屬性請求後，DuerOS返回確認信息。

參數說明

參數名稱 描述 類型 是否必須
status 消息狀態。0表示已經完成屬性上報，非0表示消息異常。 int 是
msg 消息提示信息。當狀態碼爲0時，提示更新的屬性記錄數。當狀態碼非0時，返回對應的錯誤消息。 string 是
messageId 請求消息中的messageId信息。 string 是
data 返回消息的數據信息。 array 是
data.updated_attribute_num 同步屬性的數量。 int 是

返回示例

{
    “status”: 0, 
    "msg": "update 3 attributes", 
    "messageId": "請求消息中的messageId", 
    "data": {
        "updated_attribute_num": 3
    }
}

ReportStateRequest消息

當DuerOS收到技能主動上報設備屬性的請求時，會向技能發送ReportStateRequest消息，請求技能上報屬性的完整信息。

Header信息

屬性 取值
name ReportStateRequest
namespace DuerOS.ConnectedHome.Query

Payload信息

屬性 描述說明 是否必須
accessToken 設備雲端獲取的access token。 是
appliance 設備操作的具體對象。包括applianceId和additionalApplianceDetails。 是
appliance.applianceId 設備標識符。標識符在用戶擁有的所有設備上必須是唯一的。此外，標識符需要在同一設備的多個發現請求之間保持一致。標識符可以包含任何字母或數字和以下特殊字符：_ - = # ; : ? @ &。標識符不能超過256個字符。 是
appliance.additionalApplianceDetails 提供給設備雲使用，存放設備或場景相關的附加信息，是鍵值對。DuerOS不解析或使用這些數據。該屬性的內容不能超過5000字節。 是，內容可以爲空
appliance.attributeName 查詢的屬性名稱，字符串類型，支持數字、字母和下劃線，長度不能超過128個字符。 是

應用舉例

當手動將關上廚房燈時，廚房燈的屬性發生變化，技能主動向DuerOS發送請求，DuerOS收到請求後，向技能發送ReportStateRequest消息，消息示例如下。

{
    "header": {
        "namespace": "DuerOS.ConnectedHome.Query",
        "name": "ReportStateRequest",
        "messageId": "01ebf625-0b89-4c4d-b3aa-32340e894688",
        "payloadVersion": "1"
    },
    "payload": {
        "accessToken": "[OAuth token here]",
        "appliance": {
            "additionalApplianceDetails": {},
            "applianceId": "[Device ID for Light ]"
            "attributeName": "turnOnState"
        }
    }
}

ReportStateResponse消息

當技能收到ReportStateRequest請求消息時，會主動上報請求消息中屬性的完整信息，並向技能發送ReportStateResponse消息。

Header信息

屬性 取值
name ReportStateResponse
namespace DuerOS.ConnectedHome.Query

Payload信息

屬性 描述說明 是否必須
attributes 設備的屬性信息，最多支持上報10個屬性。 是
attribute.name 屬性名稱，支持數字、字母和下劃線，長度不能超過128個字符。 是
attribute.value 屬性值，支持多種json類型。 是
attribute.scale 屬性值的單位名稱，支持數字、字母和下劃線，長度不能超過128個字符。 是
attribute.timestampOfSample 屬性值取樣的時間戳，單位是秒。 是
attribute.uncertaintyInMilliseconds 屬性值取樣的時間誤差，單位是ms。如果設備使用的是輪詢時間間隔的取樣方式，那麼uncertaintyInMilliseconds就等於時間間隔。如溫度傳感器每1秒取樣1次，那麼uncertaintyInMilliseconds的值就是1000。 是

應用舉例

技能獲取到廚房燈的turnOnState屬性時，向DuerOS發送ReportStateResponse消息，消息示例如下。

{
    "header": {
        "namespace": "DuerOS.ConnectedHome.Query",
        "name": "ReportStateResponse",
        "messageId": "780013dd-99d0-4c69-9e35-db0457f9f2a7",
        "payloadVersion": "1"
    },
    "payload": {
        "attributes": [
            {
                "name": "turnOnState",
                "value": "OFF",
                "scale": "",
                "timestampOfSample": 1496741861,
                "uncertaintyInMilliseconds": 0
            }
        ]
    }
}

說明

  • 技能主動上報屬性時，在主動上報請求消息中每次僅請求上報一個屬性，在ReportStateResponse消息中除了返回請求的屬性外，還可以返回設備的其他屬性信息，最多支持返回10個屬性信息。

設備信息同步消息

該接口爲廠商通知DuerOS的接口，當技能涉及的用戶設備信息發生變化時，如用戶新增設備或減少設備，此時技能可以通過設備信息同步接口請求DuerOS進行設備信息同步。

請求消息說明

技能向DuerOS發送請求消息，請求DuerOS同步設備變更信息。

接口地址

https://xiaodu.baidu.com/saiya/smarthome/devicesync

請求方式

POST請求方式

參數說明

參數名稱 參數說明 類型 是否必需
botId 技能ID。 string 是
logId 技能本次請求logId。 string 是
openUids 需要同步的用戶openUid信息，每次同步的openUid不超過5個。 array 是

Head說明

參數名稱 取值
Content-Type application/json

請求示例

curl -v "https://xiaodu.baidu.com/saiya/smarthome/devicesync" -H 'Content-Type:application/json' -d
'{
    "botId":"123456xyz-123456-4c5d-345677xyz",
    "logId":"123456789",
    "openUids":[
        "17a7d83c2d3cfbad5d387cd35f3ca17b"
    ]
}'

返回說明

當技能發起設備信息同步請求後，DuerOS返回信息同步確認消息。

參數說明

參數名稱 描述 類型 是否必須
status 請求消息狀態。0表示消息正常，非0表示消息異常。 int 是
msg 請求消息同步狀態，可能出現以下情況。
ok：表示至少一個openUid同步成功。
openUid not more than 5：表示openUid信息超過5個。
not support botId：表示技能ID不存在。
sync failed：表示請求信息同步失敗。
param error：表示參數不合法。		 string 是
logid 請求消息中的logid。 string 是
data 返回消息的數據信息。 array 是
data.failed 同步失敗的openUid集合。 array 是
data.succeed 同步成功的openUid集合。 array 是

返回示例

{
    "status": 0,
    "msg": "ok",
    "logid": "123456789",
    "data": {
        "failed": [],
        "succeed": [
            "17a7d83c2d3cfbad5d387cd35f3ca17b"
        ]
    }
}

技能解綁消息通知

該接口爲DuerOS通知廠商的接口。當用戶在技能商店解綁智能家居技能時，DuerOS會使用該協議通知到技能服務器，以便第三方智能家居服務提供商獲取到用戶的這一行爲而做出相應的邏輯變化，比如，用戶解綁技能後，當用戶新增設備時，不再通知DuerOS。協議使用HTTPS傳輸，採用JSON消息格式。

UnbindBotRequest

當用在技能商店解綁該技能時，DuerOS會將該消息發送給技能。

Header信息

屬性 取值
name UnbindBotRequest
namespace DuerOS.ConnectedHome.UnbindBot

Payload信息

屬性 描述 是否必須
accessToken 設備雲端獲取的access token。 是

應用舉例

當用戶在技能商店解綁了該技能時, DuerOS向技能發送UnbindBot消息，消息樣例如下

{
    "header": {
        "namespace": "DuerOS.ConnectedHome.UnbindBot",
        "name": "UnbindBotRequest",
        "messageId": "6d6d6e14-8aee-473e-8c24-0d31ff9c17a2",
        "payloadVersion": "1"
    },
    "payload": {
        "accessToken": "[OAuth Token here]"
    }
}

UnbindBotResponse

當DuerOS通知技能用戶解綁了該技能，技能會返回UnbindBotResponse消息。

Header信息

屬性 取值
name UnbindBotResponse
namespace DuerOS.ConnectedHome.UnbindBot

Payload信息

Payload信息爲空，DuerOS只是通知技能用戶在DuerOS技能商店解綁了該技能。

應用舉例

當DuerOS向技能發送瞭解綁消息後，技能回覆DuerOS消息樣例如下

{
    "header": {
        "namespace": "DuerOS.ConnectedHome.UnbindBot",
        "name": "UnbindBotResponse",
        "messageId": "6d6d6e14-8aee-473e-8c24-0d31ff9c17a2",
        "payloadVersion": "1"
    },
    "payload": {
    }
}
發表評論
所有評論
還沒有人評論，想成為第一個評論的人麼? 請在上方評論欄輸入並且點擊發布.
相關文章

小度音箱對接之DuerOS開放平臺智能家居技能Java對接Demo實現

近期調研中，編寫了個簡單的Demo，對接DuerOS的智能家居技能。 Demo源碼地址：https://gitee.com/mylitboy/link-smart-speaker-demo 介紹 小度音箱DuerOS對接dem

麦粒橙 2020-06-21 08:02:14

小度音箱對接之小度APP功能分析

本文，旨在分析小度APP中，關於智能控制相關的功能。 文中，以美的美居爲例。 文章目錄小度APP介紹首頁欄目技能欄目VIP欄目小度購欄目我的欄目智能家居模塊添加設備設備控制小結 小度APP介紹 開屏頁： 底部欄目： 頁面彙

麦粒橙 2020-06-07 19:08:42

DuerOS的DCS SDK編譯問題

最近覺得搞技術就是在於折騰，不怕難題不怕折騰纔是最起碼的精神 看到新聞說百度開放了兩個AI平臺，今天一早就來註冊並下了SDK，折騰了一把，遇到幾個問題記錄下（不記自己也會忘，方便自己方便大家）： 1.首先是Android SDK版本與Ja

zhoubintiantian 2020-06-22 17:30:01

小度音箱對接之DuerOS開放平臺功能分析

由於項目需要，需要對接DuerOS，使用小度音箱控制設備。近期會對DuerOS技能平臺進行一些研究，尤其是智能控制相關功能。特此記錄。 文章目錄DuerOS開放平臺簡介技能分類自定義技能小技能內容資源智能家居智能家居技能創建技

麦粒橙 2020-06-07 19:08:42

百度開放平臺技能交互模型-創建技能，創建意圖，測試意圖

wenxi2367 2020-02-21 17:40:47

小度音箱對接之DuerOS開放平臺智能家居技能Java對接Demo實現

近期調研中，編寫了個簡單的Demo，對接DuerOS的智能家居技能。 Demo源碼地址：https://gitee.com/mylitboy/link-smart-speaker-demo 介紹 小度音箱DuerOS對接dem

麦粒橙 2020-06-21 08:02:14

小度音箱對接之小度APP功能分析

本文，旨在分析小度APP中，關於智能控制相關的功能。 文中，以美的美居爲例。 文章目錄小度APP介紹首頁欄目技能欄目VIP欄目小度購欄目我的欄目智能家居模塊添加設備設備控制小結 小度APP介紹 開屏頁： 底部欄目： 頁面彙

麦粒橙 2020-06-07 19:08:42

DuerOS的DCS SDK編譯問題

最近覺得搞技術就是在於折騰，不怕難題不怕折騰纔是最起碼的精神 看到新聞說百度開放了兩個AI平臺，今天一早就來註冊並下了SDK，折騰了一把，遇到幾個問題記錄下（不記自己也會忘，方便自己方便大家）： 1.首先是Android SDK版本與Ja

zhoubintiantian 2020-06-22 17:30:01

小度音箱對接之DuerOS開放平臺功能分析

由於項目需要，需要對接DuerOS，使用小度音箱控制設備。近期會對DuerOS技能平臺進行一些研究，尤其是智能控制相關功能。特此記錄。 文章目錄DuerOS開放平臺簡介技能分類自定義技能小技能內容資源智能家居智能家居技能創建技

麦粒橙 2020-06-07 19:08:42

百度開放平臺技能交互模型-創建技能，創建意圖，測試意圖

wenxi2367 2020-02-21 17:40:47

快速瞭解dueros技能開發

web_xiaolei 2019-08-10 06:43:30

dueros老是跑到技能外去搜索表達

web_xiaolei 2019-08-10 06:43:30