開發指南

在使用推送服務時，OneNET作為用戶端，而用戶的第三方應用是作為伺服器，第三方應用需要支援URL驗證以及數據接收兩部分服務。

URL驗證

URL驗證流程如下圖所示：

用戶在配置頁面完成配置並點擊“提交”時，OneNET平台會向填寫URL地址發送

HTTP GET請求進行URL驗證，請求形式示例如下：

http://url?msg=xxx&nonce=xxx&signature=xxx

其中，ur/為用戶在頁面配置時填寫的URL，nonce、msg、signature用於URL及token的驗證

token驗證過程如下：

1. 將配置頁面中配置的token與nonce、msg的值計算MD5，並且編碼為Base64字串值

2. 將上一步中Base64字串值通過URL Decode計算後的值與請求參數signature的值進行對比，如果相等則表示token驗證成功

如果token驗證成功，返回msg參數值，表示URL驗證通過。

如果用戶不想驗證token，可以選擇跳過MD5計算過程，直接返回msg參數值

數據接收

平台以HTTP POST請求形式向第三方平台URL地址推送數據，第三方平台接收到數據後需要返回 HTTP 200，否則OneNET會認為此次推送無效並重試

推送數據相關信息以JSON串的形式置於HTTP請求中的body部分，其中各個欄位的含義如下

示例1：數據點消息

{
    "msg": {
        "type": 1,
        "dev_id": 2016617,
        "ds_id": "datastream_id",
        "at": 1466133706841,
        "value": 42
    },
    "msg_signature": "message signature",
    "nonce": "abcdefgh"
}

示例2：批量數據點消息（需要配置數據緩存）

{
    "msg": [{
            "type": 1,
            "dev_id": 2016617,
            "ds_id": "datastream_id",
            "at": 1466133706841,
            "value": 42
        },
        {
            "type": 1,
            "dev_id": 2016617,
            "ds_id": "datastream_id",
            "at": 1466133706842,
            "value": 43
        },
        ...
    ],
    "msg_signature": "message signature ",
    "nonce": "abcdefgh"
}

示例3：設備上下線消息

{
    "msg": {
        "type": 2,
        "dev_id": 2016617,
        "status": 0,
        "login_type": 1,
        "at": 1466133706841
    },
    "msg_signature": "message signature",
    "nonce": "abcdefgh"
}

示例4：緩存命令下發後結果上報（僅支援NB設備）

{
    "msg": {
        "type": 7,
        "cmd_id": "3a351323-c4fe-5f21-9e9e-a9adc321182f",
        "imei": "865820060031939",
        "dev_id": 2016690,
        "cmd_type": 0,
        "send_time": 1466133706841,
        "send_status": 5,
        "confirm_time": 146613371921,
        "confirm_status": 0,
        "confirm_body": {
            "obj_id": 3,
            "obj_inst": [{
                "obj_inst_id": 0,
                "res": [{
                        "res_inst": [{
                            "val": 0,
                            "res_inst_id": 0
                        }],
                        "res_id": 11
                    },
                    {
                        "val": 1530496927000,
                        "res_id": 13
                    }
                ]
            }]
        }
    },
    "msg_signature": "message signature",
    "nonce": "abcdefgh"
}

說明：

1. 當回應結果包含二進位數據時，是將二進位數據byte[] 轉換成 ASCII碼的陣列存在JSON數據中，如: [98，105，110，97，114，121]
2. 當命令類型為READ時，confirm_body欄位會攜帶上命令請求時候的object id以及object instance id，方便用戶解析數據。

加密傳輸

用戶在配置推送服務時，可配置為數據加密傳輸，OneNET支援AES對稱加密，用戶可通過頁面配置金鑰，並在應用端通過該金鑰進行解密操作

示例：密文格式

{
    "enc_msg": "XXXXXXXXXXX",
    "msg_signature": "message signature",
    "nonce": "abcdefgh"
}

服務實現建議

• OneNET平台為了保證數據不丟失，有重發機制，如果重復數據對業務有影響，數據接收端需要對重復數據進行排除重複處理
• OneNET每一次POST數據請求後，等待用戶端的響應都設有時限（目前是5秒），在規定時限內沒有收到回應會認為發送失敗，累計失敗2000次則會認為第三方服務不可用，服務將停止，所以建議第三方應用接收程式接收到數據時，先做數據緩存，再做業務邏輯處理
• 為保證你在使用OneNET平台的數據推送服務時，能夠體驗連續、穩定的服務，請將下述OneNET平台數據推送的出口IP地址添加至你應用的IP白名單中.