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

前提条件

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

任务管理流程

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

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

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

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

  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. 请求参数说明
    参数类型说明
    idString消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。
    versionString协议版本号，目前协议版本号唯一取值为1.0。
    paramsObject请求业务参数。
    taskObject任务下的作业参数。
    taskIdString任务下作业的ID。为全局唯一标识符。
    statusString任务下作业的状态。
    • SENT：已调度。
    • REMOVED：已删除。
    • CANCELLED：已取消。
    jobDocumentObject 任务文档，描述任务执行规则。
    说明 status为REMOVED或CANCELLED时，该字段值为空。
    jobFileObject 创建自定义任务时，上传的文件信息。
    • signMethod：签名方法，目前支持Md5和Sha256。
    • 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"
    }
}
    表 2. 请求参数说明
    参数类型说明
    idString消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。
    versionString协议版本号，目前协议版本号唯一取值为1.0。
    paramsObject请求业务参数。
    taskIdString三种取值方式，可返回不同状态的任务信息。
    • 任务下作业的ID：返回作业ID对应任务的详细信息。
    • $next：返回一个可执行任务的信息。
    • $list：返回可执行的任务列表，默认最多返回10个。

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

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

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

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

    {
    "id": "1234",
    "code": 200,
    "data": {
        "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
    }
}
    表 3. 请求参数说明
    参数类型说明
    idString消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。
    versionString协议版本号，目前协议版本号唯一取值为1.0。
    paramsObject请求业务参数。
    taskIdString任务下作业的ID。为全局唯一标识符。
    statusString任务下作业的状态。可取值：
    • SUCCEEDED：成功。
    • FAILED：失败。
    • IN_PROGRESS：执行中。
    • REJECTED：已拒绝。
    statusDetailsObject 用户自定义的状态详情，内容可自定义。可在物联网平台控制台的设备管理 > 任务 > 任务详情页面查看。
    progressInteger任务下作业执行进度的百分数。
  5. 在物联网平台对应实例下的监控运维 > 任务管理页面，查看已创建任务及当前状态。
    重要 状态为已超时的任务，不可再被调度执行。

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

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

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

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

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

操作样例

设备的自定义任务示例