Udostępnij za pośrednictwem

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

  • Artykuł

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 na usługę IoT Central po odebraniu polecenia, a następnie powiadom usługę IoT Central po zakończeniu długotrwałego polecenia .

Domyślnie polecenia oczekują, że urządzenie zostanie połączone i nie powiedzie się, jeśli urządzenie nie będzie możliwe. W przypadku wybrania opcji Kolejka , jeśli w interfejsie użytkownika szablonu urządzenia w trybie offline można kolejkować polecenie do momentu, gdy urządzenie zostanie przełączone 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ą po zakończeniu polecenia przez urządzenie. 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 raportu w szablonie urządzenia Termostat . To polecenie ma parametry żądania i odpowiedzi:

Screenshot showing Get Max Min Report command in Thermostat device template.

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

Pole opis
Wyświetlana nazwa Wartość polecenia używana na kafelkach pulpitu nawigacyjnego i formularzach urządzeń.
Nazwisko 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 Command.
Kolejka, jeśli jest w trybie offline Czy to polecenie ma być poleceniem offline .
opis Opis możliwości polecenia.
Komentarz Wszelkie komentarze dotyczące możliwości polecenia.
Żądanie Ładunek polecenia urządzenia.
Response Ładunek odpowiedzi polecenia 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.

Polecenia standardowe

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 można znaleźć w temacie Create and connect a client application to your Azure IoT Central application (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:

Screenshot showing how to view command payload for a standard command.

Uwaga

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 długotrwałym poleceniu urządzenie nie powoduje natychmiastowego ukończenia polecenia. 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

Długotrwałe polecenia nie są częścią konwencji IoT Plug and Play. Usługa 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

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 w celu onDeviceMethod skonfigurowania commandHandler metody . 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ź zawiera 202 kod odpowiedzi, aby wskazać 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:

Screenshot that shows long-running command finished.

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

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

Uwaga

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:

Screenshot that shows the UI for an offline command.

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

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:

Screenshot that shows an example of calling a command on an unassigned device.

Następne kroki

Teraz, gdy wiesz już, 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.