自訂任務更新訊息的Topic和Alink資料格式 - IoT Platform

物聯網平台提供裝置任務配置和管理服務。裝置批量服務調用任務和裝置批量屬性設定任務，均使用原有Alink協議通訊。本文介紹自訂任務更新訊息的Topic和Alink資料格式，包括裝置任務狀態更新、裝置請求擷取最新裝置任務資訊和更新任務下作業狀態。

背景資訊

對於自訂任務，需要在裝置端完成任務管理能力開發。具體操作，請參見裝置任務。
對於裝置批量服務調用任務和裝置批量屬性設定任務，若裝置端Link SDK已整合服務調用和屬性設定功能，則無需開發工作單位管理能力，即可實現裝置任務運行。
裝置端Link SDK整合服務調用和屬性設定功能的開發方法，請參見裝置接入概述中對應Link SDK下的物模型開發方法。
服務調用和屬性設定使用的Alink協議說明，請參見裝置屬性、事件、服務。

裝置任務運行流程，請參見裝置任務概述。

裝置任務配置和管理操作，請參見添加自訂任務、添加屬性設定任務、添加服務調用任務。

裝置任務狀態更新通知

說明

僅當裝置任務狀態為執行中、取消和刪除時，向裝置下發通知。

下行。

Topic：/sys/${productKey}/${deviceName}/thing/job/notify。

Alink請求資料格式：

{
    "id": "7542940",
    "version": "1.0",
    "params": {
        "task": {
            "taskId": "i5Ks6***pF010101",
            "status": "SENT",
            "jobDocument": {},
            "jobFile":{
                "signMethod":"Md5",
                "sign":"wssxff56dhdsd***",
                "fileUrl": "https://iotx-***.oss-cn-shanghai.aliyuncs.com/***.zip"
            }
        }
    }
}

表 1. 請求參數說明
參數	類型	說明
id	String	訊息ID號。String類型的數字，取值範圍0~4294967295，且每個訊息ID在當前裝置中具有唯一性。
version	String	協議版本號碼，目前協議版本號碼唯一取值為1.0。
params	Object	請求業務參數。
task	Object	任務下的作業參數。
taskId	String	任務下作業的ID。為通用唯一識別碼。
status	String	任務下作業的狀態。 SENT：已調度。 REMOVED：已刪除。 CANCELLED：已取消。
jobDocument	Object	任務文檔，描述任務執行規則。說明 status為REMOVED或CANCELLED時，該欄位值為空白。
jobFile	Object	建立自訂任務時，上傳的檔案資訊。 signMethod：簽名方法，目前支援`Md5`和`Sha256`。 sign：簽名，根據相應的簽名方法產生的簽名參數。 fileUrl：任務檔案的下載地址，有效期間1小時。說明 status為REMOVED或CANCELLED時，該欄位值為空白。

Alink響應資料格式：

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

表 2. 響應參數說明
參數	類型	說明
id	String	訊息ID號。String類型的數字，取值範圍0~4294967295，且每個訊息ID在當前裝置中具有唯一性。
code	Integer	結果碼。返回200表示成功，返回其他狀態代碼，表示失敗，具體請參見裝置端接收的錯誤碼。
data	Object	裝置端返回的結果資料。裝置任務更新通知返回的結果資料為空白。

擷取裝置任務詳情

上行。

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

Alink請求資料格式：

{
    "id": "123",
    "version": "1.0",
    "params": {
        "taskId": "i5Ks***F010101"
    }
}

表 3. 請求參數說明
參數	類型	說明
id	String	訊息ID號。String類型的數字，取值範圍0~4294967295，且每個訊息ID在當前裝置中具有唯一性。
version	String	協議版本號碼，目前協議版本號碼唯一取值為1.0。
params	Object	請求業務參數。
taskId	String	三種取值方式，可返回不同狀態的任務資訊。任務下作業的ID：返回作業ID對應任務的詳細資料。 `$next`：返回一個可執行任務的資訊。 `$list`：返回可執行檔工作清單，預設最多返回10個。

taskId取值不同，Alink響應資料格式不同。

taskId為任務下作業的ID：

{
    "id": "1234",
    "code": 200,
    "data": {
        "statusDetails":{"devs":"test","status":"init"},
        "taskId": "i5Ks***F010101",
        "task":{
            "taskId": "i5Ks***F010101",
            "status": "IN_PROGRESS",
            "jobDocument": {},
            "jobFile":{
                "signMethod":"Md5",
                "sign":"wssxff56dhdsd***",
                "fileUrl": "https://iotx-***.oss-cn-shanghai.aliyuncs.com/***.zip"
            }
        }
    }
}

taskId為$next：

{
    "id": "1234",
    "code": 200,
    "data": {
        "statusDetails":{"devs":"test","status":"init"},
        "taskId": "$next",
        "task":{
            "taskId": "i5Ks***F010101",
            "status": "IN_PROGRESS",
            "jobDocument": {},
            "jobFile":{
                "signMethod":"Md5",
                "sign":"wssxff56dhdsd***",
                "fileUrl": "https://iotx-***.oss-cn-shanghai.aliyuncs.com/***.zip"
            }
        }
    }
}

taskId為$list：

{
    "id": "1234",
    "code": 200,
    "data": {
        "statusDetails":{"devs":"test","status":"init"},
        "taskId": "$list",
        "task":[
            {
                "taskId": "i5Ks***",
                "status": "IN_PROGRESS"
            },
            {
                "taskId": "i61s***",
                "status": "IN_PROGRESS"
            }
        ]
    }
}

表 4. 響應參數說明
參數	類型	說明
id	String	訊息ID號。String類型的數字，取值範圍0~4294967295，且每個訊息ID在當前裝置中具有唯一性。
code	Integer	結果碼。返回200表示成功，返回其他狀態代碼，表示失敗，具體請參見裝置端接收的錯誤碼。
data	Object	裝置端返回的結果資料。
task	Object	任務下的作業參數。
taskId	String	任務下作業的ID。為通用唯一識別碼。
status	String	任務下作業的狀態。 QUEUED：待調度。 SENT：已調度。 IN_PROGRESS：執行中。 TIMED_OUT：已逾時。 FAILED：失敗。 SUCCEEDED：成功。 CANCELLED：已取消。 REJECTED：已拒絕。
statusDetails	JSON	裝置建立任務時，使用者的自訂配置。
jobDocument	Object	任務文檔，描述任務執行規則。
jobFile	Object	建立自訂任務時，上傳的檔案資訊。 signMethod：簽名方法。目前支援`Md5`和`Sha256`。 sign：簽名，根據相應的簽名方法產生的簽名參數。 fileUrl：任務檔案的下載地址，有效期間1小時。

更新任務下作業狀態

上行

請求Topic：/sys/${productKey}/${deviceName}/thing/job/update。
響應Topic：/sys/${productKey}/${deviceName}/thing/job/update_reply。

Alink請求資料格式：

{
    "id": "123",
    "version": "1.0",
    "params": {
        "taskId": "i5Ks***F010101",
        "status": "IN_PROGRESS",
        "statusDetails": {
            "key": "value"
        },
        "progress": 50
    }
}

表 5. 請求參數說明
參數	類型	說明
id	String	訊息ID號。String類型的數字，取值範圍0~4294967295，且每個訊息ID在當前裝置中具有唯一性。
version	String	協議版本號碼，目前協議版本號碼唯一取值為1.0。
params	Object	請求業務參數。
taskId	String	任務下作業的ID。為通用唯一識別碼。
status	String	任務下作業的狀態。可取值： SUCCEEDED：成功。 FAILED：失敗。 IN_PROGRESS：執行中。 REJECTED：已拒絕。
statusDetails	Object	使用者自訂的狀態詳情，內容可自訂。可在物聯網平台控制台的裝置管理 > 任務 > 任務詳情頁面查看。
progress	Integer	任務下作業執行進度的百分數。

Alink響應資料格式：

{
    "id":"123",
    "code":200,
    "data":{
        "taskId":"i5Ks***F010101"
    }
}

表 6. 響應參數說明
參數	類型	說明
id	String	訊息ID號。String類型的數字，取值範圍0~4294967295，且每個訊息ID在當前裝置中具有唯一性。
code	Integer	結果碼。返回200表示成功，返回其他狀態代碼，表示失敗，具體請參見裝置端接收的錯誤碼。
data	Object	裝置端返回的結果資料。
taskId	String	任務下作業的ID。為通用唯一識別碼。