如何在 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 報告] 命令定義。此命令同時具有請求和響應參數：

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

領域	Description
顯示名稱	用於儀表板區塊和裝置表單的命令值。
名稱	命令的名稱。 IoT Central 會從顯示名稱產生此欄位的值，但您可以視需要選擇自己的值。此欄位必須是英數字元。裝置代碼使用此名稱值。
功能類型	指令。
離線時排隊	是否將此命令設為離線命令。
Description	指令功能的說明。
評論	有關命令功能的任何評論。
Request	裝置命令的承載。
回應	裝置命令回應的承載。

若要瞭解 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 值的承載。屬性清單包含 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 應用程式，以查看不同語言的完整程式碼範例。

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-09-30