物联网平台支持设备任务功能,可同时向多个设备发起属性设置、异步服务调用和自定义任务。本文介绍如何管理设备任务。

使用说明

  • 设备批量服务调用任务:仅支持异步服务调用。
  • 自定义任务:
    • 需在设备端完成任务部署和管理功能开发,请参见Link SDK的任务管理
    • 仅支持在自定义任务中,下发设备文件给设备。文件大小不能超过1,000 MB,仅支持.bin.apk.tar.gz.zip.gzip.tar.gz格式文件。

任务管理流程

  1. 创建任务。
    1. 物联网平台控制台,对应实例下的设备管理 > 任务页面,单击创建任务
    2. 创建任务页面,单击参数名称右侧的帮助图标帮助,根据页面提示,配置任务和作业,单击完成
      您可单击下载模板,获取任务类型对应的规则文件模板。文件格式必须为JSON格式。
      • 自定义任务

        您可根据实际需求,自定义规则内容。自定义任务规则的实现逻辑,需您在设备端自行开发。

        {
            "key":"value"
        }
      • 设备批量属性设置任务
        {
            "params": {
                "propertyKey1": "propertyValue1",
                "propertyKey2": "propertyValue2"
            }
        }
        参数 说明
        params 属性设置参数。其下可包含多个属性。
        propertyKey1 属性标识符及对应值。可在物联网平台控制台,设备所属产品的功能定义中查看属性标识符。

        如果是自定义(非默认)模块testFb下属性Switch,则参数为testFb:Switch

        propertyValue1
      • 设备批量服务调用任务
        {
            "serviceIdentifier": "test_service",
            "params": {
                "propertyKey1": "propertyValue1",
                "propertyKey2": "propertyValue2"
            }
        }
        参数 说明
        serviceIdentifier 服务唯一标识符。可在物联网平台控制台中,设备所属产品的功能定义中查看。

        如果是自定义(非默认)模块testFb下服务testService,则参数值为"testFb:testService"

        params 服务的入参,其下可包含多个入参。

      配置作业时,设置以下参数:

      • 超时时间:从设备任务进入IN_PROGRESS状态,开始计算时间。

        如果超过了超时时间,任务下作业仍未执行完成,作业状态将被自动设置为TIMED_OUT,作业停止执行。

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

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

  2. 创建任务完成后,物联网平台根据任务设置和Alink协议数据格式,向设备推送任务信息。具体流程,及Topic和数据格式说明,请参见数据格式说明
  3. 可选:在物联网平台的设备管理 > 任务页面,查看已创建任务及当前状态。

    在任务列表,单击目标任务对应的查看,在任务详情页面,单击以下页签:

    • 任务信息
      • 单击编辑任务信息,可修改任务描述、作业执行速率和超时配置。
      • 单击下载,可获取下发给设备的执行规则文件,或自定义任务文件。
    • 作业概览

      查看任务下各状态的作业统计。您可单击作业对应的操作按钮:

      • 查看:跳转到目标设备的设备详情页面,单击任务页签,查看该设备下的所有任务列表。

        您可在日志服务页签,单击前往查看,在云端运行日志页签下,日志列表的业务类型列选择云到设备消息,查看设备属性和调用服务的日志。

      • 执行详情:如果作业未执行成功,执行详情面板显示失败原因。
    说明
    • 仅状态为执行中的任务,可被取消。
    • 状态为已超时的任务,不可再被调度执行。

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

数据格式说明

自定义任务

  1. 任务创建完成后,物联网平台通过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-***.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:任务文件的下载地址。
    说明 status为REMOVED或CANCELLED时,该字段值为空。
  2. 设备端根据自定义任务逻辑,实现规则内容。
    如果当前设备处于离线状态,无法接收任务信息,设备上线后,可通过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. 请求参数说明
    参数 类型 说明
    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": {
        "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-***.aliyuncs.com/***.zip"
          }
         }
        }
    }
  3. 任务进行过程中,设备端通过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. 请求参数说明
    参数 类型 说明
    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协议更多信息,请参见设备任务的ALink协议说明

设备批量属性设置任务

任务创建完成后,物联网平台通过调用接口SetDevicePropertySetDevicesProperty,下发设置属性指令到设备,然后设备向物联网平台返回响应结果。

消息格式如下:

{
  "id": "123",
  "version": "1.0",
  "params": {
    "temperature": "30.5"
  },
  "method": "thing.service.property.set"
}

其中,params数据是任务规则文件的params数据。

设置设备属性的Alink协议更多信息,请参见设置设备属性

设备批量服务调用任务

任务创建完成后,物联网平台通过InvokeThingServiceInvokeThingsService接口调用服务,采用异步方式下行推送请求,然后设备也采用异步方式向物联网平台返回响应结果。

消息格式如下:

{
  "id": "123",
  "version": "1.0",
  "params": {
    "Power": "on",
    "WF": "2"
  },
  "method": "thing.service.{tsl.service.identifier}"
}

其中,params数据是任务规则文件中params数据;{tsl.service.identifier}是任务规则文件中serviceIdentifier的值。

设备服务异步调用的Alink协议更多信息,请参见设备服务调用(异步调用)