全部产品
Search
文档中心

阿里云物联网平台:设备任务

更新时间:Dec 27, 2023

物联网平台提供设备任务配置和管理服务。设备批量服务调用任务和设备批量属性设置任务,均使用原有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:签名方法,目前支持Md5Sha256

  • 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:签名方法。目前支持Md5Sha256

  • 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。为全局唯一标识符。