自定义任务更新消息的Topic和Alink数据格式 - 阿里云物联网平台

物联网平台提供设备任务配置和管理服务。设备批量服务调用任务和设备批量属性设置任务，均使用原有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。为全局唯一标识符。