Azure IoT Central ソリューションでコマンドを使用する方法

このハウツー ガイドでは、デバイス テンプレートで定義されているコマンドを使用する方法を示します。

オペレーターは、IoT Central UI を使用して、デバイスでコマンドを呼び出すことができます。 コマンドによってデバイスの動作が制御されます。 たとえば、オペレーターはデバイスを再起動するか、または診断データを収集するためにコマンドを呼び出すことがあります。

デバイスは次のことを実行できます。

• 直ちにコマンドに応答する。
• コマンドを受信したときに IoT Central に応答し、その後、"実行時間の長いコマンド" が完了したら IoT Central に通知する。

既定では、コマンドはデバイスが接続されていることを予期し、デバイスに到達できない場合は失敗します。 デバイス テンプレート UI で [オフラインの場合にキューに入れる] オプションを選択した場合は、デバイスがオンラインになるまでコマンドがキューに入れられることがあります。 これらの "オフライン コマンド" は、この記事の後の方にある別のセクションで説明されています。

IoT Plug and Play コマンド規則の詳細については、IoT Plug and Play規則を参照してください。

デバイスが IoT Central と交換するコマンド データの詳細については、Telemetry、プロパティ、および command ペイロードを参照してください。

IoT Central REST API を使用してコマンドを管理する方法については、「IoT Central REST API を使用してデバイスを制御する方法」を参照してください。

デバイス SDK を使用せずにデバイスにコマンドを実装する方法については、「MQTT プロトコルを使用した IoT ハブとの通信」を参照してください。

コマンドを定義する

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

コマンドは、デバイス テンプレートの一部として定義されます。 次のスクリーンショットは、[サーモスタット] デバイス テンプレート内の [最大-最小レポートの取得] コマンドの定義を示しています。 このコマンドには、要求パラメーターと応答パラメーターの両方が含まれています。

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

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

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

標準コマンド

標準コマンドを処理するために、デバイスは IoT Central からコマンドを受信するとすぐに応答値を送信します。 Azure IoT device SDK を使用して、IoT Central アプリケーションによって呼び出された標準コマンドをハンドルできます。

複数の言語での実装例については、「 クライアント アプリケーションを作成して Azure IoT Central アプリケーションに接続する」を参照してください。

次のスクリーンショットは、成功したコマンドの応答が IoT Central UI にどのように表示されるかを示しています。

実行時間の長いコマンド

実行時間の長いコマンドでは、デバイスはコマンドをすぐに完了しません。 代わりに、デバイスはコマンドの受信を確認し、後でコマンドが完了したことを確認します。 この方法により、デバイスは IoT Central への接続を開いたままにすることなく、実行時間の長い操作を完了できます。

このセクションでは、デバイスがコマンドの完了を示す確認を送信するのを遅らせる方法を示します。

次のコード スニペットは、デバイスが実行時間の長いコマンドを実装する方法を示しています。

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 メソッドが設定されます。 このコマンド ハンドラーは、次の処理を行います。

1. コマンドの名前をチェックします。
2. sendCommandResponse を呼び出して、IoT Central に応答を返送します。 この応答には、保留中の結果を示す 202 応答コードが含まれます。
3. 実行時間の長い操作を完了します。
4. コマンドと同じ名前を持つ報告されるプロパティを使用して、IoT Central にコマンドが完了したことを通知します。

次のスクリーンショットは、コマンドが完了したことを示すプロパティの更新を受信したときの IoT Central UI を示しています。

オフライン コマンド

このセクションでは、デバイスがオフライン コマンドを処理する方法を示します。 デバイスはオンラインである場合、受信したオフライン コマンドを直ちに処理できます。 デバイスはオフラインである場合、次回 IoT Central に接続したときにオフライン コマンドを処理します。 デバイスは、オフライン コマンドに応答して戻り値を送信することができません。

次のスクリーンショットは、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 値を持つペイロードを示しています。 このプロパティ リストでは、method-name のリスト項目にコマンド名が含まれています。

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

未割り当てデバイス上のコマンド

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

次のステップ

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