物联网平台提供设备任务配置和管理服务。设备批量服务调用任务和设备批量属性设置任务,均使用原有Alink协议通信,本文介绍自定义任务更新消息的Topic和Alink数据格式,包括设备任务状态更新、设备请求获取最新设备任务信息和更新任务下作业状态。

背景信息

  • 对于自定义任务,需要在设备端完成任务管理能力开发。具体操作,请参见任务管理
  • 对于设备批量服务调用任务和设备批量属性设置任务,若设备端Link SDK已集成服务调用和属性设置功能,则无需开发任务管理能力,即可实现设备任务运行。

    设备端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-***.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:任务文件的下载地址。
说明 status为REMOVED或CANCELLED时,该字段值为空。

Alink响应数据格式:

{
    "id": "7542940",
    "code":200,
    "data" : {}
}
表 2. 响应参数说明
参数 类型 说明
id String 消息ID号。String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。
code Integer 结果码。返回200表示成功,返回其他状态码,表示失败,具体请参见设备端通用code
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": {
        "taskId": "i5Ks***F010101",
        "task":{
              "taskId": "i5Ks***F010101",
              "status": "IN_PROGRESS",
              "jobDocument": {
           },
             "jobFile":{
                  "signMethod":"Md5",
                  "sign":"wssxff56dhdsd***",
                  "fileUrl": "https://iotx-***.aliyuncs.com/***.zip"
          }
         }
        }
    }
  • taskId$next
    {
      "id": "1234",
      "code": 200,
      "data": {
        "taskId": "$next",
        "task":{
              "taskId": "i5Ks***F010101",
              "status": "IN_PROGRESS",
              "jobDocument": {
           },
             "jobFile":{
                  "signMethod":"Md5",
                  "sign":"wssxff56dhdsd***",
                  "fileUrl": "https://iotx-***.aliyuncs.com/***.zip"
          }
         }
        }
    }
  • taskId$list
    {
      "id": "1234",
      "code": 200,
      "data": {
        "taskId": "$list",
        "task":[
              {
              "taskId": "i5Ks***",
              "status": "IN_PROGRESS"
              },
              {
              "taskId": "i61s***",
              "status": "IN_PROGRESS"
              }
            ]
        }
    }
表 4. 响应参数说明
参数 类型 说明
id String 消息ID号。String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。
code Integer 结果码。返回200表示成功,返回其他状态码,表示失败,具体请参见设备端通用code
data Object 设备端返回的结果数据。
task Object 任务下的作业参数。
taskId String 任务下作业的ID。为全局唯一标识符。
status String 任务下作业的状态。
  • QUEUED:待调度
  • SENT:已调度
  • IN_PROGRESS:执行中
  • TIMED_OUT:已超时
  • FAILED:失败
  • SUCCEEDED:成功
  • CANCELLED:已取消
  • REJECTED:已拒绝
jobDocument Object 任务文档,描述任务执行规则。
jobFile Object 创建自定义任务时,上传的文件信息。
  • signMethod:签名方法。目前支持Md5Sha256
  • sign:签名,根据相应的签名方法生成的签名参数。
  • fileUrl:任务文件的下载地址。

更新任务下作业状态

上行

  • 请求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表示成功,返回其他状态码,表示失败,具体请参见设备端通用code
data Object 设备端返回的结果数据。
taskId String 任务下作业的ID。为全局唯一标识符。