在多个设备上计划作业

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

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

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

作业生命周期

作业由解决方案后端启动,并由 IoT 中心维护。 可以通过面向服务的 URI ({iot hub}/jobs/v2/{device id}/methods/<jobID>?api-version=2016-11-14) 启动作业,并通过面向服务的 URI ({iot hub}/jobs/v2/<jobId>?api-version=2016-11-14) 查询正在执行的作业的进度。 若要在启动作业后刷新正在运行的作业的状态,请运行作业查询。

Note

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

用于执行直接方法的作业

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

    PUT /jobs/v2/<jobId>?api-version=2016-11-14

    Authorization: <config.sharedAccessSignature>
    Content-Type: application/json; charset=utf-8
    Request-Id: <guid>
    User-Agent: <sdk-name>/<sdk-version>

    {
        jobId: '<jobId>',
        type: 'scheduleDirectRequest', 
        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 中心查询语言。

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

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

    PUT /jobs/v2/<jobId>?api-version=2016-11-14
    Authorization: <config.sharedAccessSignature>
    Content-Type: application/json; charset=utf-8
    Request-Id: <guid>
    User-Agent: <sdk-name>/<sdk-version>

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

查询作业的进度

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

GET /jobs/v2/query?api-version=2016-11-14[&jobType=<jobType>][&jobStatus=<jobStatus>][&pageSize=<pageSize>][&continuationToken=<continuationToken>]

    Authorization: <config.sharedAccessSignature>
    Content-Type: application/json; charset=utf-8
    Request-Id: <guid>
    User-Agent: <sdk-name>/<sdk-version>

从响应提供 continuationToken。

作业属性

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

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

其他参考资料

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

后续步骤

如果要尝试本文中介绍的一些概念,可能对以下 IoT 中心教程感兴趣: