在多個裝置上排程 Azure IoT 中樞作業

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>
}

查詢條件也可以位於單一裝置識別碼或裝置識別碼清單上，如下列範例所示：

"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。
開始時間	應用程式提供工作的開始時間（ISO-8601）。
結束時間	IoT 中樞提供的作業完成日期（ISO-8601）。只有在工作達到「已完成」狀態之後才有效。
maxExecutionTimeIn秒	應用程式提供從工作開始到完成的允許總時間上限。
type	工作類型：
	scheduleUpdateTwin：用來更新一組所需屬性或標籤的作業。
	scheduleDeviceMethod：用來在一組裝置對應項上叫用裝置方法的作業。
狀態	工作的當前狀態。狀態的可能值：
	pending：已排程並等待工作服務接走。
	scheduled：排定在未來的某個時間。
	running：目前作用中的工作。
	canceled：工作已取消。
	failed：工作失敗。
	completed：工作已完成。
裝置工作統計資料	有關任務執行的統計資料。
	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 中樞教學課程：

排程和廣播工作

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-08-26