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

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

项目
03/06/2024

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

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

设备可以：

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

默认情况下，命令期望设备是可以连接的，如果无法访问设备，则命令会失败。如果在设备模板 UI 中选择“脱机时排队”选项，则可以将命令排入队列，直到设备处于联机状态。本文将在后面的一个单独部分中介绍这些脱机命令。

若要了解有关 IoT 即插即用命令约定的详细信息，请参阅 IoT 即插即用约定。

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

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

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

定义命令

标准命令被发送到设备，以指示设备执行某操作。命令可以包含带有附加信息的参数。例如，打开设备上阀门的命令可以有指定阀门打开程度的参数。当设备完成命令时，命令也可以接收返回值。例如，要求设备运行某些诊断的命令可以接收诊断报告作为返回值。

命令被定义为设备模板的一部分。下面的屏幕截图展示了“恒温器”设备模板中的“Get Max-Min report”命令定义。此命令同时包含请求参数和响应参数：

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

字段	说明
显示名称	“仪表板磁贴”和“设备”窗体中使用的命令值。
名称	命令的名称。 IoT Central 将根据显示名称生成此字段的值，但你可根据需要选择自己的值。此字段必须为字母数字。设备代码使用此“名称”值。
功能类型	命令。
脱机时排队	是否让此命令成为脱机命令。
说明	命令功能的说明。
评论	有关命令功能的任何注释。
请求	设备命令的有效负载。
响应	设备命令响应的有效负载。

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

可选字段（例如显示名称和说明）允许你向接口和功能添加更多详细信息。

标准命令

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

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

下面的屏幕截图展示了成功命令响应如何显示在 IoT Central UI 中：

注意

对于标准命令，有 30 秒的超时。如果设备在 30 秒内未响应，IoT Central 会假定命令失败。此超时期限不可配置。

长时间运行的命令

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

注意

长时间运行的命令不属于 IoT 即插即用约定。 IoT Central 有自己的约定来实现长时间运行的命令。

本部分介绍设备如何延迟发送命令已完成的确认信息。

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

注意

为了简单起见，本文使用 Node.js。

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 方法。此命令处理程序：

检查命令名称。
调用 sendCommandResponse，以将响应发送回 IoT Central。此响应包括指示挂起结果的 202 响应代码。
完成长时间运行的操作。
使用与命令同名的报告的属性来告知 IoT Central 命令已完成。

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

脱机命令

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

注意

脱机命令不属于 IoT 即插即用约定。 IoT Central 有自己的约定来实现脱机命令。

注意

为了简单起见，本文使用 Node.js。

下面的屏幕截图展示了名为 GenerateDiagnostics 的脱机命令。 request 参数是一个对象，它包含名为 StartTime 的日期/时间属性和名为 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 值的有效负载。属性列表包括 method-name 列表项中的命令名称：

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

注意

脱机命令的默认生存时间为 24 小时，超过此时间后，消息就会到期。

未分配设备上的命令

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

后续步骤

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

通过