Как использовать REST API в IoT Central для создания заданий и управления ими

Статья
10/22/2024

REST API IoT Central позволяет разрабатывать клиентские приложения, которые интегрируются с приложениями IoT Central. Вы можете использовать REST API для создания заданий и управления ими в приложении IoT Central. REST API предоставляет следующие возможности.

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

Запланированные задания создаются для выполнения в будущем. Вы можете задать дату и время начала запланированного задания для выполнения однократно, ежедневно или еженедельно. Непланированные задания выполняются только один раз.

В этой статье описывается, как использовать API /jobs/{job_id} для массового управления устройствами. Вы также можете управлять устройствами по отдельности.

Каждому вызову REST API IoT Central требуется заголовок авторизации. Дополнительные сведения см. в разделе Аутентификация и авторизация вызовов REST API IoT Central.

Справочную документацию по REST API IoT Central см. в справочнике по REST API Azure IoT Central.

Сведения о создании заданий и управлении ими в пользовательском интерфейсе см. в статье "Управление устройствами в массовом режиме" в приложении Azure IoT Central.

Полезные данные задания

Многие API, описанные в этой статье, включают определение, которое выглядит как следующий фрагмент кода JSON:

{
  "id": "job-014",
  "displayName": "Set target temperature",
  "description": "Set target temperature for all thermostat devices",
  "group": "833d7a7d-8f99-4e04-9e56-745806bdba6e",
  "batch": {
    "type": "percentage",
    "value": 25
  },
  "cancellationThreshold": {
    "type": "percentage",
    "value": 10,
    "batch": false
  },
  "data": [
    {
      "type": "PropertyJobData",
      "target": "dtmi:modelDefinition:zomtmdxh:eqod32zbyl",
      "path": "targetTemperature",
      "value": "56"
    }
  ],
  "status": "complete"
}

В следующей таблице описаны поля в предыдущем фрагменте кода JSON:

Поле	Description
`id`	Уникальный идентификатор задания в приложении.
`displayName`	Отображаемое имя задания в приложении.
`description`	Описание задания.
`group`	Идентификатор группы устройств, к которой применяется задание. Используйте предварительную версию `deviceGroups` REST API, чтобы получить список групп устройств в приложении.
`status`	Состояние задания. Одно из значений: `complete`, `cancelled`, `failed`, `pending`, `running`, `stopped`.
`batch`	При наличии этот раздел определяет, как объединить устройства в задании.
`batch/type`	Размер пакета составляет `percentage` всех устройств в группе или `number` устройства.
`batch/value`	Процент устройств или число устройств в каждом пакете.
`cancellationThreshold`	При наличии этот раздел определяет порог отмены для здания.
`cancellationThreshold/batch`	`true` или `false`. Если значение true, то пороговое значение отмены устанавливается для каждого пакета. Если значение `false`, то порог отмены применяется ко всему заданию.
`cancellationThreshold/type`	Порог отмены для задания составляет `percentage` или `number` устройств.
`cancellationThreshold/value`	Процент устройств или число устройств, определяющих порог отмены.
`data`	Массив операций, выполняемых заданием.
`data/type`	Один из `PropertyJobData`, `CommandJobDataCloudPropertyJobData`или `DeviceTemplateMigrationJobData`. Предварительная версия API включает `DeviceManifestMigrationJobData`.
`data/target`	Идентификатор модели целевых устройств.
`data/path`	Имя свойства, команды или облачного свойства.
`data/value`	Значение свойства, которое необходимо задать, или параметр команды для отправки.

Получение сведений о задании

Используйте следующий запрос для получения списка заданий в приложении:

GET https://{your app subdomain}.azureiotcentral.com/api/jobs?api-version=2022-07-31

Ответ на этот запрос выглядит так, как показано в следующем примере.

{
  "value": [
    {
      "id": "job-006",
      "displayName": "Set customer name",
      "description": "Set the customer name cloud property",
      "group": "4fcbec3b-5ee8-4324-855d-0f03b56bcf7f",
      "data": [
        {
          "type": "CloudPropertyJobData",
          "target": "dtmi:modelDefinition:bojo9tfju:yfvu5gv2vl",
          "path": "CustomerName",
          "value": "Contoso"
        }
      ],
      "status": "complete"
    },
    {
      "id": "job-005",
      "displayName": "Set target temperature",
      "description": "Set target temperature device property",
      "group": "833d7a7d-8f99-4e04-9e56-745806bdba6e",
      "data": [
        {
          "type": "PropertyJobData",
          "target": "dtmi:modelDefinition:zomtmdxh:eqod32zbyl",
          "path": "targetTemperature",
          "value": 56
        }
      ],
      "status": "complete"
    },
    {
      "id": "job-004",
      "displayName": "Run device report",
      "description": "Call command to run the device reports",
      "group": "833d7a7d-8f99-4e04-9e56-745806bdba6e",
      "batch": {
        "type": "percentage",
        "value": 25
      },
      "cancellationThreshold": {
        "type": "percentage",
        "value": 10,
        "batch": false
      },
      "data": [
        {
          "type": "CommandJobData",
          "target": "dtmi:modelDefinition:zomtmdxh:eqod32zbyl",
          "path": "getMaxMinReport",
          "value": "2021-06-15T05:00:00.000Z"
        }
      ],
      "status": "complete"
    }
  ]
}

Используйте следующий запрос для получения отдельного задания по идентификатору:

GET https://{your app subdomain}.azureiotcentral.com/api/jobs/job-004?api-version=2022-07-31

Ответ на этот запрос выглядит так, как показано в следующем примере.

{
  "id": "job-004",
  "displayName": "Run device report",
  "description": "Call command to run the device reports",
  "group": "833d7a7d-8f99-4e04-9e56-745806bdba6e",
  "batch": {
    "type": "percentage",
    "value": 25
  },
  "cancellationThreshold": {
    "type": "percentage",
    "value": 10,
    "batch": false
  },
  "data": [
    {
      "type": "CommandJobData",
      "target": "dtmi:modelDefinition:zomtmdxh:eqod32zbyl",
      "path": "getMaxMinReport",
      "value": "2021-06-15T05:00:00.000Z"
    }
  ],
  "status": "complete"
}

Используйте следующий запрос для получения сведений об устройствах в задании:

GET https://{your app subdomain}.azureiotcentral.com/api/jobs/job-004/devices?api-version=2022-07-31

Ответ на этот запрос выглядит так, как показано в следующем примере.

{
  "value": [
    {
      "id": "therm-01",
      "status": "completed"
    },
    {
      "id": "therm-02",
      "status": "completed"
    },
    {
      "id": "therm-03",
      "status": "completed"
    },
    {
      "id": "therm-04",
      "status": "completed"
    }
  ]
}

Создание задания

Используйте следующий запрос для создания задания:

PUT https://{your app subdomain}.azureiotcentral.com/api/jobs/job-006?api-version=2022-07-31

Поле group в тексте запроса определяет группу устройств в приложении IoT Central. Задание использует группу устройств для идентификации набора устройств, с которым работает задание.

Если у вас еще нет подходящей группы устройств, можно создать ее с помощью вызова REST API. В следующем примере создается группа устройств с group1 идентификатором группы:

PUT https://{your app subdomain}/api/deviceGroups/group1?api-version=2022-07-31

При создании группы устройств определяется filter , который выбирает устройства для включения в группу. Фильтр определяет шаблон устройства и соответствующие свойства. В следующем примере создается группа устройств, содержащая все устройства, связанные с шаблоном устройства dtmi:modelDefinition:dtdlv2, где provisioned находится trueсвойство.

{
  "displayName": "Device group 1",
  "description": "Custom device group.",
  "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true"
}

Ответ на этот запрос выглядит так, как показано в следующем примере.

{
  "id": "group1",
  "displayName": "Device group 1",
  "description": "Custom device group.",
  "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true"
}

Теперь можно использовать id значение из ответа для создания нового задания.

{
  "displayName": "Set target temperature",
  "description": "Set target temperature device property",
  "group": "group1",
  "batch": {
    "type": "percentage",
    "value": 25
  },
  "cancellationThreshold": {
    "type": "percentage",
    "value": 10,
    "batch": false
  },
  "data": [
    {
      "type": "PropertyJobData",
      "target": "dtmi:modelDefinition:zomtmdxh:eqod32zbyl",
      "path": "targetTemperature",
      "value": "55"
    }
  ]
}

Ответ на этот запрос выглядит, как показано в примере ниже. Начальное состояние задания pending:

{
  "id": "job-006",
  "displayName": "Set target temperature",
  "description": "Set target temperature device property",
  "group": "group1",
  "batch": {
    "type": "percentage",
    "value": 25
  },
  "cancellationThreshold": {
    "type": "percentage",
    "value": 10,
    "batch": false
  },
  "data": [
    {
      "type": "PropertyJobData",
      "target": "dtmi:modelDefinition:zomtmdxh:eqod32zbyl",
      "path": "targetTemperature",
      "value": "55"
    }
  ],
  "status": "pending"
}

Остановка, возобновление и повторный запуск заданий

Используйте следующий запрос, чтобы остановить выполнение задания:

POST https://{your app subdomain}.azureiotcentral.com/api/jobs/job-006/stop?api-version=2022-07-31

Если запрос выполнен успешно, возвращается ответ 204 - No Content.

Используйте следующий запрос, чтобы возобновить остановленное задание:

POST https://{your app subdomain}.azureiotcentral.com/api/jobs/job-006/resume?api-version=2022-07-31

Если запрос выполнен успешно, возвращается ответ 204 - No Content.

Используйте следующую команду для повторного запуска существующего задания на всех неисправных устройствах:

PUT https://{your app subdomain}.azureiotcentral.com/api/jobs/job-006/rerun/rerun-001?api-version=2022-07-31

Создание запланированного задания

Полезные данные для запланированного задания похожи на стандартное задание, но включают следующие дополнительные поля:

Поле	Description
расписание или запуск	Дата начала и время задания в формате ISO 8601
расписание и повторение	Возможные значения: `daily`, `monthly`, `yearly \|`
расписание или конец	Необязательное поле, указывающее число вхождений для задания или даты окончания в формате ISO 8601

PUT https://{your app subdomain}.azureiotcentral.com/api/scheduledJobs/scheduled-Job-001?api-version=2022-07-31

В следующем примере показан текст запроса, создающий запланированное задание.

{
    "displayName": "New Scheduled Job",
    "group": "6fecf96f-a26c-49ed-8076-6960f8efba31",
    "data": [
        {
            "type": "cloudProperty",
            "target": "dtmi:eclipsethreadx:devkit:hlby5jgib2o",
            "path": "Company",
            "value": "Contoso"
        }
    ],
    "schedule": {
        "start": "2022-10-24T22:29:01Z",
        "recurrence": "daily",
        "end": {
            "type": "date",
            "date": "2022-12-30"
        }
    }
}

Ответ на этот запрос выглядит так, как показано в следующем примере.

{
    "id": "scheduled-Job-001",
    "displayName": "New Scheduled Job",
    "description": "",
    "group": "6fecf96f-a26c-49ed-8076-6960f8efba31",
    "data": [
        {
            "type": "cloudProperty",
            "target": "dtmi:eclipsethreadx:devkit:hlby5jgib2o",
            "path": "Company",
            "value": "Contoso"
        }
    ],
    "schedule": {
        "start": "2022-10-24T22:29:01Z",
        "recurrence": "daily",
        "end": {
            "type": "date",
            "date": "2022-12-30"
        }
    },
    "enabled": false,
    "completed": false,
    "etag": "\"88003877-0000-0700-0000-631020670000\""
}

Получение запланированного задания

Используйте следующий запрос, чтобы получить запланированное задание:

GET https://{your app subdomain}.azureiotcentral.com/api/scheduledJobs/scheduled-Job-001?api-version=2022-07-31

Ответ на этот запрос выглядит так, как показано в следующем примере.

{
    "id": "scheduled-Job-001",
    "displayName": "New Scheduled Job",
    "description": "",
    "group": "6fecf96f-a26c-49ed-8076-6960f8efba31",
    "data": [
        {
            "type": "cloudProperty",
            "target": "dtmi:eclipsethreadx:devkit:hlby5jgib2o",
            "path": "Company",
            "value": "Contoso"
        }
    ],
    "schedule": {
        "start": "2022-10-24T22:29:01Z",
        "recurrence": "daily"
    },
    "enabled": false,
    "completed": false,
    "etag": "\"88003877-0000-0700-0000-631020670000\""
}

Вывод списка запланированных заданий

Используйте следующий запрос, чтобы получить список запланированных заданий:

GET https://{your app subdomain}.azureiotcentral.com/api/scheduledJobs?api-version=2022-07-31

Ответ на этот запрос выглядит так, как показано в следующем примере.

{
    "value": [
        {
            "id": "scheduled-Job-001",
            "displayName": "New Scheduled Job",
            "description": "",
            "group": "6fecf96f-a26c-49ed-8076-6960f8efba31",
            "data": [
                {
                    "type": "cloudProperty",
                    "target": "dtmi:eclipsethreadx:devkit:hlby5jgib2o",
                    "path": "Company",
                    "value": "Contoso"
                }
            ],
            "schedule": {
                "start": "2022-10-24T22:29:01Z",
                "recurrence": "daily"
            },
            "enabled": false,
            "completed": false,
            "etag": "\"88003877-0000-0700-0000-631020670000\""
        },
        {
            "id": "46480dff-dc22-4542-924e-a5d45bf347aa",
            "displayName": "test",
            "description": "",
            "group": "cdd04344-bb55-425b-a55a-954d68383289",
            "data": [
                {
                    "type": "cloudProperty",
                    "target": "dtmi:rigado:evxfmi0xim",
                    "path": "test",
                    "value": 2
                }
            ],
            "schedule": {
                "start": "2022-09-01T03:00:00.000Z"
            },
            "enabled": true,
            "completed": true,
            "etag": "\"88000f76-0000-0700-0000-631020310000\""
        }
    ]
}

Обновление запланированного задания

Используйте следующий запрос для обновления запланированного задания:

PATCH https://{your app subdomain}.azureiotcentral.com/api/scheduledJobs/scheduled-Job-001?api-version=2022-07-31

В следующем примере показан текст запроса, который обновляет запланированное задание.

{
  "schedule": {
    "start": "2022-10-24T22:29:01Z",
    "recurrence": "weekly"
  }
}

Ответ на этот запрос выглядит так, как показано в следующем примере.

{
    "id": "scheduled-Job-001",
    "displayName": "New Scheduled Job",
    "description": "",
    "group": "6fecf96f-a26c-49ed-8076-6960f8efba31",
    "data": [
        {
            "type": "cloudProperty",
            "target": "dtmi:eclipsethreadx:devkit:hlby5jgib2o",
            "path": "Company",
            "value": "Contoso"
        }
    ],
    "schedule": {
        "start": "2022-10-24T22:29:01Z",
        "recurrence": "weekly"
    },
    "enabled": false,
    "completed": false,
    "etag": "\"88003877-0000-0700-0000-631020670000\""
}

Удаление запланированного задания

Используйте следующий запрос, чтобы удалить запланированное задание

GET https://{your app subdomain}.azureiotcentral.com/api/scheduledJobs/scheduled-Job-001?api-version=2022-07-31

Следующие шаги

Теперь, когда вы узнали, как управлять заданиями с помощью REST API, рекомендуемым следующим шагом является руководство. Использование REST API для управления приложением Azure IoT Central.

Поделиться через

Как использовать REST API в IoT Central для создания заданий и управления ими

Полезные данные задания

Получение сведений о задании

Создание задания

Остановка, возобновление и повторный запуск заданий

Создание запланированного задания

Получение запланированного задания

Вывод списка запланированных заданий

Обновление запланированного задания

Удаление запланированного задания

Следующие шаги

Обратная связь

Дополнительные ресурсы