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

發行項
02/06/2024

本操作說明指南說明如何使用裝置範本中定義的命令。

操作員可以使用IoT Central UI在裝置上呼叫命令。命令會控制裝置的行為。例如，操作員可能會呼叫命令來重新啟動裝置或收集診斷數據。

裝置可以：

立即回應命令。
在收到命令時回應 IoT Central，然後在長時間執行的命令完成時通知 IoT Central。

根據預設，命令會預期裝置已連線，如果無法連線到裝置，則會失敗。如果您在裝置範本 UI 中選取 [ 離線] 選項，則命令可以排入佇列，直到裝置上線為止。本文稍後的個別章節將說明這些 離線命令 。

若要瞭解IoT Pug和 Play 命令慣例，請參閱 IoT 隨插即用慣例。

若要深入了解裝置與IoT Central交換的命令數據，請參閱遙測、屬性和命令承載。

若要瞭解如何使用IoT Central REST API管理命令，請參閱如何使用IoT Central REST API來控制裝置。

定義您的命令

標準命令會傳送至裝置，以指示裝置執行某些動作。命令可以包含具有其他信息的參數。例如，在裝置上開啟閥的命令可能會有一個參數，指定開啟閥的量。當裝置完成命令時，命令也可以接收傳回值。例如，要求裝置執行某些診斷的命令可能會以傳回值的形式接收診斷報告。

命令會定義為裝置範本的一部分。下列螢幕快照顯示控溫器裝置範本中的 [取得 Max-Min] 報表命令定義。此指令同時具有要求和回應參數：

下表顯示命令功能的組態設定：

欄位	描述
顯示名稱	儀錶板磚和裝置表單上使用的命令值。
名稱	命令的名稱。 IoT Central 會從顯示名稱產生此欄位的值，但如有必要，您也可以選擇自己所要使用的值。此欄位必須是英數位元。裝置程式代碼會使用此 Name 值。
功能類型	命令。
離線時排入佇列	是否要將此命令設為離線命令。
描述	命令功能的說明。
註解	有關命令功能的任何註解。
要求	裝置命令的承載。
回應	裝置命令回應的承載。

若要瞭解 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 值的承載。屬性清單包含方法名稱清單專案中的指令名稱：

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 應用程式，以查看不同語言的完整程式碼範例。