全部產品
Search

搜尋本產品

    IoT Platform：子裝置上下線

    文件中心

    IoT Platform：子裝置上下線

    更新時間：Jun 30, 2024

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

    說明
    • 子裝置上下線、批量上下線訊息，只支援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裝置端標識。可以為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

    Alink響應資料格式：

    {
  "id":"123",
  "code":"200",
  "message":"success",
  "data":[{
      "productKey": "al12345****",
      "deviceName": "device1234"
    },{
      "deviceName": "device4321",
      "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子裝置密碼或者簽名錯誤。

    子裝置下線

    資料上行：

    • 請求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的值是子裝置的對應資訊。
    表 7. 請求參數說明
    參數類型說明
    idString訊息ID號。String類型的數字，取值範圍0~4294967295，且每個訊息ID在當前裝置中具有唯一性。
    paramsObject請求入參，包含要下線的子裝置資訊。
    表 8. params
    參數類型說明
    deviceNameString子裝置的裝置名稱。
    productKeyString子裝置所屬產品的ProductKey。

    Alink響應資料格式：

    {
  "id": "123",
  "code": 200,
  "message": "success",
  "data": {
      "deviceName": "device1234",
      "productKey": "al12345****"
    }
}
    表 9. 響應參數說明
    參數類型說明
    idString訊息ID，String類型的數字，取值範圍0~4294967295，且每個訊息ID在當前裝置中具有唯一性。
    codeInteger返回結果，200代表成功。
    messageString返回結果資訊。
    dataObject請求成功或失敗時，返回的下線的子裝置資訊。具體參數請參見下表data。
    表 10. 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的值是子裝置的對應資訊。
    表 7. 請求參數說明
    參數類型說明
    idString訊息ID號。String類型的數字，取值範圍0~4294967295，且每個訊息ID在當前裝置中具有唯一性。
    paramsObject請求入參，包含要下線的子裝置資訊。
    表 8. params
    參數類型說明
    deviceNameString子裝置的裝置名稱。
    productKeyString子裝置所屬產品的ProductKey。

    Alink響應資料格式：

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

    錯誤資訊：

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

    相關文檔

    子裝置接入配置，可參見裝置身份註冊。

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