你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

如何使用 IoT Central REST API 来创建和管理作业

项目
10/22/2024

通过 IoT Central REST API，你可以开发与 IoT Central 应用程序集成的客户端应用程序。你可以使用 REST API 来创建和管理 IoT Central 应用程序中的作业。你可以使用 REST API 达到以下目的：

列出应用程序中的作业并查看作业的详细信息。
在应用程序中创建作业。
停止、恢复和重新运行应用程序中的作业。
在应用程序中计划作业并查看已计划作业的详细信息。

创建计划作业以在将来运行。可以将已计划作业的开始日期和时间设置为一次性、每天或每周运行一次。未计划的作业仅运行一次。

本文介绍如何使用 /jobs/{job_id} API 批量控制设备。还可以单独控制设备。

每个 IoT Central REST API 调用都需要授权标头。有关详细信息，请参阅如何对 IoT Central REST API 调用进行身份验证和授权。

有关 IoT Central REST API 的参考文档，请参阅 Azure IoT Central REST API 参考。

若要了解如何在 UI 中创建和管理作业，请参阅在 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 代码片段中的字段：

字段	说明
`id`	应用程序中作业的唯一 ID。
`displayName`	应用程序中作业的显示名称。
`description`	作业的说明。
`group`	应用作业的设备组的 ID。使用 `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`、`CommandJobData`、`CloudPropertyJobData` 或 `DeviceTemplateMigrationJobData` 之一。 API 的预览版本包括 `DeviceManifestMigrationJobData`。
`data/target`	目标设备的模型 ID。
`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"
    }
  ]
}

使用以下请求按 ID 检索单个作业：

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 调用创建一个。以下示例创建一个设备组，该组 ID 为 group1：

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

创建设备组时，需要定义 filter 以选择要添加到该组的设备。筛选器标识设备模板以及要匹配的任何属性。以下示例创建设备组，其中包含与 provisioned 属性为 true 的“dtmi:modelDefinition:dtdlv2”模板关联的所有设备。

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

创建计划作业

计划作业与标准作业的有效负载类似，但包含以下额外字段：

字段	说明
计划/开始时间	作业的开始日期和时间，采用 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 管理 IoT Central 应用程序。

通过

如何使用 IoT Central REST API 来创建和管理作业

作业有效负载

获取作业信息

创建作业

停止、恢复和重新运行作业

创建计划作业

获取计划作业

列出计划作业

更新计划作业

删除计划作业

后续步骤

反馈

其他资源