在多个设备上调度 Azure IoT 中心任务

Azure IoT 中心支持许多构建基块，例如设备孪生属性、标记和直接方法。通常情况下，后端应用允许设备管理员和操作员在计划的时间批量更新 IoT 设备并与之交互。作业在计划的时间针对一组设备执行设备孪生更新和直接方法。例如，操作员将使用后端应用来启动和跟踪作业，以在建筑物 43 和 3 楼 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），用于指示作业完成时间。只有在作业达到“完成”状态后才有效。
maxExecutionTimeInSeconds	应用程序提供从作业开始到作业完成为止允许的最大总时间。
类型	作业的类型：
	scheduleUpdateTwin：用于更新一组所需属性或标记的作业。
	scheduleDeviceMethod：用于在一组设备孪生上调用设备方法的作业。
status	作业的当前状态。可能的状态值：
	待处理：已计划并等待作业服务获取。
	已计划：已安排在将来的某个时间。
	正在运行：当前活动的作业。
	已取消：作业已取消。
	失败：作业失败。
	完成：作业已完成。
deviceJobStatistics	有关作业执行的统计信息。
	deviceJobStatistics 属性：
	deviceJobStatistics.deviceCount：作业中的设备数。
	deviceJobStatistics.failedCount：作业失败的设备数。
	deviceJobStatistics.succeededCount：作业成功的设备数。
	deviceJobStatistics.runningCount：当前正在运行作业的设备数。
	deviceJobStatistics.pendingCount：等待运行作业的设备数。

其他参考资料

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

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

后续步骤

若要了解本文中所述的一些概念，请参阅以下 IoT 中心文章：

Azure IoT 中心的可靠性

Last updated on 2026-04-24