Планирование заданий на нескольких устройствах

  • Статья

Центр Интернета вещей Azure включает ряд стандартных блоков (свойства и теги двойников устройств и прямые методы). Как правило, внутренние приложения позволяют администраторам и операторам устройств массово и в запланированное время обновлять устройства Интернета вещей и взаимодействовать с ними. На запланированное время задания выполняют обновления для двойников устройств и прямых методов для ряда устройств. Например, оператор использует внутреннее приложение, которое инициирует задание перезапуска ряда устройств на третьем этаже в здании №43 в определенное время и отслеживает ход его выполнения. При этом задание не будет нарушать выполнение других операций в здании.

Примечание

Функции, описанные в этой статье, доступны только на стандартном уровне Центра Интернета вещей. Дополнительные сведения о базовых и стандартных и бесплатных уровнях Центр Интернета вещей см. в статье Выбор подходящего уровня Центр Интернета вещей для решения.

Используйте задания, если необходимо запланировать выполнение задания на ряде устройств, а также настроить отслеживание выполнения действий:

  • Обновление требуемых свойств
  • Обновление тегов
  • Вызов прямых методов

Жизненный цикл задания

Задания инициируются в серверной части решения, а осуществляются с помощью Центра Интернета вещей. Вы можете инициировать задание, используя обращенный к службе универсальный код ресурса (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. Чтобы обновить состояние выполняемых заданий после запуска задания, выполните запрос задания. Нет явной очистки журнала заданий, но срок жизни для них составляет 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']"

В статье Справочник по языку запросов Центра Интернета вещей для двойников устройств и заданий подробно рассматривается язык запросов Центра Интернета вещей.

Следующий фрагмент кода показывает запрос и ответ для задания, запланированного для вывода прямого метода с именем testMethod на всех устройствах в 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"}

Задания для обновления свойств устройств-двойников

В следующем фрагменте показаны сведения по обновлению свойств устройства-двойника с использованием задания в запросе 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="*".

В следующем фрагменте кода показаны запрос и ответ для задания, запланированного на обновление свойств двойника устройства для Test-device в 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 получен в рамках ответа.

Вы можете выполнять запросы для получения состояния выполнения заданий на каждом устройстве, используя язык запросов Центра Интернета вещей для двойников устройств, заданий и маршрутизации сообщений.

Свойства заданий

В таблице ниже содержится список свойств, которые можно использовать при выполнении запросов на задания и их результаты, а также описание этих свойств.

Свойство Описание
jobId Идентификатор задания, указанный в приложении.
startTime Время начала задания (ISO-8601), указанное в приложении.
endTime Дата завершения задания (ISO-8601), указанная в Центре Интернета вещей. Она допустима только после перехода задания в завершенное состояние.
type Типы заданий:
scheduledUpdateTwin — задание по обновлению набора требуемых свойств или тегов.
scheduledDeviceMethod — задание по вызову метода устройства для набора двойников устройств.
status Текущее состояние задания. Возможные значения состояния:
pending — задание запланировано и ожидает действий от службы заданий.
scheduled — задание запланировано на будущее.
running — задание сейчас активно.
canceled — задание было отменено.
failed — произошел сбой задания.
completed — задание завершено.
deviceJobStatistics Статистика задания.
Свойства deviceJobStatistics:
deviceJobStatistics.deviceCount: число устройств в задании.
deviceJobStatistics.failedCount: количество устройств, на которых произошел сбой задания.
deviceJobStatistics.succeededCount: количество устройств, на которых задание выполнено успешно.
deviceJobStatistics.runningCount: количество устройств, на которых сейчас выполняется задание.
deviceJobStatistics.pendingCount: количество устройств, на которых сейчас ожидается выполнение задания.

Дополнительные справочные материалы

Другие справочные статьи в руководстве разработчика для Центра Интернета вещей:

Дальнейшие действия

Чтобы применить некоторые основные понятия, описанные в этой статье, просмотрите следующие руководства по Центру Интернета вещей: