在多个设备上计划作业

项目
06/05/2023

Azure IoT 中心可启用多个构建基块（如设备孪生属性和标记和直接方法）。通常情况下，后端应用允许设备管理员和操作员在计划的时间批量更新 IoT 设备并与之交互。作业在计划的时间针对一组设备执行设备孪生更新和直接方法。例如，操作员可使用用于启动和跟踪作业的后端应用在不会中断大楼运作的时间重新启动 43 号大楼第 3 层中的一组设备。

注意

本文所述的功能只能用于 IoT 中心的标准层。有关 IoT 中心基本层和标准/免费层的详细信息，请参阅选择适合你的解决方案的 IoT 中心层。

在以下情况下请考虑使用作业：需要计划并跟踪一组设备上的以下任何活动的进度：

更新所需属性
更新标记
调用直接方法

作业生命周期

作业由解决方案后端启动，并由 IoT 中心维护。可以通过面向服务的 URI (PUT https://<iot hub>/jobs/v2/<jobID>?api-version=2021-04-12) 启动作业，并通过面向服务的 URI (GET https://<iot hub>/jobs/v2/<jobID?api-version=2021-04-12) 查询正在执行的作业的进度。若要在启动作业后刷新正在运行的作业的状态，请运行作业查询。没有显示清除作业历史记录，但它们的 TTL 为 30 天。

注意

启动作业时，属性名称和值只能包含 US-ASCII 可打印字母数字，但下列组中的任一项除外：$ ( ) < > @ , ; : \ " / [ ] ? = { } SP HT

注意

jobId 字段的长度不得超过 64 个字符，并且只能包含 US-ASCII 字母、数字和短划线 (-) 字符。

用于执行直接方法的作业

以下代码片段显示了使用作业在一组设备上执行直接方法的 HTTPS 1.1 请求详细信息：

PUT /jobs/v2/<jobId>?api-version=2021-04-12

Authorization: <config.sharedAccessSignature>
Content-Type: application/json; charset=utf-8

{
    "jobId": "<jobId>",
    "type": "scheduleDeviceMethod",
    "cloudToDeviceMethod": {
        "methodName": "<methodName>",
        "payload": <payload>,
        "responseTimeoutInSeconds": methodTimeoutInSeconds
    },
    "queryCondition": "<queryOrDevices>", // query condition
    "startTime": <jobStartTime>,          // as an ISO-8601 date string
    "maxExecutionTimeInSeconds": <maxExecutionTimeInSeconds>
}

查询条件也可以位于单个设备 ID 上或位于设备 ID 列表中，如以下示例所示：

"queryCondition" = "deviceId = 'MyDevice1'"
"queryCondition" = "deviceId IN ['MyDevice1','MyDevice2']"
"queryCondition" = "deviceId IN ['MyDevice1']"

IoT 中心查询语言格外详细地介绍了 IoT 中心查询语言。

以下代码片段演示了特定作业的请求和响应，该作业计划在 contoso-hub-1 的所有设备上调用名为 testMethod 的直接方法：

PUT https://contoso-hub-1.azure-devices.cn/jobs/v2/job01?api-version=2021-04-12 HTTP/1.1
Authorization: SharedAccessSignature sr=contoso-hub-1.azure-devices.cn&sig=68iv------------------------------------v8Hxalg%3D&se=1556849884&skn=iothubowner
Content-Type: application/json; charset=utf-8
Host: contoso-hub-1.azure-devices.cn
Content-Length: 317

{
    "jobId": "job01",
    "type": "scheduleDeviceMethod",
    "cloudToDeviceMethod": {
        "methodName": "testMethod",
        "payload": {},
        "responseTimeoutInSeconds": 30
    },
    "queryCondition": "*",
    "startTime": "2019-05-04T15:53:00.077Z",
    "maxExecutionTimeInSeconds": 20
}

HTTP/1.1 200 OK
Content-Length: 65
Content-Type: application/json; charset=utf-8
Vary: Origin
Server: Microsoft-HTTPAPI/2.0
Date: Fri, 03 May 2019 01:46:18 GMT

{"jobId":"job01","type":"scheduleDeviceMethod","status":"queued"}

用于更新设备孪生属性的作业

以下代码片段显示了使用作业更新设备克隆属性的 HTTPS 1.1 请求详细信息：

PUT /jobs/v2/<jobId>?api-version=2021-04-12

Authorization: <config.sharedAccessSignature>
Content-Type: application/json; charset=utf-8

{
    "jobId": "<jobId>",
    "type": "scheduleUpdateTwin",
    "updateTwin": <patch>                 // Valid JSON object
    "queryCondition": "<queryOrDevices>", // query condition
    "startTime": <jobStartTime>,          // as an ISO-8601 date string
    "maxExecutionTimeInSeconds": <maxExecutionTimeInSeconds>
}

注意

updateTwin 属性要求有效的 etag 匹配，例如 etag="*"。

以下代码片段演示了特定作业的请求和响应，该作业计划在 contoso-hub-1 上更新 test-device 的设备孪生属性：

PUT https://contoso-hub-1.azure-devices.cn/jobs/v2/job02?api-version=2021-04-12 HTTP/1.1
Authorization: SharedAccessSignature sr=contoso-hub-1.azure-devices.cn&sig=BN0U-------------------------------------RuA%3D&se=1556925787&skn=iothubowner
Content-Type: application/json; charset=utf-8
Host: contoso-hub-1.azure-devices.cn
Content-Length: 339

{
    "jobId": "job02",
    "type": "scheduleUpdateTwin",
    "updateTwin": {
      "properties": {
        "desired": {
          "test1": "value1"
        }
      },
     "etag": "*"
     },
    "queryCondition": "deviceId = 'test-device'",
    "startTime": "2019-05-08T12:19:56.868Z",
    "maxExecutionTimeInSeconds": 20
}

HTTP/1.1 200 OK
Content-Length: 63
Content-Type: application/json; charset=utf-8
Vary: Origin
Server: Microsoft-HTTPAPI/2.0
Date: Fri, 03 May 2019 22:45:13 GMT

{"jobId":"job02","type":"scheduleUpdateTwin","status":"queued"}

查询作业的进度

以下代码片段显示了用于查询作业的 HTTPS 1.1 请求详细信息：

GET /jobs/v2/query?api-version=2021-04-12[&jobType=<jobType>][&jobStatus=<jobStatus>][&pageSize=<pageSize>][&continuationToken=<continuationToken>]

Authorization: <config.sharedAccessSignature>
Content-Type: application/json; charset=utf-8

从响应提供 continuationToken。

可以使用设备孪生、作业和消息路由的 IoT 中心查询语言在每台设备上查询作业执行状态。

作业属性

以下列表显示了属性和相应说明，在查询作业或作业结果时可使用这些属性。

属性	说明
jobId	应用程序提供的作业 ID。
startTime	应用程序提供的作业开始时间(ISO-8601)。
endTime	IoT 中心提供的作业完成时的日期(ISO-8601)。只有在作业达到“完成”状态后才有效。
type	作业的类型：
	scheduleUpdateTwin：用于更新一组所需属性或标记的作业。
	scheduleDeviceMethod：用于对一组设备孪生调用设备方法的作业。
status	作业的当前状态。可能的状态值：
	挂起：已计划并等待作业服务选取。
	已计划：计划将来的某个时间。
	正在运行：当前活动的作业。
	已取消：作业已取消。
	失败：作业失败。
	完成：作业已完成。
deviceJobStatistics	有关作业执行的统计信息。
	deviceJobStatistics 属性：
	deviceJobStatistics.deviceCount：作业中的设备数。
	deviceJobStatistics.failedCount：作业失败的设备数。
	deviceJobStatistics.succeededCount：作业成功的设备数。
	deviceJobStatistics.runningCount：当前正在运行作业的设备数。
	deviceJobStatistics.pendingCount：等待运行作业的设备数。

其他参考资料

IoT 中心开发人员指南中的其他参考主题包括：

IoT 中心终结点介绍了每个 IoT 中心针对运行时和管理操作公开的各种终结点。
限制和配额介绍了适用于 IoT 中心服务的配额，以及使用服务时预期会碰到的限制行为。
Azure IoT 设备和服务 SDK 列出了开发与 IoT 中心交互的设备和服务应用时可使用的各种语言 SDK。
设备孪生、作业和消息路由的 IoT 中心查询语言介绍 IoT 中心查询语言。使用此查询语言从 IoT 中心检索设备孪生和作业的相关信息。
IoT 中心 MQTT 支持提供了有关 IoT 中心对 MQTT 协议的支持的详细信息。

后续步骤

要尝试本文中介绍的一些概念，请参阅以下 IoT 中心教程：

计划和广播作业

通过