Jak używać poleceń w rozwiązaniu usługi Azure IoT Central

W tym przewodniku z instrukcjami pokazano, jak używać poleceń zdefiniowanych w szablonie urządzenia.

Operator może użyć interfejsu użytkownika usługi IoT Central do wywołania polecenia na urządzeniu. Polecenia kontrolują zachowanie urządzenia. Na przykład operator może wywołać polecenie w celu ponownego uruchomienia urządzenia lub zebrania danych diagnostycznych.

Urządzenie może:

• Natychmiast odpowiedz na polecenie.
• Odpowiedz IoT Central po odebraniu polecenia, a następnie powiadom IoT Central, gdy długotrwałe polecenie zostanie zakończone.

Domyślnie polecenia oczekują, że urządzenie będzie połączone, i zakończą się niepowodzeniem, jeśli urządzenie nie będzie osiągalne. W przypadku wybrania opcji Kolejka, jeśli offline w interfejsie użytkownika szablonu urządzenia polecenie można kolejkować do momentu, gdy urządzenie przejdzie w tryb online. Te polecenia w trybie offline zostały opisane w oddzielnej sekcji w dalszej części tego artykułu.

Aby dowiedzieć się więcej na temat konwencji poleceń IoT Pug i Play, zobacz Konwencje IoT Plug and Play.

Aby dowiedzieć się więcej na temat danych poleceń wymienianych przez urządzenie za pomocą usługi IoT Central, zobacz Telemetria, właściwość i ładunki poleceń.

Aby dowiedzieć się, jak zarządzać poleceniami przy użyciu interfejsu API REST usługi IoT Central, zobacz Jak używać interfejsu API REST usługi IoT Central do sterowania urządzeniami.

Aby dowiedzieć się, jak zaimplementować polecenia na urządzeniu bez korzystania z zestawów SDK urządzeń, zobacz Komunikacja z centrum IoT przy użyciu protokołu MQTT.

Definiowanie poleceń

Polecenia standardowe są wysyłane do urządzenia w celu poinstruowania urządzenia o zrobieniu czegoś. Polecenie może zawierać parametry z dodatkowymi informacjami. Na przykład polecenie otwarcia zaworu na urządzeniu może mieć parametr określający, ile należy otworzyć zaworu. Polecenia mogą również odbierać wartość zwracaną, gdy urządzenie zakończy wykonywanie polecenia. Na przykład polecenie, które prosi urządzenie o uruchomienie niektórych diagnostyki, może otrzymać raport diagnostyczny jako wartość zwracaną.

Polecenia są definiowane jako część szablonu urządzenia. Poniższy zrzut ekranu przedstawia definicję polecenia Get Max-Min report w szablonie urządzenia Termostat . To polecenie ma parametry żądania i odpowiedzi:

W poniższej tabeli przedstawiono ustawienia konfiguracji dla możliwości polecenia:

(No changes needed)	Description
Wyświetlana nazwa	Wartość komendy używana w kafelkach dashbordu i formularzach urządzeń.
Name	Nazwa polecenia. Usługa IoT Central generuje wartość dla tego pola z nazwy wyświetlanej, ale w razie potrzeby możesz wybrać własną wartość. To pole musi być alfanumeryczne. Kod urządzenia używa tej wartości Nazwa .
Typ możliwości	Polecenie.
Kolejka, jeśli jest w trybie offline	Czy to polecenie ma być poleceniem offline .
Description	Opis funkcji polecenia.
Comment	Wszelkie komentarze dotyczące możliwości polecenia.
Żądanie	Ładunek polecenia urządzenia.
Odpowiedź	Ładunek reakcji na komendę urządzenia.

Aby dowiedzieć się więcej o języku DTDL (Digital Twin Definition Language), którego usługa Azure IoT Central używa do definiowania poleceń w szablonie urządzenia, zobacz IoT Plug and Play conventions Commands ( > Polecenia dotyczące technologii IoT Plug and Play).

Opcjonalne pola, takie jak nazwa wyświetlana i opis, umożliwiają dodanie dodatkowych szczegółów do interfejsu i możliwości.

Standardowe polecenia

Aby obsłużyć standardowe polecenie, urządzenie wysyła wartość odpowiedzi natychmiast po odebraniu polecenia z usługi IoT Central. Zestaw SDK urządzeń usługi Azure IoT umożliwia obsługę standardowych poleceń wywoływanych przez aplikację usługi IoT Central.

Na przykład implementacje w wielu językach, zobacz Samouczek: tworzenie i łączenie aplikacji klienckiej z aplikacją usługi Azure IoT Central.

Poniższy zrzut ekranu przedstawia sposób wyświetlania pomyślnej odpowiedzi polecenia w interfejsie użytkownika usługi IoT Central:

Uwaga / Notatka

W przypadku standardowych poleceń występuje limit czasu 30 sekund. Jeśli urządzenie nie odpowie w ciągu 30 sekund, usługa IoT Central zakłada, że polecenie nie powiodło się. Ten limit czasu nie jest konfigurowalny.

Długotrwałe polecenia

W przypadku długotrwałego polecenia urządzenie nie wykonuje go od razu. Zamiast tego urządzenie potwierdza potwierdzenie otrzymania polecenia, a następnie potwierdza, że polecenie zostało ukończone. Takie podejście umożliwia urządzeniu ukończenie długotrwałej operacji bez konieczności otwierania połączenia z usługą IoT Central.

Uwaga / Notatka

Długotrwałe polecenia nie są częścią konwencji IoT Plug and Play. Platforma IoT Central ma własną konwencję implementowania długotrwałych poleceń.

W tej sekcji pokazano, jak urządzenie może opóźnić wysyłanie potwierdzenia ukończenia polecenia.

Poniższy fragment kodu pokazuje, jak urządzenie może zaimplementować długotrwałe polecenie:

Uwaga / Notatka

W tym artykule użyto Node.js dla uproszczenia.

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

Wywołanie onDeviceMethod konfiguruje metodę commandHandler. Ta procedura obsługi poleceń:

1. Sprawdza nazwę polecenia.
2. Wywołania sendCommandResponse wysyłające odpowiedź z powrotem do usługi IoT Central. Ta odpowiedź obejmuje kod odpowiedzi 202, wskazując na oczekujące wyniki.
3. Kończy długotrwałą operację.
4. Używa zgłaszanej właściwości o tej samej nazwie co polecenie, aby poinformować usługę IoT Central, że polecenie zostało ukończone.

Poniższy zrzut ekranu przedstawia interfejs użytkownika usługi IoT Central po odebraniu aktualizacji właściwości, która wskazuje, że polecenie zostało ukończone:

Polecenia w trybie offline

W tej sekcji pokazano, jak urządzenie obsługuje polecenie offline. Jeśli urządzenie jest w trybie online, może obsługiwać polecenie w trybie offline, gdy tylko zostanie odebrane. Jeśli urządzenie jest w trybie offline, obsługuje polecenie offline po następnym połączeniu z usługą IoT Central. Urządzenia nie mogą wysyłać wartości zwracanej w odpowiedzi na polecenie w trybie offline.

Uwaga / Notatka

Polecenia offline nie są częścią konwencji IoT Plug and Play. Usługa IoT Central ma własną konwencję implementowania poleceń offline.

Uwaga / Notatka

W tym artykule użyto Node.js dla uproszczenia.

Poniższy zrzut ekranu przedstawia polecenie w trybie offline o nazwie GenerateDiagnostics. Parametr żądania jest obiektem o właściwości datetime o nazwie StartTime i właściwości wyliczenia całkowitej o nazwie Bank:

Poniższy fragment kodu pokazuje, jak klient może nasłuchiwać poleceń w trybie offline i wyświetlać zawartość komunikatu:

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

Dane wyjściowe z poprzedniego fragmentu kodu pokazują ładunek z wartościami StartTime i Bank . Lista właściwości zawiera nazwę polecenia w elemencie listy nazwa-metody :

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

Uwaga / Notatka

Domyślny czas wygaśnięcia dla poleceń trybu offline wynosi 24 godziny, po upływie którego komunikat wygaśnie.

Polecenia na nieprzypisanych urządzeniach

Polecenia można wywoływać na urządzeniu, które nie jest przypisane do szablonu urządzenia. Aby wywołać polecenie na nieprzypisanym urządzeniu, przejdź do urządzenia w sekcji Urządzenia , wybierz pozycję Zarządzaj urządzeniem , a następnie polecenie. Wprowadź nazwę metody, ładunek i inne wymagane wartości. Poniższy zrzut ekranu przedstawia interfejs użytkownika używany do wywoływania polecenia:

Dalsze kroki

Teraz, gdy wiesz, jak używać poleceń w aplikacji usługi Azure IoT Central, zobacz Telemetria, właściwość i ładunki poleceń , aby dowiedzieć się więcej na temat parametrów poleceń i utworzyć i połączyć aplikację kliencką z aplikacją usługi Azure IoT Central , aby wyświetlić kompletne przykłady kodu w różnych językach.