Udostępnij przez

Planowanie zadań usługi Azure IoT Hub na wielu urządzeniach

Usługa Azure IoT Hub umożliwia korzystanie z wielu bloków konstrukcyjnych, takich jak właściwości bliźniacze urządzenia i tagi oraz metody bezpośrednie. Zazwyczaj aplikacje zaplecza umożliwiają administratorom i operatorom urządzeń zbiorcze aktualizowanie i interakcję z urządzeniami IoT oraz interakcję z nimi w zaplanowanym czasie. Zadania wykonują aktualizacje kopii cyfrowej urządzenia i bezpośrednie metody dla zestawu urządzeń w zaplanowanym czasie. Na przykład operator używa aplikacji back-endowej, która inicjuje i śledzi zadanie ponownego uruchomienia zestawu urządzeń w budynku 43 na piętrze 3 w czasie, który nie zakłóca funkcjonowania budynku.

Uwaga

Funkcje opisane w tym artykule są dostępne tylko w warstwie Standardowa usługi IoT Hub. Aby uzyskać więcej informacji na temat warstw podstawowej i standardowej/bezpłatnej usługi IoT Hub, zobacz Wybieranie odpowiedniej warstwy i rozmiaru usługi IoT Hub dla rozwiązania.

Rozważ użycie zadań, gdy musisz zaplanować i śledzić postęp dowolny z następujących działań na zestawie urządzeń:

  • Aktualizowanie żądanych właściwości
  • Aktualizowanie tagów
  • Wywoływanie metod bezpośrednich

Cykl życia zadania

Zadania są inicjowane przez zaplecze rozwiązania i obsługiwane przez usługę IoT Hub. Zadanie można zainicjować za pomocą identyfikatora URI dostępnego dla usługi (PUT https://<iot hub>/jobs/v2/<jobID>?api-version=2021-04-12) i wykonywania zapytań o postęp wykonywania zadania za pomocą identyfikatora URI dostępnego dla usługi (GET https://<iot hub>/jobs/v2/<jobID?api-version=2021-04-12). Aby odświeżyć stan uruchomionych zadań po zainicjowaniu zadania, uruchom zapytanie dotyczące zadania. Nie ma wyraźnego usuwania historii zadań, ale mają czas życia (TTL) 30 dni. 

Uwaga

Kiedy inicjujesz zadanie, nazwy właściwości i wartości mogą zawierać tylko US-ASCII drukowalne znaki alfanumeryczne, z wyjątkiem tych znajdujących się w następującym zestawie: $ ( ) < > @ , ; : \ " / [ ] ? = { } SP HT

Uwaga

Pole jobId musi zawierać maksymalnie 64 znaki i może zawierać tylko US-ASCII litery, cyfry i znak kreski (-).

Zadania do wykonania metodami bezpośrednimi

Poniższy fragment kodu przedstawia szczegóły żądania HTTPS 1.1 dotyczące wykonywania metody bezpośredniej na zestawie urządzeń przy użyciu zadania:

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

Warunek zapytania może również znajdować się na jednym identyfikatorze urządzenia lub na liście identyfikatorów urządzeń, jak pokazano w poniższych przykładach:

"queryCondition" = "deviceId = 'MyDevice1'"
"queryCondition" = "deviceId IN ['MyDevice1','MyDevice2']"
"queryCondition" = "deviceId IN ['MyDevice1']"

Aby uzyskać więcej informacji na temat języka zapytań usługi IoT Hub, zobacz Język zapytań usługi IoT Hub dla bliźniaczych reprezentacji urządzeń i modułów, zadań i routingu komunikatów.

Poniższy fragment kodu przedstawia żądanie i odpowiedź dla zadania zaplanowanego do wywołania metody bezpośredniej o nazwie testMethod na wszystkich urządzeniach w contoso-hub-1:

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

Zadania aktualizacji właściwości bliźniaka cyfrowego urządzenia

Poniższy fragment przedstawia szczegóły żądania HTTPS 1.1 dotyczącego aktualizacji właściwości bliźniaczego modelu urządzenia za pomocą zadania.

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

Uwaga

Właściwość updateTwin wymaga prawidłowego dopasowania wartości etag; na przykład etag="*".

Poniższy fragment kodu przedstawia żądanie i odpowiedź dla zadania zaplanowanego do zaktualizowania właściwości bliźniaczego obrazu urządzenia dla testowego urządzenia na platformie 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"}

Wykonywanie zapytań o postęp zadań

Poniższy fragment kodu przedstawia szczegóły żądania HTTPS 1.1 dotyczące wykonywania zapytań dotyczących zadań:

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

Token kontynuacji jest dostarczany w odpowiedzi.

Możesz wykonywać zapytania dotyczące stanu wykonania zadania na każdym urządzeniu przy użyciu języka zapytań usługi IoT Hub dla bliźniaków urządzeń i modułów, zadań oraz routingu komunikatów.

Właściwości zadań

Na poniższej liście przedstawiono właściwości i odpowiadające im opisy, których można użyć podczas wykonywania zapytań dotyczących zadań lub wyników zadań.

Nieruchomość Opis
identyfikator zadania Identyfikator podany przez aplikację zadania.
startTime Czas rozpoczęcia zadania podany przez aplikację (ISO-8601).
endTime Data (ISO-8601) podana przez IoT Hub na moment ukończenia zadania. Ważny tylko po osiągnięciu zadania stanu 'ukończono'.
maxExecutionTimeInSeconds Aplikacja podała maksymalny dozwolony całkowity czas od momentu uruchomienia zadania do momentu jego zakończenia.
typ Typy zadań:
scheduleUpdateTwin: zadanie używane do aktualizowania zestawu żądanych właściwości lub tagów.
scheduleDeviceMethod: zadanie używane do wywoływania metody urządzenia na zestawie bliźniaczych urządzeń.
status Bieżący stan zadania. Możliwe wartości stanu:
oczekujące: Zaplanowane i oczekujące na wykonanie przez usługę realizacji zadań.
zaplanowane: Zaplanowano na przyszły termin.
w trakcie: aktualnie aktywne zadanie.
anulowane: Zadanie zostało anulowane.
nie powiodło się: Zadanie nie powiodło się.
ukończono: Zadanie zostało ukończone.
deviceJobStatistics Statystyki dotyczące wykonywania zadania.
właściwości deviceJobStatistics:
deviceJobStatistics.deviceCount: liczba urządzeń w zadaniu.
deviceJobStatistics.failedCount: Liczba urządzeń, dla których zadanie zakończyło się niepowodzeniem.
deviceJobStatistics.succeededCount: liczba urządzeń, na których zadanie zakończyło się pomyślnym wynikiem.
deviceJobStatistics.runningCount: liczba urządzeń, na których aktualnie uruchomiono zadanie.
deviceJobStatistics.pendingCount: liczba urządzeń oczekujących na uruchomienie zadania.

Inne materiały referencyjne

Inne artykuły referencyjne w przewodniku dewelopera usługi IoT Hub obejmują:

Następne kroki

Aby zapoznać się z niektórymi pojęciami opisanymi w tym artykule, zobacz następujący artykuł usługi IoT Hub:

  • Last updated on