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 ハブと通信する」を参照してください。

コマンドを定義する

標準コマンドは、デバイスに何かを行うよう指示するためにデバイスに送信されます。コマンドには、追加情報を含むパラメーターを含めることができます。たとえば、デバイスでバルブを開くコマンドには、バルブを開く量を指定するパラメーターを指定できます。デバイスがコマンドを完了した際に、コマンドは戻り値を受け取ることもあります。たとえば、一部の診断を実行するようにデバイスに要求するコマンドは、戻り値として診断レポートを受け取る可能性があります。

コマンドは、デバイステンプレートの一部として定義されます。次のスクリーンショットは、Thermostat デバイステンプレートの Get Max-Min レポート コマンド定義を示しています。このコマンドには、要求パラメーターと応答パラメーターの両方があります。

次の表に、コマンド機能の構成設定を示します。

フィールド	Description
表示される名前	ダッシュボードタイルとデバイスフォームで使用されるコマンド値。
名前	コマンドの名前。 IoT Central では、表示名からこのフィールドの値が生成されますが、必要に応じて独自の値を選択できます。このフィールドは英数字である必要があります。デバイスコードでは、この Name 値が使用されます。
機能の種類	コマンド。
オフラインの場合にキューに入れる	このコマンドをオフラインコマンドにするかどうか。
Description	コマンド機能の説明。
コメント	コマンド機能に関するコメント。
リクエスト	デバイスコマンドのペイロード。
[応答]	デバイスコマンド応答のペイロード。

Azure IoT Central がデバイステンプレートでコマンドを定義するために使用するデジタルツイン定義言語 (DTDL) の詳細については、「 IoT プラグアンドプレイ規則 > コマンド」を参照してください。

表示名や説明などの省略可能なフィールドを使用すると、インターフェイスと機能に詳細を追加できます。

標準コマンド

標準コマンドを処理するために、デバイスは IoT Central からコマンドを受信するとすぐに応答値を送信します。 Azure IoT device 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 という 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"}]}

注

オフラインコマンドの既定の有効期間は 24 時間で、その後メッセージの有効期限が切れます。

割り当てられていないデバイス上のコマンド

デバイステンプレートに割り当てられていないデバイスでコマンドを呼び出すことができます。割り当てられていないデバイスでコマンドを呼び出すには、[デバイス ] セクションで デバイスに移動し、[ デバイスの管理 ] を選択し、[ コマンド] を選択します。メソッド名、ペイロード、およびその他の必要な値を入力します。次のスクリーンショットは、コマンドの呼び出しに使用する UI を示しています。

次のステップ

Azure IoT Central アプリケーションでコマンドを使用する方法については、「テレメトリ、プロパティ、コマンドペイロード」を参照してコマンドパラメーターの詳細を確認し、クライアントアプリケーションを作成して Azure IoT Central アプリケーションに接続して、さまざまな言語の完全なコードサンプルを確認します。

フィードバック

このページはお役に立ちましたか?

Last updated on 2025-10-31