你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

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

2025-08-28

Azure IoT 中心支持许多构建基块，例如设备孪生属性、标记和直接方法。通常，后端应用使设备管理员和操作员能够批量更新 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.net/jobs/v2/job01?api-version=2021-04-12 HTTP/1.1
Authorization: SharedAccessSignature sr=contoso-hub-1.azure-devices.net&sig=68iv------------------------------------v8Hxalg%3D&se=1556849884&skn=iothubowner
Content-Type: application/json; charset=utf-8
Host: contoso-hub-1.azure-devices.net
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.net/jobs/v2/job02?api-version=2021-04-12 HTTP/1.1
Authorization: SharedAccessSignature sr=contoso-hub-1.azure-devices.net&sig=BN0U-------------------------------------RuA%3D&se=1556925787&skn=iothubowner
Content-Type: application/json; charset=utf-8
Host: contoso-hub-1.azure-devices.net
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 中心查询语言来查询设备孪生、作业和消息路由的每个设备上的作业执行状态。

作业属性

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

资产	Description
jobId	应用程序提供的作业 ID。
startTime	应用程序为作业提供了开始时间（ISO-8601）。
endTime	IoT 中心提供了作业完成时的日期（ISO-8601）。仅在作业达到“已完成”状态后有效。
maxExecutionTimeInSeconds	应用程序提供从作业开始到作业完成为止允许的最大总时间。
类型	作业类型：
	scheduleUpdateTwin：用于更新一组所需属性或标记的作业。
	scheduleDeviceMethod：用于对一组设备孪生调用设备方法的作业。
地位	作业的当前状态。状态的可能值：
	挂起：已计划并等待作业服务选取。
	scheduled：已安排在将来的某个时间。
	正在运行：当前活动的作业。
	已取消：作业已取消。
	失败：作业失败。
	已完成：作业已完成。
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 支持提供有关 MQTT 协议的 IoT 中心支持的详细信息。

后续步骤

若要试用本文中所述的一些概念，请参阅以下 IoT 中心教程：

调度和发布任务

反馈

此页面是否有帮助？