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

發行項
05/13/2024

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

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

裝置可以︰

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

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

若要了解 IoT 隨插即用命令慣例，請參閱 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 的離線命令。要求參數是一個物件，其日期時間屬性稱為 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 應用程式，以查看不同語言的完整程式碼範例。

共用方式為