如何在 Azure IoT Central 解决方案中使用命令

本作指南介绍如何使用设备模板中定义的命令。

操作员可以使用 IoT Central UI 在设备上调用命令。 命令控制设备的行为。 例如，操作员可以调用命令来重新启动设备或收集诊断数据。

设备可以：

• 立即响应命令。
• 在收到命令时响应 IoT Central，然后在长时间运行的命令完成时通知 IoT Central。

默认情况下，命令要求设备已连接，如果无法访问设备，则失败。 如果在设备模板 UI 中选择“离线时排队”选项，则命令可以在设备上线之前排队。 本文后面的单独部分介绍了这些 脱机命令 。

若要了解 IoT Pug 和 Play 命令约定，请参阅 IoT 即插即用约定。

若要详细了解设备与 IoT Central 交换的命令数据，请参阅 遥测、属性和命令有效负载。

若要了解如何使用 IoT Central REST API 管理命令，请参阅 如何使用 IoT Central REST API 控制设备。

若要了解如何在不使用设备 SDK 的情况下在设备中实现命令，请参阅 使用 MQTT 协议与 IoT 中心通信。

定义命令

标准命令将发送到设备，以指示设备执行某些作。 命令可以包含具有其他信息的参数。 例如，在设备上打开阀的命令可以具有一个参数，该参数指定打开阀的多少。 当设备完成命令时，命令还可以接收返回值。 例如，要求设备运行某些诊断的命令可能会以返回值的形式接收诊断报告。

命令定义为设备模板的一部分。 以下屏幕截图显示了恒温器设备模板中的“获取 Max-Min 报表”命令定义。 此命令具有请求和响应参数：

下表显示了命令功能的配置设置：

若要了解 Azure IoT Central 用于在设备模板中定义命令的数字孪生定义语言（DTDL），请参阅 IoT 即插即用约定 > 命令。

可选字段（如显示名称和说明），可向界面和功能添加更多详细信息。

标准命令

为了处理标准命令，设备在从 IoT Central 接收命令后立即发送响应值。 可以使用 Azure IoT 设备 SDK 来处理 IoT Central 应用程序调用的标准命令。

有关多种语言实现的示例，请参阅 教程：创建客户端应用程序并将其连接到 Azure IoT Central 应用程序。

以下屏幕截图显示了成功命令响应在 IoT Central UI 中的显示方式：

需要长时间运行的命令

在长时间运行的命令中，设备不会立即完成该命令。 相反，设备会确认收到命令，然后随后确认命令已完成。 此方法使设备无需保持与 IoT Central 的连接即可完成长时间运行的操作。

本部分说明设备如何延迟发送命令已完成的确认。

以下代码片段演示设备如何实现长时间运行的命令：

client.onDeviceMethod('rundiagnostics', commandHandler);

// ...

const commandHandler = async (request, response) => {
  switch (request.methodName) {
  case 'rundiagnostics': {
    console.log('Starting long-running diagnostics run ' + request.payload);
    await sendCommandResponse(request, response, 202, 'Diagnostics run started');

    // Long-running operation here
    // ...

    const patch = {
      rundiagnostics: {
        value: 'Diagnostics run complete at ' + new Date().toLocaleString()
      }
    };

    deviceTwin.properties.reported.update(patch, function (err) {
      if (err) throw err;
      console.log('Properties have been reported for component');
    });
    break;
  }
  default:
    await sendCommandResponse(request, response, 404, 'unknown method');
    break;
  }
};

调用 onDeviceMethod 来配置 commandHandler 方法。 此命令处理程序：

1. 检查命令的名称。
2. 调用 sendCommandResponse 将响应发送回 IoT Central。 此响应包括用于表示待处理结果的 202 响应代码。
3. 完成长时间运行的操作。
4. 使用与命令同名的报告属性，告知 IoT Central 命令已完成。

以下屏幕截图显示了当 IoT Central UI 收到指示命令已完成的属性更新时：

脱机命令

本部分介绍如何设备处理脱机命令。 如果设备处于联机状态，它可以在收到脱机命令后立即处理。 如果设备处于脱机状态，它将在下次连接到 IoT Central 时处理脱机命令。 设备无法发送返回值以响应脱机命令。

以下屏幕截图显示了名为 GenerateDiagnostics 的脱机命令。 请求参数是一个对象，该对象具有名为 StartTime 的 datetime 属性和一个名为 Bank 的整数枚举属性：

以下代码片段演示客户端如何侦听脱机命令并显示消息内容：

client.on('message', function (msg) {
  console.log('Body: ' + msg.data);
  console.log('Properties: ' + JSON.stringify(msg.properties));
  client.complete(msg, function (err) {
    if (err) {
      console.error('complete error: ' + err.toString());
    } else {
      console.log('complete sent');
    }
  });
});

上一代码片段的输出显示具有 StartTime 和 Bank 值的有效负载。 属性列表包括 方法名称 列表项中的命令名称：

Body: {"StartTime":"2021-01-06T06:00:00.000Z","Bank":2}
Properties: {"propertyList":[{"key":"iothub-ack","value":"none"},{"key":"method-name","value":"GenerateDiagnostics"}]}

未分配设备上的命令

可以在未分配给设备模板的设备上调用命令。 若要在未分配的设备上调用命令，请在“ 设备 ”部分导航到设备，选择“ 管理设备 ”，然后选择 “命令”。 输入方法名称、有效负载和任何其他必需值。 以下屏幕截图显示了用于调用命令的 UI：

后续步骤

了解如何在 Azure IoT Central 应用程序中使用命令后，请参阅 遥测、属性和命令有效负载 ，详细了解命令参数， 并创建客户端应用程序并将其连接到 Azure IoT Central 应用程序 ，以查看不同语言的完整代码示例。