云端可以調(diào)用SetDeviceDesiredProperty接口，設(shè)置期望屬性值來控制設(shè)備。在云端設(shè)置設(shè)備期望屬性值后，若設(shè)備在線，將實(shí)時(shí)更新設(shè)備屬性狀態(tài)；若設(shè)備離線，期望屬性值將緩存云端，待設(shè)備上線后，獲取期望屬性值，并更新屬性狀態(tài)。本文介紹設(shè)備期望屬性值的數(shù)據(jù)格式。

說明 云端通過調(diào)用接口設(shè)置期望屬性值，請(qǐng)參見SetDeviceDesiredProperty。

獲取期望屬性值

上行（Alink JSON）。

設(shè)備向云端請(qǐng)求獲取設(shè)備屬性的期望值。

  • 請(qǐng)求Topic：/sys/${productKey}/${deviceName}/thing/property/desired/get。
  • 響應(yīng)Topic：/sys/${productKey}/${deviceName}/thing/property/desired/get_reply。

Alink請(qǐng)求數(shù)據(jù)格式：

{
    "id" : "123",
    "version":"1.0",
    "sys":{
      "ack":0
  },
    "params" : [
        "power",
        "temperature"
    ],
    "method":"thing.property.desired.get"
}

Alink響應(yīng)數(shù)據(jù)格式：

{
    "id":"123",
    "code":200,
    "data":{
        "power": {
            "value": "on",
            "version": 2
        }
    }
}
表 1. 請(qǐng)求參數(shù)描述
參數(shù)類型說明
idString消息ID號(hào)。String類型的數(shù)字，取值范圍0~4294967295，且每個(gè)消息ID在當(dāng)前設(shè)備中具有唯一性。
versionString協(xié)議版本號(hào)，目前協(xié)議版本號(hào)唯一取值為1.0。
sysObject擴(kuò)展功能的參數(shù)，其下包含各功能字段。
說明 使用設(shè)備端SDK開發(fā)時(shí)，如果未設(shè)置擴(kuò)展功能，則無此參數(shù)，相關(guān)功能保持默認(rèn)配置。
ackIntegersys下的擴(kuò)展功能字段，表示是否返回響應(yīng)數(shù)據(jù)。
  • 1：云端返回響應(yīng)數(shù)據(jù)。
  • 0：云端不返回響應(yīng)數(shù)據(jù)。
重要 該功能配置說明，請(qǐng)參見物模型使用示例。

如果未配置該功能，則無此參數(shù)，云端默認(rèn)返回響應(yīng)數(shù)據(jù)。

paramsList要獲取期望值的屬性標(biāo)識(shí)符（Identifier）列表。

如示例中列舉了兩個(gè)屬性的標(biāo)識(shí)符：

[ 
 "power",
 "temperature"
 ]

如果是自定義模塊屬性，屬性標(biāo)識(shí)符格式為模塊標(biāo)識(shí)符:屬性標(biāo)識(shí)符（中間為英文冒號(hào)）。示例：

[ 
 "test:power",
 "test:temperature"
 ]
methodString請(qǐng)求方法，取值thing.property.desired.get。
表 2. 返回參數(shù)描述
參數(shù)類型說明
idString消息ID號(hào)。String類型的數(shù)字，取值范圍0~4294967295，且每個(gè)消息ID在當(dāng)前設(shè)備中具有唯一性。
codeInteger結(jié)果信息， 具體參考設(shè)備端通用code。
dataObject返回的期望值信息。

示例中，返回了屬性power的期望值數(shù)據(jù)，包含期望值value和當(dāng)前期望值版本version。

{
  "power": {
    "value": "on", 
    "version": 2
  }
}

如果是自定義模塊屬性，屬性標(biāo)識(shí)符格式為模塊標(biāo)識(shí)符:屬性標(biāo)識(shí)符（中間為英文冒號(hào)）。示例：

{
  "test:power": {
    "value": "on", 
    "version": 2
  }
}
說明 若未在云端設(shè)置過該屬性的期望值，或期望屬性值已被清空，返回對(duì)象中不包含該屬性的標(biāo)識(shí)符。如示例中，屬性temperature無期望值，返回?cái)?shù)據(jù)中不包含該屬性標(biāo)識(shí)符。

Data所包含的參數(shù)具體說明，請(qǐng)見下表data。

表 3. data
參數(shù)類型說明
keyStringkey即屬性的標(biāo)識(shí)符。如示例中為power。
valueO?bject期望屬性值。
versionInteger當(dāng)前期望屬性值的版本。
說明 首次設(shè)置期望屬性值后，期望值版本為1。以后每次設(shè)置后，期望值版本號(hào)自動(dòng)加1。

清空期望屬性值

上行（Alink JSON）。

設(shè)備清除云端設(shè)備的期望屬性值。

  • 請(qǐng)求Topic：/sys/${productKey}/${deviceName}/thing/property/desired/delete。
  • 響應(yīng)Topic：/sys/${productKey}/${deviceName}/thing/property/desired/delete_reply。

Alink請(qǐng)求數(shù)據(jù)格式：

{
    "id": "123",
    "version": "1.0",
    "sys":{
      "ack":0
  },
    "params": {
        "power": {
            "version": 1
        },
        "temperature": { }
    },
    "method":"thing.property.desired.delete"  
}

Alink響應(yīng)數(shù)據(jù)格式：

{
    "id": "123",
    "code": 200,
    "data": { }
}
表 4. 請(qǐng)求參數(shù)描述
參數(shù)類型說明
idString消息ID號(hào)。String類型的數(shù)字，取值范圍0~4294967295，且每個(gè)消息ID在當(dāng)前設(shè)備中具有唯一性。
versionString協(xié)議版本號(hào)，目前協(xié)議版本號(hào)唯一取值為1.0。
sysObject擴(kuò)展功能的參數(shù)，其下包含各功能字段。
說明 使用設(shè)備端SDK開發(fā)時(shí)，如果未設(shè)置擴(kuò)展功能，則無此參數(shù)，相關(guān)功能保持默認(rèn)配置。
ackIntegersys下的擴(kuò)展功能字段，表示是否返回響應(yīng)數(shù)據(jù)。
  • 1：云端返回響應(yīng)數(shù)據(jù)。
  • 0：云端不返回響應(yīng)數(shù)據(jù)。
重要 該功能配置說明，請(qǐng)參見物模型使用示例。

如果未配置該功能，則無此參數(shù)，云端默認(rèn)返回響應(yīng)數(shù)據(jù)。

paramsO?bject要清除期望值的屬性信息列表。傳入數(shù)據(jù)包含屬性的標(biāo)識(shí)符和期望值版本version。如： 
{
  "power": {
    "version": 1
  }, 
  "temperature": { }
}

如果是自定義模塊屬性，屬性標(biāo)識(shí)符格式為模塊標(biāo)識(shí)符:屬性標(biāo)識(shí)符（中間為英文冒號(hào)）。示例：

{
  "test:power": {
    "version": 1
  }, 
  "test:temperature": { }
}

params所包含的參數(shù)具體說明，請(qǐng)見下表params。

methodString請(qǐng)求方法，取值thing.property.desired.delete。
表 5. params
參數(shù)類型說明
keyStringkey即屬性的標(biāo)識(shí)符。如示例中，列出了power和temperature兩個(gè)屬性標(biāo)識(shí)符。
versionInteger要?jiǎng)h除期望屬性值的版本號(hào)。
說明
  • version版本號(hào)可從Topic：/sys/${productKey}/${deviceName}/thing/property/desired/get 獲取。
  • 如果指定version為2，則表示云端最新版本是2時(shí)執(zhí)行清除。如果指定版本為2，但是云端最新版本是3，則忽略這個(gè)清除請(qǐng)求。
  • 若請(qǐng)求中，未指定要清除的期望值版本version，則不驗(yàn)證版本號(hào)，該屬性的期望值將被清除。
表 6. 返回參數(shù)描述
參數(shù)類型說明
idString消息ID號(hào)。String類型的數(shù)字，取值范圍0~4294967295，且每個(gè)消息ID在當(dāng)前設(shè)備中具有唯一性。
codeInteger結(jié)果信息，具體參考設(shè)備端通用code。
dataO?bject返回?cái)?shù)據(jù)。清空期望屬性值時(shí)，返回?cái)?shù)據(jù)為空。

相關(guān)文檔