全部產品
Search

搜尋本產品

    IoT Platform：管理拓撲關係

    文件中心

    IoT Platform：管理拓撲關係

    更新時間：Jun 30, 2024

    子裝置身份註冊後，需由網關向物聯網平台上報網關與子裝置的拓撲關係，然後進行子裝置上線。

    子裝置上線過程中，物聯網平台會校正子裝置的身份和與網關的拓撲關係。所有校正通過，才會建立並綁定子裝置邏輯通道至網關物理通道上。子裝置與物聯網平台的資料上下行通訊與直連裝置的通訊協定一致，協議上不需要露出網關資訊。

    刪除拓撲關係後，子裝置不能再通過網關上線。系統將提示拓撲關係不存在，認證不通過等錯誤。

    添加裝置拓撲關係

    網關類型的裝置，可以通過該Topic上行請求添加它和子裝置之間的拓撲關係，返回成功添加拓撲關係的子裝置。

    重要 單次最多可請求添加30個子裝置。

    資料上行。

    • 請求Topic：/sys/${productKey}/${deviceName}/thing/topo/add
    • 響應Topic：/sys/${productKey}/${deviceName}/thing/topo/add_reply

    Alink請求資料格式：

    {
  "id": "123",
  "version": "1.0",
  "sys":{
      "ack":0
  },
  "params": [
    {
      "deviceName": "deviceName1234",
      "productKey": "1234556554",
      "sign": "xxxxxx",
      "signmethod": "hmacSha1",
      "timestamp": "1524448722000",
      "clientId": "xxxxxx"
    }
  ],
  "method": "thing.topo.add"
}

    Alink響應資料格式：

    {
  "id": "123",
  "code": 200,
  "data": [
    {
      "deviceName": "deviceName1234",
      "productKey": "1234556554"
    }
  ]
}

    請求參數說明：

    參數類型說明
    idString訊息ID號。需定義為String類型的數字，取值範圍0~4294967295，且每個訊息ID在當前裝置中具有唯一性。
    versionString協議版本號碼，目前協議版本號碼唯一取值為1.0。

    sys

    Object

    擴充功能的參數，其下包含各功能欄位。

    說明

    使用裝置端SDK開發時，如果未設定擴充功能，則無此參數，相關功能保持預設配置。

    ack

    Integer

    sys下的擴充功能欄位，表示是否返迴響應資料。

    • 1：雲端返迴響應資料。

    • 0：雲端不返迴響應資料。

    重要

    該功能配置說明，請參見物模型使用樣本。

    如果未配置該功能，則無此參數，雲端預設返迴響應資料。

    paramsList請求入參。
    deviceNameString子裝置的名稱。
    productKeyString子裝置所屬產品的ProductKey。
    signString

    簽名。

    加簽演算法：

    1. 將所有提交給伺服器的參數（sign，signMethod除外）按照字母順序排序，然後將參數和值依次拼接（無拼接符號）。
    2. 對加簽內容，需通過signMethod指定的加簽演算法，使用裝置的DeviceSecret值，進行簽名計算。
    簽名計算樣本： 
    sign= hmac_md5(deviceSecret, clientId123deviceNametestproductKey123timestamp1524448722000)
    signmethodString簽名方法，支援hmacSha1、hmacSha256、hmacMd5、Sha256。
    timestampString時間戳記（單位：毫秒）。
    clientIdString裝置本地標記，非必填。可以設定為具體的productKey&deviceName。
    methodString要求方法，取值thing.topo.add。

    響應參數說明：

    參數類型說明
    idString訊息ID，String類型的數字，取值範圍0~4294967295，且每個訊息ID在當前裝置中具有唯一性。
    codeInteger返回結果，200代表成功。
    dataObject請求成功時返回的子裝置資訊，具體參數請參見下表data。
    表 1. data
    參數類型說明
    deviceNameString子裝置的裝置名稱。
    productKeyString子裝置所屬產品的ProductKey。

    錯誤資訊：

    錯誤碼訊息描述
    460request parameter error請求參數錯誤。
    6402topo relation cannot add by self裝置不能把自己添加為自己的子裝置。
    401request auth error簽名校正授權失敗。

    刪除裝置的拓撲關係

    網關類型的裝置，可以通過該Topic上行請求刪除它和子裝置之間的拓撲關係，返回成功刪除拓撲關係的子裝置。

    重要 單次最多可請求刪除30個子裝置。

    資料上行。

    • 請求Topic：/sys/${productKey}/${deviceName}/thing/topo/delete
    • 響應Topic：/sys/${productKey}/${deviceName}/thing/topo/delete_reply

    Alink請求資料格式：

    {
  "id": "123",
  "version": "1.0",
  "sys":{
      "ack":0
  },
  "params": [
    {
      "deviceName": "deviceName1234",
      "productKey": "1234556554"
    }
  ],
  "method": "thing.topo.delete"
}

    Alink響應資料格式：

    {
  "id": "123",
  "code": 200,
  "data": [
    {
      "deviceName": "deviceName1234",
      "productKey": "1234556554"
    }
  ]
}

    請求參數說明：

    參數類型說明
    idString訊息ID號。需定義為String類型的數字，取值範圍0~4294967295，且每個訊息ID在當前裝置中具有唯一性。
    versionString協議版本號碼，目前協議版本號碼唯一取值為1.0。

    sys

    Object

    擴充功能的參數，其下包含各功能欄位。

    說明

    使用裝置端SDK開發時，如果未設定擴充功能，則無此參數，相關功能保持預設配置。

    ack

    Integer

    sys下的擴充功能欄位，表示是否返迴響應資料。

    • 1：雲端返迴響應資料。

    • 0：雲端不返迴響應資料。

    重要

    該功能配置說明，請參見物模型使用樣本。

    如果未配置該功能，則無此參數，雲端預設返迴響應資料。

    paramsList請求參數。
    deviceNameString子裝置名稱。
    productKeyString子裝置所屬產品的ProductKey
    methodString要求方法。取值thing.topo.delete。

    響應參數說明：

    參數類型說明
    idString訊息ID，String類型的數字，取值範圍0~4294967295，且每個訊息ID在當前裝置中具有唯一性。
    codeInteger返回結果，200代表成功。
    dataObject請求成功時返回的子裝置資訊，具體參數請參見下表data。
    表 2. data
    參數類型說明
    deviceNameString子裝置的裝置名稱。
    productKeyString子裝置所屬產品的ProductKey。

    錯誤資訊：

    錯誤碼訊息描述
    460request parameter error請求參數錯誤。
    6100device not found裝置不存在。

    擷取裝置的拓撲關係

    資料上行。

    • 請求Topic：/sys/${productKey}/${deviceName}/thing/topo/get
    • 響應Topic：/sys/${productKey}/${deviceName}/thing/topo/get_reply

    網關類型的裝置，可以通過該Topic擷取該裝置和子裝置的拓撲關係。

    Alink請求資料格式：

    {
  "id": "123",
  "version": "1.0",
  "sys":{
      "ack":0
  },
  "params": {},
  "method": "thing.topo.get"
}

    Alink響應資料格式：

    {
  "id": "123",
  "code": 200,
  "data": [
    {
      "deviceName": "deviceName1234",
      "productKey": "1234556554"
    }
  ]
}

    請求參數說明：

    參數類型說明
    idString訊息ID號。需定義為String類型的數字，取值範圍0~4294967295，且每個訊息ID在當前裝置中具有唯一性。
    versionString協議版本號碼，目前協議版本號碼唯一取值為1.0。

    sys

    Object

    擴充功能的參數，其下包含各功能欄位。

    說明

    使用裝置端SDK開發時，如果未設定擴充功能，則無此參數，相關功能保持預設配置。

    ack

    Integer

    sys下的擴充功能欄位，表示是否返迴響應資料。

    • 1：雲端返迴響應資料。

    • 0：雲端不返迴響應資料。

    重要

    該功能配置說明，請參見物模型使用樣本。

    如果未配置該功能，則無此參數，雲端預設返迴響應資料。

    paramsObject請求參數，可為空白。
    methodString要求方法，取值thing.topo.get。

    響應參數說明：

    參數類型說明
    idString訊息ID，String類型的數字，取值範圍0~4294967295，且每個訊息ID在當前裝置中具有唯一性。
    codeInteger返回結果，200代表成功。
    dataObject請求成功時的返回結果。
    deviceNameString子裝置的名稱。
    productKeyString子裝置所屬產品的ProductKey。

    錯誤資訊：

    錯誤碼訊息描述
    460request parameter error請求參數錯誤。

    發現裝置列表上報

    資料上行。

    • 請求Topic：/sys/${productKey}/${deviceName}/thing/list/found
    • 響應Topic：/sys/${productKey}/${deviceName}/thing/list/found_reply

    在一些情境下，網關可以發現新接入的子裝置。發現後，需將新接入子裝置的資訊上報雲端，然後通過資料流轉到第三方應用，選擇將哪些子裝置接入該網關。

    Alink請求資料格式：

    {
  "id": "123",
  "version": "1.0",
  "sys":{
      "ack":0
  },
  "params": [
    {
      "deviceName": "deviceName1234",
      "productKey": "1234556554"
    }
  ],
  "method": "thing.list.found"
}

    Alink響應資料格式：

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

    請求參數說明：

    參數類型說明
    idString訊息ID號。需定義為String類型的數字，取值範圍0~4294967295，且每個訊息ID在當前裝置中具有唯一性。
    versionString協議版本號碼，目前協議版本號碼唯一取值為1.0。

    sys

    Object

    擴充功能的參數，其下包含各功能欄位。

    說明

    使用裝置端SDK開發時，如果未設定擴充功能，則無此參數，相關功能保持預設配置。

    ack

    Integer

    sys下的擴充功能欄位，表示是否返迴響應資料。

    • 1：雲端返迴響應資料。

    • 0：雲端不返迴響應資料。

    重要

    該功能配置說明，請參見物模型使用樣本。

    如果未配置該功能，則無此參數，雲端預設返迴響應資料。

    paramsObject請求參數，可為空白。
    methodString要求方法，取值thing.list.found。
    deviceNameString子裝置的名稱。
    productKeyString子裝置所屬產品的ProductKey。

    響應參數說明：

    參數類型說明
    idString訊息ID，String類型的數字，取值範圍0~4294967295，且每個訊息ID在當前裝置中具有唯一性。
    codeInteger返回結果，200代表成功。
    dataObject請求成功時的返回結果。

    錯誤資訊：

    錯誤碼訊息描述
    460request parameter error請求參數錯誤。
    6250product not found上報的子裝置產品不存在。
    6280devicename not meet specs上報的子裝置的名稱不符規範。

    通知網關添加裝置拓撲關係

    資料下行。

    • 請求Topic：/sys/${productKey}/${deviceName}/thing/topo/add/notify
    • 響應Topic：/sys/${productKey}/${deviceName}/thing/topo/add/notify_reply

    通知網關裝置對子裝置發起添加拓撲關係，可以配合發現裝置列表上報功能使用。可以通過資料流轉擷取裝置返回的結果，資料流轉Topic為/${productKey}/${deviceName}/thing/downlink/reply/message。

    Alink請求資料格式：

    {
  "id": "123",
  "version": "1.0",
  "params": [
    {
      "deviceName": "deviceName1234",
      "productKey": "1234556554"
    }
  ],
  "method": "thing.topo.add.notify"
}

    Alink響應資料格式：

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

    請求參數說明：

    參數類型說明
    idString

    資料下行訊息ID號，由物聯網平台產生，取值範圍0~4294967295，且每個訊息ID在當前裝置中具有唯一性。

    versionString協議版本號碼，目前協議版本號碼唯一取值為1.0。
    paramsObject請求參數，可為空白。
    methodString要求方法，取值thing.topo.add.notify。
    deviceNameString子裝置的名稱。
    productKeyString子裝置所屬產品的ProductKey。

    響應參數說明：

    參數類型說明
    idString訊息ID，String類型的數字，取值範圍0~4294967295，且每個訊息ID在當前裝置中具有唯一性。
    codeInteger返回結果，200代表成功。
    dataObject請求成功時的返回結果。

    通知網關拓撲關係變化

    將拓撲關係變化通知網關。

    網關訂閱Topic：/sys/${productKey}/${deviceName}/thing/topo/change

    操作行為通知方式
    網關下添加子裝置添加網關與子裝置的拓撲關係。通知網關。
    刪除子裝置刪除子裝置與對應網關的拓撲關係。
    禁用子裝置禁用子裝置，並禁用當前子裝置與對應網關的拓撲關係。
    啟用子裝置解除子裝置禁用，恢複當前子裝置和對應網關的拓撲關係。

    下行訊息Alink資料格式：

    {
    "id":"123",
    "version":"1.0",
    "params":{
        "status":0,  //0-建立  1-刪除 2-恢複禁用  8-禁用
        "subList":[{
            "productKey":"a1hRrzD****",
            "deviceName":"abcd"
        }]
    }, 
  "method":"thing.topo.change"  
}

    參數說明：

    參數類型說明
    idString

    資料下行訊息ID號，由物聯網平台產生，取值範圍0~4294967295，且每個訊息ID在當前裝置中具有唯一性。

    versionString協議版本號碼，目前協議版本號碼唯一取值為1.0。
    methodString要求方法，取值thing.topo.change。
    paramsObject請求參數，包含參數status（拓撲關係狀態）和sublist（子裝置列表）。
    statusInteger拓撲關係狀態。
    • 0：建立
    • 1：刪除
    • 2：解除禁用（啟用）
    • 8：禁用
    deviceNameString子裝置的名稱。
    productKeyString子裝置所屬產品的Key。

    Alink響應資料格式：

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