排程多個裝置上的作業

「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 上的測試裝置更新裝置對應項屬性之作業的要求和回應:

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 中樞查詢語言,查詢每個裝置上的作業執行狀態。

作業屬性

以下清單顯示屬性和對應的描述,可在查詢作業或作業結果時使用。

屬性 描述
jobId 應用程式所提供的作業識別碼。
startTime 應用程式所提供的作業開始時間 (ISO-8601)。
endTime IoT 中樞所提供的作業完成日期 (ISO-8601)。 在作業到達「已完成」狀態後才有效。
type 作業類型:
scheduleUpdateTwin︰用來更新一組所需屬性或標籤的作業。
scheduleDeviceMethod︰用來在一組裝置對應項上叫用裝置方法的作業。
status 作業的目前狀態。 狀態的可能值︰
pending︰已排定並等候作業服務執行。
scheduled︰已排定未來時間。
running︰目前作用中的作業。
canceled:作業已被取消。
failed:作業失敗。
completed作業完成。
deviceJobStatistics 作業執行的相關統計資料。
deviceJobStatistics 屬性:
deviceJobStatistics.deviceCount:作業中的裝置數目。
deviceJobStatistics.failedCount:作業失敗的裝置數目。
deviceJobStatistics.succeededCount:作業成功的裝置數目。
deviceJobStatistics.runningCount目前正在執行作業的裝置數目。
deviceJobStatistics.pendingCount:等待執行作業的裝置數目。

其他參考資料

IoT 中樞開發人員指南中的其他參考主題包括︰

下一步

若要嘗試本文所述的一些概念,請參閱下列「IoT 中樞」教學課程: