子設備可以逐個上下線，也可以批量上下線。子設備上線之前，需在物聯網平臺為子設備注冊身份，建立子設備與網關的拓撲關系。子設備上線時，物聯網平臺會根據拓撲關系進行子設備身份校驗，以確定子設備是否具備使用網關通道的能力。

說明
  • 子設備上下線、批量上下線消息，只支持QoS=0，不支持QoS=1。
  • 一個網關下，同時在線的子設備數量不能超過2,000。在線子設備數量達到2,000個后，新的子設備上線請求將被拒絕。
  • 發送子設備批量上下線請求時，單個批次上下線的子設備數量不超過50個。
  • 設備批量上下線請求結果為全部成功或全部失敗，失敗時的data響應參數中會包含具體的設備信息。

子設備上線

數據上行：

  • 請求Topic：/ext/session/${productKey}/${deviceName}/combine/login
  • 響應Topic：/ext/session/${productKey}/${deviceName}/combine/login_reply
說明 因為子設備通過網關通道與物聯網平臺通信，以上Topic為網關設備的Topic。Topic中變量${productKey}和${deviceName}需替換為網關設備的對應信息。

Alink請求數據格式：

{
  "id": "123",
  "params": {
    "productKey": "al12345****",
    "deviceName": "device1234",
    "clientId": "al12345****&device1234",
    "timestamp": "1581417203000",
    "signMethod": "hmacmd5",
    "sign": "9B9C732412A4F84B981E1AB97CAB****",
    "cleanSession": "true"
  }
}
說明 消息體中，參數productKey和deviceName的值是子設備的對應信息。
表 1. 請求參數說明
參數類型說明
idString消息ID號。String類型的數字，取值范圍0~4294967295，且每個消息ID在當前設備中具有唯一性。
paramsObject請求入參，包含的具體參數見下表params。
表 2. params
參數類型說明
deviceNameString子設備的設備名稱。
productKeyString子設備所屬的產品的ProductKey。
signString

子設備簽名。簽名方法與直連設備簽名方法相同。

簽名方法：

  1. 將所有提交給服務器的參數（sign，signMethod 和 cleanSession除外）按照字母順序排序，然后將參數和值依次拼接（無拼接符號）。
  2. 對加簽內容，通過signMethod指定的加簽算法，并使用設備的DeviceSecret值，進行簽名計算。

    計算結果作為sign的取值。

sign值計算方法示例如下：

hmac_md5(deviceSecret, clientIdal12345****&device1234deviceNamedevice1234productKeyal12345****timestamp1581417203000)
signMethodString簽名方法，支持hmacSha1、hmacSha256、hmacMd5和Sha256。
timestampString毫秒級時間戳。
clientIdString設備端標識?？梢詾?code class="ph codeph" data-tag="codeph" id="codeph-lgb-1to-bbo">productKey&deviceName。
cleanSessionString
  • 如果取值是true，則清理所有子設備離線時的消息，即所有未接收的QoS1消息將被清除。
  • 如果取值是false，則不清理子設備離線時的消息。

Alink響應數據格式：

{
  "id":"123",
  "code":200,
  "message":"success"
  "data":{
      "deviceName": "device1234",
      "productKey": "al12345****"
    }
}
表 3. 響應參數說明
參數類型說明
idString消息ID，String類型的數字，取值范圍0~4294967295，且每個消息ID在當前設備中具有唯一性。
codeInteger返回結果，200代表成功。
messageString返回結果信息。
dataObject請求成功或失敗時返回的子設備信息，具體參數請參見下表data。
表 4. data
參數類型說明
deviceNameString子設備的設備名稱。
productKeyString子設備所屬產品的密鑰。

錯誤信息：

錯誤碼錯誤信息描述
460request parameter error請求參數錯誤。
429rate limit, too many subDeviceOnline msg in one minute單個設備認證過于頻繁被限流。
428too many subdevices under gateway網關下同時在線子設備過多。
6401topo relation not exist網關和子設備沒有拓撲關系。
6100device not found子設備不存在。
521device deleted子設備已被刪除。
522device forbidden子設備已被禁用。
6287invalid sign子設備密碼或者簽名錯誤。

子設備批量上線

重要 單次最多可請求50個子設備上線。

數據上行：

  • 請求Topic：/ext/session/${productKey}/${deviceName}/combine/batch_login
  • 響應Topic：/ext/session/${productKey}/${deviceName}/combine/batch_login_reply
說明 因為子設備通過網關通道與物聯網平臺通信，以上Topic為網關設備的Topic。Topic中變量${productKey}和${deviceName}需替換為網關設備的對應信息。

Alink請求數據格式：

{
  "id": "123",
  "params":{ 
     "deviceList":[{
        "productKey": "al12345****", 
        "deviceName": "device1234",
        "clientId": "al12345****&device1234",
        "timestamp": "1581417203000", 
        "cleanSession": "false",
        "signMethod": "hmacmd5",
        "sign": "9B9C732412A4F84B981E1AB97CAB****",
     }, {
        "productKey": "al12345****", 
        "deviceName": "device4321",
        "clientId": "al12345****&device4321",
        "timestamp": "1581417203000", 
        "cleanSession": "true",
        "signMethod": "hmacmd5",
        "sign": "9B9C732412A4F84B981E1AB97CAB****",
     }]
  }
}
說明 消息體中，參數productKey和deviceName的值是子設備的對應信息。
表 5. 請求參數說明
參數類型說明
idString消息ID號。String類型的數字，取值范圍0~4294967295，且每個消息ID在當前設備中具有唯一性。
paramsObject請求入參，其中deviceList參數包含要上線的子設備認證參數列表，包含的具體參數見下表deviceList。
表 6. deviceList
參數類型說明
deviceNameString子設備的設備名稱。
productKeyString子設備所屬的產品的ProductKey。
signString

子設備簽名。簽名方法與直連設備簽名方法相同。

簽名方法：

  1. 將所有提交給服務器的參數（sign，signMethod 和 cleanSession除外）按照字母順序排序，然后將參數和值依次拼接（無拼接符號）。
  2. 對加簽內容，通過signMethod指定的加簽算法，并使用設備的DeviceSecret值，進行簽名計算。

    計算結果作為sign的取值。

sign值計算方法示例如下：

hmac_md5(deviceSecret, clientIdal12345****&device1234deviceNamedevice1234productKeyal12345****timestamp1581417203000)
signMethodString簽名方法，支持hmacSha1、hmacSha256、hmacMd5和Sha256。
timestampString毫秒級時間戳。
clientIdString設備端標識。可以為productKey&deviceName。
cleanSessionString
  • 如果取值是true，則清理所有子設備離線時的消息，即所有未接收的QoS1消息將被清除。
  • 如果取值是false，則不清理子設備離線時的消息。

Alink響應數據格式：

{
  "id":"123",
  "code":"200",
  "message":"success",
  "data":[{
      "productKey": "al12345****",
      "deviceName": "device1234"
    },{
      "deviceName": "device4321",
      "productKey": "al12345****"
    }]
}
表 7. 響應參數說明
參數類型說明
idString消息ID，String類型的數字，取值范圍0~4294967295，且每個消息ID在當前設備中具有唯一性。
codeInteger返回結果，200代表成功。
messageString返回結果信息。
dataObject請求成功或失敗時返回的子設備信息，具體參數請參見下表data。
表 8. data
參數類型說明
deviceNameString子設備的設備名稱。
productKeyString子設備所屬產品的密鑰。

錯誤信息：

錯誤碼錯誤信息描述
460request parameter error請求參數錯誤。
429rate limit, too many subDeviceOnline msg in one minute單個設備認證過于頻繁被限流。
428too many subdevices under gateway網關下同時在線子設備過多。
6401topo relation not exist網關和子設備沒有拓撲關系。
6100device not found子設備不存在。
521device deleted子設備已被刪除。
522device forbidden子設備已被禁用。
6287invalid sign子設備密碼或者簽名錯誤。

子設備下線

數據上行：

  • 請求Topic：/ext/session/${productKey}/${deviceName}/combine/logout
  • 響應Topic：/ext/session/${productKey}/${deviceName}/combine/logout_reply
說明 因為子設備通過網關通道與物聯網平臺通信，以上Topic為網關設備的Topic。Topic中變量${productKey}和${deviceName}需替換為網關設備的對應信息。

Alink請求數據格式：

{
  "id": "123",
  "params": {
    "productKey": "al12345****",
    "deviceName": "device1234"
  }
}
說明 消息體中，參數productKey和deviceName的值是子設備的對應信息。
表 9. 請求參數說明
參數類型說明
idString消息ID號。String類型的數字，取值范圍0~4294967295，且每個消息ID在當前設備中具有唯一性。
paramsObject請求入參，包含要下線的子設備信息。
表 10. params
參數類型說明
deviceNameString子設備的設備名稱。
productKeyString子設備所屬產品的ProductKey。

Alink響應數據格式：

{
  "id": "123",
  "code": 200,
  "message": "success",
  "data": {
      "deviceName": "device1234",
      "productKey": "al12345****"
    }
}
表 11. 響應參數說明
參數類型說明
idString消息ID，String類型的數字，取值范圍0~4294967295，且每個消息ID在當前設備中具有唯一性。
codeInteger返回結果，200代表成功。
messageString返回結果信息。
dataObject請求成功或失敗時，返回的下線的子設備信息。具體參數請參見下表data。
表 12. data
參數類型說明
deviceNameString子設備的設備名稱。
productKeyString子設備所屬產品的ProductKey。

錯誤信息：

錯誤碼錯誤信息描述
460request parameter error請求參數錯誤。
520device no session子設備會話不存在。

子設備批量下線

重要 單次最多可請求50個子設備下線。

數據上行：

  • 請求Topic：/ext/session/${productKey}/${deviceName}/combine/batch_logout
  • 響應Topic：/ext/session/${productKey}/${deviceName}/combine/batch_logout_reply
說明 因為子設備通過網關通道與物聯網平臺通信，以上Topic為網關設備的Topic。Topic中變量${productKey}和${deviceName}需替換為網關設備的對應信息。

Alink請求數據格式：

{
  "id": "123",
  "params":[{
            "productKey": "al12345****",
            "deviceName": "device1234"
          },{
            "productKey": "al12345****",
            "deviceName": "device4321"
      }]
}
說明 消息體中，參數productKey和deviceName的值是子設備的對應信息。
表 13. 請求參數說明
參數類型說明
idString消息ID號。String類型的數字，取值范圍0~4294967295，且每個消息ID在當前設備中具有唯一性。
paramsObject請求入參，包含要下線的子設備信息。
表 14. params
參數類型說明
deviceNameString子設備的設備名稱。
productKeyString子設備所屬產品的ProductKey。

Alink響應數據格式：

{
  "id":"123",
  "code":"200",
  “message":"success",
  "data":[{
      "productKey": "al12345****"
      "deviceName": "device1234"
    },{
      "deviceName": "device4321",
      "productKey": "al12345****"
    }]
}
表 15. 響應參數說明
參數類型說明
idString消息ID，String類型的數字，取值范圍0~4294967295，且每個消息ID在當前設備中具有唯一性。
codeInteger返回結果，200代表成功。
messageString返回結果信息。
dataObject請求成功或失敗時，返回的下線的子設備信息。具體參數請參見下表data。
表 16. data
參數類型說明
deviceNameString子設備的設備名稱。
productKeyString子設備所屬產品的ProductKey。

錯誤信息：

錯誤碼消息描述
460request parameter error請求參數錯誤。
520device no session子設備會話不存在。

相關文檔

子設備接入配置，可參見設備身份注冊。

錯誤碼說明及解決辦法，可參見設備端接收的錯誤碼。