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ěď na IoT Central, když obdrží příkaz, a pak později upozornit IoT Central na dokončení dlouhotrvajícího příkazu .

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 Fronta, může být příkaz zařazen do fronty, dokud zařízení nebude online. Tyto offline příkazy jsou popsány v samostatné části dále v tomto článku.

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

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 chcete zjistit, 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 sestavu 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 sestavy v šabloně termostatu zařízení. Tento příkaz má parametry požadavku i odpovědi:

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

Pole	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 funkce	Příkaz.
Fronta v offline režimu	Určuje, jestli má být tento příkaz offline .
Popis	Popis schopnosti příkazu.
Komentář	Jakékoli komentáře k možnosti příkazu.
Žádost	Datová část příkazu zařízení.
Response	Datová část 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 technologie Plug and Play konvence > IoT.

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

V dlouhotrvajícím příkazu se zařízení okamžitě nedokončí. 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í technologie Plug and Play IoT. 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 pro zjednodušení používá 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;
  }
};

Volání pro onDeviceMethod nastavení commandHandler metody. 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í technologie Plug and Play IoT. IoT Central má vlastní konvenci pro implementaci offline příkazů.

Poznámka:

Tento článek pro zjednodušení používá Node.js.

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 s hodnotami 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ž jste se naučili používat příkazy v aplikaci Azure IoT Central, podívejte se na telemetrii, 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.