全部产品
Search
文档中心

阿里云物联网平台:添加自定义任务

更新时间:Dec 20, 2023

当批量设置设备属性和服务调用任务无法满足您的业务需求时,您可以添加自定义任务,通过设置自定义规则,实现多场景的设备任务。本文介绍该任务的创建方法、运行中Topic及其数据格式的说明,查看状态的具体操作。

前提条件

已在设备端完成任务部署和管理功能开发。具体操作,请参见Link SDK的设备任务

任务管理流程

  1. 创建自定义任务。
    1. 物联网平台控制台对应实例下的监控运维 > 任务管理页面,单击创建任务
    2. 创建任务页面,单击以下参数名称右侧的帮助图标帮助,根据页面提示,配置任务和作业,单击完成
      • 任务配置
        参数说明
        任务名称输入符合规则的任务名称。可自定义。
        任务类型选择类型:自定义任务
        任务描述输入该任务的用途等信息,便于您区分不同的任务。
        目标设备、产品或分组
        从设备、产品或分组维度选择可执行任务的设备。
        重要 从分组维度选择设备时,不支持选择动态分组。
        下发给设备的任务执行规则上传规则文件。仅支持.json格式文件,文件大小不能超过64 KB。

        您可单击下载模板,获取规则文件模板。内容如下:

        {
            "key":"value"
        }
        • key:标识字段,自定义的String数据。
        • valuekey对应的值,数据格式满足JSON要求即可。

        您需根据模板格式,自定义规则内容。使用示例,请参见设备的自定义任务示例

        文件签名算法支持MD5SHA256

        可选配置,与任务中下发给设备的文件结合使用。

        任务中下发给设备的文件上传自定义任务的文件。

        可选参数,与文件签名算法结合使用。

        支持.bin.apk.tar.gz.zip.gzip.tar.gz格式文件,文件大小不能超过1,000 MB。

        重要 您需根据实际需求,自定义规则和设备文件内容。任务规则和设备文件内容的实现逻辑,需您在设备端完成开发。
      • 作业配置
        参数说明
        作业执行推送配置
        • 每分钟作业执行数量:根据您的业务需要,设置每分钟作业推送数量。
        • 推送消息类型:仅对自定义任务和Pub批量消息推送任务生效。

          可选:

          • QoS0:最多发送一次。
          • QoS1:最少发送一次。如果QoS1消息未接收到PUBACK消息,会在设备重连时,重新推送给设备。
        作业执行的超时配置可选配置。不设置表示不会超时。仅对自定义任务生效。

        从设备任务进入IN_PROGRESS状态,开始计算时间。如果超过了超时时间,任务下作业仍未执行完成,作业状态将被自动设置为TIMED_OUT,作业停止执行。

        作业开始调度时间
        可选配置。

        从当前设置操作的时间,开始计算时间。

        设备任务创建成功后,先初始化,直至到达调度时间,才会开始调度执行。

  2. 任务创建完成后,物联网平台通过Topic:/sys/{productKey}/{deviceName}/thing/job/notify,将任务信息推送给设备。
    消息格式如下:
    {
        "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"
                }
            }
        }
    }

    其中jobDocument下为任务规则文件内容。

    表 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时,该字段值为空。

  3. 设备端根据自定义任务逻辑,实现规则内容。
    如果当前设备处于离线状态,无法接收任务信息,设备上线后,可通过Topic:/sys/{productKey}/{deviceName}/thing/job/get先获取可执行的任务列表,然后获取一个可执行任务信息,来完成任务。

    获取任务列表的消息格式如下:

    {
        "id": "123",
        "version": "1.0",
        "params": {
            "taskId": "$list"
        }
    }

    获取任务信息的消息格式:

    {
        "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个。

    物联网平台收到请求后,通过响应Topic:/sys/{productKey}/{deviceName}/thing/job/get_reply,向设备端返回结果。

    返回任务列表数据格式如下:

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

    返回任务信息数据格式如下:

    {
        "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"
                }
            }
        }
    }
  4. 任务进行过程中,设备端通过Topic:/sys/{productKey}/{deviceName}/thing/job/update,向物联网平台上报任务进度。
    消息格式如下:
    {
        "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

    任务下作业执行进度的百分数。

  5. 在物联网平台对应实例下的监控运维 > 任务管理页面,查看已创建任务及当前状态。
    重要 状态为已超时的任务,不可再被调度执行。

    从任务创建完成开始计时,如果任务下作业未在7天内全部执行完成,任务状态显示为已超时

    您可根据实际场景需要,执行以下操作:

    • 在任务列表中,取消执行中状态的任务。
    • 单击目标任务对应的查看,在任务详情页面,查看任务信息和作业执行统计。
      功能页签说明
      任务信息您可以查看任务信息,修改任务描述和作业配置,下载设备任务文件。
      作业概览您可以查看任务下各状态的作业统计。
      • 您可以单击目标设备的查看,在设备详情页面:
        • 单击任务页签,查看该设备下的所有任务列表。
        • 单击日志服务前往查看,在云端运行日志页签的搜索栏,选择业务类型云到设备消息,查看设备任务相关日志。
      • 如果作业未执行成功,单击执行详情,可查看失败原因。
      • 如果作业执行已超时或失败,单击已超时失败的状态按钮,可查看对应状态的作业列表。

        您可以单击列表上方的重新执行,重新执行当前任务下所有已超时和失败的作业。

    • 单击目标任务对应的删除,然后单击确认
      警告 删除设备任务后,与该任务相关的数据被清除,如果有依赖该任务的业务,可能导致服务不可用或影响用户的业务。请谨慎操作。

操作样例

设备的自定义任务示例