Parancsok használata Azure IoT Central-megoldásban

Ez az útmutató bemutatja, hogyan használhatja az eszközsablonokban definiált parancsokat.

Az operátor az IoT Central felhasználói felületén meghívhat egy parancsot egy eszközön. A parancsok vezérli az eszköz viselkedését. Egy operátor például meghívhat egy parancsot egy eszköz újraindításához vagy diagnosztikai adatok gyűjtéséhez.

Az eszköz:

• Azonnal válaszoljon egy parancsra.
• Válaszoljon az IoT Centralra, amikor megkapja a parancsot, majd később értesítse az IoT Centralt, ha a hosszú ideig futó parancs befejeződött.

Alapértelmezés szerint a parancsok arra számítanak, hogy az eszköz csatlakoztatva lesz, és sikertelen lesz, ha az eszköz nem érhető el. Ha az üzenetsort választja, ha az eszközsablon felhasználói felületén offline lehetőség van, egy parancs várólistára állítható, amíg az eszköz online állapotba nem kerül. Ezeket az offline parancsokat a cikk későbbi, külön szakaszában ismertetjük.

Az IoT Pug és Play parancskonvencióinak megismeréséhez tekintse meg az IoT Plug and Play konvencióinak témakörét.

Az eszköz IoT Centralnal való cseréjének parancsadataival kapcsolatos további információkért tekintse meg a telemetriai adatokat, a tulajdonságot és a parancs hasznos adatait.

Ha meg szeretné tudni, hogyan kezelheti a parancsokat az IoT Central REST API használatával, olvassa el az IoT Central REST API használatát az eszközök vezérléséhez.

Ha meg szeretné tudni, hogyan implementálhat parancsokat egy eszközön az eszköz SDK-k használata nélkül, olvassa el a Kommunikáció IoT Hubbal az MQTT protokoll használatával című témakört.

Parancsok definiálása

A rendszer szabványos parancsokat küld egy eszköznek, hogy utasítsa az eszközt, hogy tegyen valamit. A parancsok további információkat tartalmazó paramétereket is tartalmazhatnak. Például egy eszköz szelepének megnyitására szolgáló parancs olyan paraméterrel rendelkezhet, amely meghatározza, hogy mennyi legyen a szelep megnyitása. A parancsok visszatérési értéket is kaphatnak, amikor az eszköz végrehajtja a parancsot. Például egy parancs, amely arra kéri az eszközt, hogy futtasson bizonyos diagnosztikákat, kaphat egy diagnosztikai jelentést visszatérési értékként.

A parancsok egy eszközsablon részeként vannak definiálva. Az alábbi képernyőképen a Max-Min jelentés lekérése parancsdefiníció látható a Termosztát-eszközsablonban . Ez a parancs mind a kérési, mind a válaszparaméterekkel rendelkezik:

Az alábbi táblázat egy parancsképesség konfigurációs beállításait mutatja be:

Az Azure IoT Central által az eszközsablonok parancsainak definiálására használt Digitális ikerdefiníciós nyelv (DTDL) megismeréséhez tekintse meg az IoT Plug and Play konvenciók parancsait>.

Az opcionális mezők, például a megjelenítendő név és a leírás lehetővé teszik további részletek hozzáadását a felülethez és a képességekhez.

Standard parancsok

A szabványos parancsok kezeléséhez az eszköz válaszértéket küld, amint megkapja a parancsot az IoT Centraltól. Az Azure IoT-eszköz SDK-val kezelheti az IoT Central-alkalmazás által meghívott szabványos parancsokat.

Például több nyelven futó implementációk: Ügyfélalkalmazás létrehozása és csatlakoztatása az Azure IoT Central-alkalmazáshoz.

Az alábbi képernyőkép bemutatja, hogyan jelenik meg a sikeres parancsválasz az IoT Central felhasználói felületén:

Hosszú ideig futó parancsok

Hosszú ideig futó parancs esetén az eszköz nem hajtja végre azonnal a parancsot. Ehelyett az eszköz nyugtázza a parancs fogadását, majd később megerősíti, hogy a parancs befejeződött. Ez a módszer lehetővé teszi, hogy az eszköz hosszú ideig futó műveletet hajtson végre anélkül, hogy az IoT Centralhoz való kapcsolat nyitva marad.

Ez a szakasz bemutatja, hogyan késleltetheti az eszköz a parancs befejezésének megerősítését.

Az alábbi kódrészlet bemutatja, hogyan implementálhat egy eszköz egy hosszú ideig futó parancsot:

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;
  }
};

A metódus beállítására commandHandler irányuló onDeviceMethod hívás. Ez a parancskezelő:

1. Ellenőrzi a parancs nevét.
2. Hívások sendCommandResponse a válasz visszaküldésére az IoT Centralnak. Ez a válasz tartalmazza a 202 függőben lévő eredményeket jelző válaszkódot.
3. Befejezi a hosszú ideig futó műveletet.
4. A parancs nevével megegyező nevű jelentett tulajdonság használatával közli az IoT Centralnal, hogy a parancs befejeződött.

Az alábbi képernyőképen az IoT Central felhasználói felülete látható, amikor megkapja a parancsot jelző tulajdonságfrissítést:

Offline parancsok

Ez a szakasz bemutatja, hogyan kezeli az eszköz az offline parancsokat. Ha egy eszköz online állapotban van, azonnal kezelheti az offline parancsot. Ha egy eszköz offline állapotban van, akkor az offline parancsot kezeli, amikor legközelebb csatlakozik az IoT Centralhoz. Az eszközök nem küldhetnek visszaértéket offline parancsra válaszul.

Az alábbi képernyőképen egy GenerateDiagnostics nevű offline parancs látható. A kérelemparaméter egy StartTime nevű datetime tulajdonsággal és egy Bank nevű egész számbavételi tulajdonsággal rendelkező objektum:

Az alábbi kódrészlet bemutatja, hogyan figyelheti az ügyfél az offline parancsokat, és hogyan jelenítheti meg az üzenet tartalmát:

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');
    }
  });
});

Az előző kódrészlet kimenete a StartTime és a Bank értékekkel jeleníti meg a hasznos adatokat. A tulajdonságlista tartalmazza a parancsnevet a metódusnév listaelemben:

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

Nem hozzárendelt eszközökön lévő parancsok

Olyan eszközön is meghívhat parancsokat, amelyek nincsenek eszközsablonhoz rendelve. Ha nem hozzárendelt eszközön szeretne parancsot hívni, lépjen az eszközre az Eszközök szakaszban, válassza az Eszköz kezelése, majd a Parancs lehetőséget. Adja meg a metódus nevét, hasznos adatait és minden más szükséges értéket. Az alábbi képernyőképen a parancs meghívásához használt felhasználói felület látható:

Következő lépések

Most, hogy megtanulta, hogyan használhat parancsokat az Azure IoT Central-alkalmazásban, tekintse meg a telemetriai adatokat, a tulajdonságokat és a parancsok hasznos adatait , hogy többet tudjon meg a parancsparaméterekről, valamint ügyfélalkalmazás létrehozása és csatlakoztatása az Azure IoT Central-alkalmazáshoz a teljes kódminták különböző nyelveken való megtekintéséhez.