Jak používat příkazy v řešení Azure IoT Central

V tomto průvodci návodem se dozvíte, jak používat příkazy definované v šabloně zařízení.

Operátor může k volání příkazu na zařízení použít uživatelské rozhraní IoT Central. Příkazy řídí chování zařízení. Operátor může například volat příkaz k restartování zařízení nebo shromažďování diagnostických dat.

Zařízení může:

• Okamžitě zareagujte na příkaz.
• Odpovězte IoT Central, když obdrží příkaz, a poté upozorněte IoT Central na dokončení dlouhotrvající příkaz.

Příkazy ve výchozím nastavení očekávají, že se zařízení připojí a selže, pokud zařízení není dostupné. Pokud v uživatelském rozhraní šablony zařízení vyberete možnost Zařadit do fronty, pokud offline, může být příkaz zařazen do fronty, dokud se zařízení nepřipojí. Tyto offline příkazy jsou popsány v samostatné části dále v tomto článku.

Další informace o konvencích příkazů IoT Pug a Play najdete v tématu Konvence IoT Plug and Play.

Další informace o datech příkazů, která zařízení vyměňuje se službou IoT Central, najdete v tématu Telemetrie, vlastnosti a datové části příkazů.

Pokud se chcete dozvědět, jak spravovat příkazy pomocí rozhraní IoT Central REST API, přečtěte si, jak používat rozhraní IOT Central REST API k řízení zařízení.

Informace o tom, jak implementovat příkazy v zařízení bez použití sad SDK zařízení, najdete v tématu Komunikace se službou IoT Hub pomocí protokolu MQTT.

Definování příkazů

Standardní příkazy se odesílají do zařízení, aby zařízení něco udělalo. Příkaz může obsahovat parametry s dalšími informacemi. Například příkaz k otevření ventilu na zařízení může mít parametr, který určuje, kolik se má ventil otevřít. Příkazy můžou po dokončení příkazu také obdržet návratovou hodnotu. Například příkaz, který požádá zařízení o spuštění nějaké diagnostiky, může obdržet diagnostickou zprávu jako návratovou hodnotu.

Příkazy se definují jako součást šablony zařízení. Následující snímek obrazovky ukazuje definici příkazu Get Max-Min report v šabloně zařízení Termostat . Tento příkaz má parametry požadavku i odpovědi:

Následující tabulka ukazuje nastavení konfigurace pro funkci příkazu:

Obor	Description
Zobrazovaný název	Hodnota příkazu použitá na dlaždicích řídicích panelů a formulářích zařízení.
Název	Název příkazu. IoT Central vygeneruje hodnotu pro toto pole ze zobrazovaného názvu, ale v případě potřeby můžete zvolit vlastní hodnotu. Toto pole musí být alfanumerické. Kód zařízení používá tuto hodnotu Name .
Typ schopnosti	Příkaz.
Zařaďte do fronty při offline režimu	Určuje, jestli má být tento příkaz offline .
Description	Popis schopnosti příkazu.
Comment	Jakékoli komentáře k funkci příkazu.
Žádost	Datová část příkazu pro zařízení.
Odezva	Náklad odpovědi příkazu zařízení.

Další informace o jazyce DTDL (Digital Twin Definition Language), který Azure IoT Central používá k definování příkazů v šabloně zařízení, najdete v tématu Příkazy > ioT Plug and Play.

Volitelná pole, jako je zobrazovaný název a popis, umožňují přidat do rozhraní a funkcí další podrobnosti.

Standardní příkazy

Aby bylo možné zpracovat standardní příkaz, zařízení odešle hodnotu odpovědi, jakmile obdrží příkaz z IoT Central. Sadu SDK zařízení Azure IoT můžete použít ke zpracování standardních příkazů vyvolaých vaší aplikací IoT Central.

Příklady implementace ve více jazycích najdete v tématu Kurz: Vytvoření a připojení klientské aplikace k aplikaci Azure IoT Central.

Následující snímek obrazovky ukazuje, jak se v uživatelském rozhraní IoT Central zobrazuje úspěšná odpověď příkazu:

Poznámka:

U standardních příkazů je časový limit 30 sekund. Pokud zařízení nereaguje do 30 sekund, IoT Central předpokládá, že příkaz selhal. Toto časové období není možné konfigurovat.

Dlouhotrvající příkazy

U dlouhotrvajícího příkazu zařízení okamžitě nedokončí tento příkaz. Místo toho zařízení potvrdí přijetí příkazu a později potvrdí, že příkaz byl dokončen. Tento přístup umožňuje zařízení dokončit dlouhotrvající operaci, aniž by bylo připojení k IoT Central otevřené.

Poznámka:

Dlouhotrvající příkazy nejsou součástí konvencí IoT Plug and Play. IoT Central má vlastní konvenci pro implementaci dlouhotrvajících příkazů.

V této části se dozvíte, jak může zařízení zpozdit odeslání potvrzení, že se příkaz dokončil.

Následující fragment kódu ukazuje, jak může zařízení implementovat dlouhotrvající příkaz:

Poznámka:

Tento článek používá Node.js pro jednoduchost.

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

Volání onDeviceMethod nastaví metodu commandHandler. Tato obslužná rutina příkazu:

1. Zkontroluje název příkazu.
2. Volání sendCommandResponse pro odeslání odpovědi zpět do IoT Central Tato odpověď obsahuje 202 kód odpovědi, který označuje čekající výsledky.
3. Dokončí dlouhotrvající operaci.
4. Použije ohlášenou vlastnost se stejným názvem jako příkaz k tomu, aby ioT Central oznámila, že se příkaz dokončil.

Následující snímek obrazovky ukazuje uživatelské rozhraní IoT Central, když obdrží aktualizaci vlastnosti, která indikuje dokončení příkazu:

Offline příkazy

V této části se dozvíte, jak zařízení zpracovává offline příkaz. Pokud je zařízení online, může po přijetí zpracovat offline příkaz. Pokud je zařízení offline, zpracuje offline příkaz, když se příště připojí ke službě IoT Central. Zařízení nemůžou odeslat návratovou hodnotu v reakci na offline příkaz.

Poznámka:

Offline příkazy nejsou součástí konvencí IoT Plug and Play. IoT Central má vlastní konvenci pro implementaci offline příkazů.

Poznámka:

Tento článek používá Node.js pro jednoduchost.

Následující snímek obrazovky ukazuje offline příkaz s názvem GenerateDiagnostics. Parametr požadavku je objekt s vlastností datetime s názvem StartTime a celočíselnou vlastností výčtu s názvem Bank:

Následující fragment kódu ukazuje, jak může klient naslouchat příkazům offline a zobrazit obsah zprávy:

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

Výstup z předchozího fragmentu kódu ukazuje datovou část, která obsahuje hodnoty StartTime a Bank. Seznam vlastností obsahuje název příkazu v položce seznamu název metody :

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

Poznámka:

Výchozí doba pro offline příkazy je 24 hodin, po které vyprší platnost zprávy.

Příkazy na nepřiřazených zařízeních

Příkazy můžete volat na zařízení, které není přiřazené k šabloně zařízení. Pokud chcete volat příkaz na nepřiřazené zařízení, přejděte na zařízení v části Zařízení , vyberte Spravovat zařízení a pak příkaz. Zadejte název metody, datovou část a všechny další požadované hodnoty. Následující snímek obrazovky ukazuje uživatelské rozhraní, které používáte k volání příkazu:

Další kroky

Teď, když víte, jak používat příkazy v aplikaci Azure IoT Central, podívejte se na telemetrická data, vlastnost a datové části příkazů , kde najdete další informace o parametrech příkazů a vytvoření a připojení klientské aplikace k aplikaci Azure IoT Central , abyste viděli kompletní ukázky kódu v různých jazycích.