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

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

前提条件

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

任务管理流程

创建自定义任务。

在物联网平台控制台对应实例下的监控运维 > 任务管理页面，单击创建任务。

在创建任务页面，单击以下参数名称右侧的帮助图标

，根据页面提示，配置任务和作业，单击完成。

任务配置

参数	说明
任务名称	输入符合规则的任务名称。可自定义。
任务类型	选择类型：自定义任务。
任务描述	输入该任务的用途等信息，便于您区分不同的任务。
目标设备、产品或分组	从设备、产品或分组维度选择可执行任务的设备。重要从分组维度选择设备时，不支持选择动态分组。
下发给设备的任务执行规则	上传规则文件。仅支持`.json`格式文件，文件大小不能超过64 KB。您可单击下载模板，获取规则文件模板。内容如下： `{ "key":"value" }` key：标识字段，自定义的String数据。 value：key对应的值，数据格式满足JSON要求即可。您需根据模板格式，自定义规则内容。使用示例，请参见设备的自定义任务示例。
文件签名算法	支持MD5和SHA256。可选配置，与任务中下发给设备的文件结合使用。
任务中下发给设备的文件	上传自定义任务的文件。可选参数，与文件签名算法结合使用。支持`.bin`、`.apk`、`.tar`、`.gz`、`.zip`、`.gzip`、`.tar.gz`格式文件，文件大小不能超过1,000 MB。

重要您需根据实际需求，自定义规则和设备文件内容。任务规则和设备文件内容的实现逻辑，需您在设备端完成开发。

作业配置

参数	说明
作业执行推送配置	每分钟作业执行数量：根据您的业务需要，设置每分钟作业推送数量。推送消息类型：仅对自定义任务和Pub批量消息推送任务生效。可选： QoS0：最多发送一次。 QoS1：最少发送一次。如果QoS1消息未接收到PUBACK消息，会在设备重连时，重新推送给设备。
作业执行的超时配置	可选配置。不设置表示不会超时。仅对自定义任务生效。从设备任务进入IN_PROGRESS状态，开始计算时间。如果超过了超时时间，任务下作业仍未执行完成，作业状态将被自动设置为TIMED_OUT，作业停止执行。
作业开始调度时间	可选配置。从当前设置操作的时间，开始计算时间。设备任务创建成功后，先初始化，直至到达调度时间，才会开始调度执行。

任务创建完成后，物联网平台通过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：签名方法，目前支持`Md5`和`Sha256`。 sign：签名，根据相应的签名方法生成的签名参数。 fileUrl：任务文件的下载地址，有效期1小时。说明 status为REMOVED或CANCELLED时，该字段值为空。

设备端根据自定义任务逻辑，实现规则内容。

如果当前设备处于离线状态，无法接收任务信息，设备上线后，可通过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"
            }
        }
    }
}

任务进行过程中，设备端通过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	任务下作业执行进度的百分数。

在物联网平台对应实例下的监控运维 > 任务管理页面，查看已创建任务及当前状态。

重要状态为已超时的任务，不可再被调度执行。

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

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

在任务列表中，取消执行中状态的任务。

单击目标任务对应的查看，在任务详情页面，查看任务信息和作业执行统计。

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

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

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

前提条件

任务管理流程

操作样例