裝置期望屬性值 - IoT Platform

雲端可以調用SetDeviceDesiredProperty介面，設定期望屬性值來控制裝置。在雲端設定裝置期望屬性值後，若裝置線上，將即時更新裝置屬性狀態；若裝置離線，期望屬性值將緩衝雲端，待裝置上線後，擷取期望屬性值，並更新屬性狀態。本文介紹裝置期望屬性值的資料格式。

說明雲端通過調用介面設定期望屬性值，請參見SetDeviceDesiredProperty。

擷取期望屬性值

上行（Alink JSON）。

裝置向雲端請求擷取裝置屬性的期望值。

請求Topic：/sys/${productKey}/${deviceName}/thing/property/desired/get。
響應Topic：/sys/${productKey}/${deviceName}/thing/property/desired/get_reply。

Alink請求資料格式：

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

Alink響應資料格式：

{
    "id":"123",
    "code":200,
    "data":{
        "power": {
            "value": "on",
            "version": 2
        }
    }
}

表 1. 請求參數描述
參數	類型	說明
id	String	訊息ID號。String類型的數字，取值範圍0~4294967295，且每個訊息ID在當前裝置中具有唯一性。
version	String	協議版本號碼，目前協議版本號碼唯一取值為1.0。
sys	Object	擴充功能的參數，其下包含各功能欄位。說明使用裝置端SDK開發時，如果未設定擴充功能，則無此參數，相關功能保持預設配置。
ack	Integer	sys下的擴充功能欄位，表示是否返迴響應資料。 1：雲端返迴響應資料。 0：雲端不返迴響應資料。重要該功能配置說明，請參見物模型使用樣本。如果未配置該功能，則無此參數，雲端預設返迴響應資料。
params	List	要擷取期望值的屬性標識符（Identifier）列表。如樣本中列舉了兩個屬性的標識符： `[ "power", "temperature" ]` 如果是自訂模組屬性，屬性標識符格式為`模組標識符:屬性標識符`（中間為英文冒號）。樣本： `[ "test:power", "test:temperature" ]`
method	String	要求方法，取值`thing.property.desired.get`。

表 2. 返回參數描述
參數	類型	說明
id	String	訊息ID號。String類型的數字，取值範圍0~4294967295，且每個訊息ID在當前裝置中具有唯一性。
code	Integer	結果資訊，具體參考裝置端通用code。
data	Object	返回的期望值資訊。樣本中，返回了屬性power的期望值資料，包含期望值value和當前期望值版本version。 `{ "power": { "value": "on", "version": 2 } }` 如果是自訂模組屬性，屬性標識符格式為`模組標識符:屬性標識符`（中間為英文冒號）。樣本： `{ "test:power": { "value": "on", "version": 2 } }` 說明若未在雲端設定過該屬性的期望值，或期望屬性值已被清空，返回對象中不包含該屬性的標識符。如樣本中，屬性temperature無期望值，返回資料中不包含該屬性標識符。 Data所包含的參數具體說明，請見下表data。

表 3. data
參數	類型	說明
key	String	key即屬性的標識符。如樣本中為power。
value	Object	期望屬性值。
version	Integer	當前期望屬性值的版本。說明首次設定期望屬性值後，期望值版本為1。以後每次設定後，期望值版本號碼自動加1。

清空期望屬性值

上行（Alink JSON）。

裝置清除雲端裝置的期望屬性值。

請求Topic：/sys/${productKey}/${deviceName}/thing/property/desired/delete。
響應Topic：/sys/${productKey}/${deviceName}/thing/property/desired/delete_reply。

Alink請求資料格式：

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

Alink響應資料格式：

{
    "id": "123",
    "code": 200,
    "data": { }
}

表 4. 請求參數描述
參數	類型	說明
id	String	訊息ID號。String類型的數字，取值範圍0~4294967295，且每個訊息ID在當前裝置中具有唯一性。
version	String	協議版本號碼，目前協議版本號碼唯一取值為1.0。
sys	Object	擴充功能的參數，其下包含各功能欄位。說明使用裝置端SDK開發時，如果未設定擴充功能，則無此參數，相關功能保持預設配置。
ack	Integer	sys下的擴充功能欄位，表示是否返迴響應資料。 1：雲端返迴響應資料。 0：雲端不返迴響應資料。重要該功能配置說明，請參見物模型使用樣本。如果未配置該功能，則無此參數，雲端預設返迴響應資料。
params	Object	要清除期望值的屬性資訊列表。傳入資料包含屬性的標識符和期望值版本version。如： `{ "power": { "version": 1 }, "temperature": { } }` 如果是自訂模組屬性，屬性標識符格式為`模組標識符:屬性標識符`（中間為英文冒號）。樣本： `{ "test:power": { "version": 1 }, "test:temperature": { } }` params所包含的參數具體說明，請見下表params。
method	String	要求方法，取值`thing.property.desired.delete`。

表 5. params
參數	類型	說明
key	String	key即屬性的標識符。如樣本中，列出了power和temperature兩個屬性標識符。
version	Integer	要刪除期望屬性值的版本號碼。說明 version版本號碼可從Topic：`/sys/${productKey}/${deviceName}/thing/property/desired/get` 擷取。如果指定version為2，則表示雲端最新版本是2時執行清除。如果指定版本為2，但是雲端最新版本是3，則忽略這個清除請求。若請求中，未指定要清除的期望值版本version，則不驗證版本號碼，該屬性的期望值將被清除。

表 6. 返回參數描述
參數	類型	說明
id	String	訊息ID號。String類型的數字，取值範圍0~4294967295，且每個訊息ID在當前裝置中具有唯一性。
code	Integer	結果資訊，具體參考裝置端通用code。
data	Object	返回資料。清空期望屬性值時，返回資料為空白。

IoT Platform：裝置期望屬性值

擷取期望屬性值

清空期望屬性值

相關文檔