Udostępnij za pośrednictwem

Wysyłanie i odbieranie komunikatów z chmury do urządzenia

  • Artykuł

Azure IoT Hub to w pełni zarządzana usługa, która umożliwia komunikację dwukierunkową, w tym komunikaty z chmury do urządzenia (C2D) z zaplecza rozwiązania do milionów urządzeń.

W tym artykule opisano sposób użycia zestawów SDK usługi Azure IoT do tworzenia następujących typów aplikacji:

  • Aplikacje urządzeń, które odbierają komunikaty z chmury do urządzenia i obsługują je z kolejki obsługi komunikatów usługi IoT Hub.

  • Aplikacje zaplecza, które wysyłają komunikaty z chmury do urządzenia do jednego urządzenia za pośrednictwem kolejki obsługi komunikatów usługi IoT Hub.

Ten artykuł ma na celu uzupełnienie przykładów zestawu SDK z możliwością uruchamiania, do których odwołuje się ten artykuł.

Uwaga

Funkcje opisane w tym artykule są dostępne tylko w warstwie Standardowa usługi IoT Hub. Aby uzyskać więcej informacji na temat warstw podstawowej i standardowej/bezpłatnej usługi IoT Hub, zobacz Wybieranie odpowiedniej warstwy usługi IoT Hub dla rozwiązania.

Omówienie

Aby aplikacja urządzenia odbierała komunikaty z chmury do urządzenia, musi połączyć się z usługą IoT Hub, a następnie skonfigurować procedurę obsługi komunikatów w celu przetwarzania komunikatów przychodzących. Zestawy SDK urządzeń usługi Azure IoT Hub udostępniają klasy i metody, których urządzenie może używać do odbierania i obsługi komunikatów z usługi. W tym artykule omówiono kluczowe elementy dowolnej aplikacji urządzenia, która odbiera komunikaty, w tym:

  • Deklarowanie obiektu klienta urządzenia
  • Łączenie z usługą IoT Hub
  • Pobieranie komunikatów z kolejki komunikatów usługi IoT Hub
  • Przetwarzanie komunikatu i wysyłanie potwierdzenia z powrotem do usługi IoT Hub
  • Konfigurowanie zasad ponawiania próby odbierania komunikatów

Aby aplikacja zaplecza wysyłała komunikaty z chmury do urządzenia, musi połączyć się z usługą IoT Hub i wysyłać komunikaty za pośrednictwem kolejki komunikatów usługi IoT Hub. Zestawy SDK usługi Azure IoT Hub udostępniają klasy i metody, których aplikacja może używać do wysyłania komunikatów do urządzeń. W tym artykule omówiono kluczowe elementy każdej aplikacji, która wysyła komunikaty do urządzeń, w tym:

  • Deklarowanie obiektu klienta usługi
  • Łączenie z usługą IoT Hub
  • Kompilowanie i wysyłanie komunikatu
  • Odbieranie opinii o dostawie
  • Konfigurowanie zasad ponawiania próby wysyłania komunikatów

Omówienie kolejki komunikatów

Aby zrozumieć obsługę komunikatów z chmury na urządzenie, ważne jest, aby zrozumieć pewne podstawy dotyczące działania kolejek komunikatów urządzenia usługi IoT Hub.

Komunikaty z chmury do urządzenia wysyłane z aplikacji zaplecza rozwiązania do urządzenia IoT są kierowane za pośrednictwem usługi IoT Hub. Nie ma bezpośredniej komunikacji komunikacji równorzędnej między aplikacją zaplecza rozwiązania a urządzeniem docelowym. Usługa IoT Hub umieszcza przychodzące komunikaty w kolejce komunikatów, które są gotowe do pobrania przez docelowe urządzenia IoT.

Aby zagwarantować co najmniej jednokrotne dostarczanie komunikatów, usługa IoT Hub utrzymuje komunikaty z chmury do urządzenia w kolejkach poszczególnych urządzeń. Urządzenia muszą jawnie potwierdzić ukończenie komunikatu, zanim usługa IoT Hub usunie komunikat z kolejki. Takie podejście gwarantuje odporność na łączność i awarie urządzeń.

Gdy usługa IoT Hub umieszcza komunikat w kolejce komunikatów urządzenia, ustawia stan komunikatu na Enqueued. Gdy wątek urządzenia pobiera komunikat z kolejki, usługa IoT Hub blokuje komunikat, ustawiając stan komunikatu na Niewidoczny. Ten stan uniemożliwia innym wątkom na urządzeniu przetwarzanie tego samego komunikatu. Gdy wątek urządzenia pomyślnie ukończy przetwarzanie komunikatu, powiadamia centrum IoT Hub, a następnie usługa IoT Hub ustawia stan komunikatu na Ukończono.

Aplikacja urządzenia, która pomyślnie odbiera i przetwarza komunikat, zostanie wyświetlony komunikat Complete the message (Ukończ komunikat). Jednak w razie potrzeby urządzenie może również:

  • Odrzuć komunikat, co powoduje, że usługa IoT Hub ustawiła ją na stan Utracony. Urządzenia łączące się za pośrednictwem protokołu transportu telemetrii kolejkowania komunikatów (MQTT) nie mogą odrzucać komunikatów z chmury do urządzenia.
  • Porzucanie komunikatu, co powoduje, że usługa IoT Hub umieścić komunikat z powrotem w kolejce z ustawionym stanem komunikatu na wartość Enqueued. Urządzenia łączące się za pośrednictwem protokołu MQTT nie mogą porzucić komunikatów chmura-urządzenie.

Aby uzyskać więcej informacji na temat cyklu życia komunikatów chmury do urządzenia i sposobu przetwarzania komunikatów z chmury do urządzenia w usłudze IoT Hub, zobacz Wysyłanie komunikatów z chmury do urządzenia z centrum IoT Hub.

Odbieranie komunikatów z chmury do urządzenia

W tej sekcji opisano sposób odbierania komunikatów z chmury do urządzenia przy użyciu klasy DeviceClient w zestawie SDK usługi Azure IoT dla platformy .NET.

Istnieją dwie opcje, których aplikacja kliencka urządzenia może używać do odbierania komunikatów:

  • Sondowanie: aplikacja urządzenia sprawdza nowe komunikaty usługi IoT Hub przy użyciu pętli kodu (na przykład while pętli lub for ). Pętla jest wykonywana stale, sprawdzając komunikaty.
  • Wywołanie zwrotne: aplikacja urządzenia konfiguruje asynchroniczną metodę obsługi komunikatów, która jest wywoływana natychmiast po nadejściu komunikatu.

Deklarowanie obiektu DeviceClient

Element DeviceClient zawiera metody i właściwości niezbędne do odbierania komunikatów z usługi IoT Hub.

Na przykład:

static DeviceClient deviceClient;

Podaj parametry połączenia

Podaj podstawowe parametry połączenia usługi IoT Hub i identyfikator urządzenia, aby DeviceClient użyć metody CreateFromConnectionString. Oprócz wymaganych parametry połączenia podstawowych usługi CreateFromConnectionString IoT Hub można przeciążyć metodę, aby uwzględnić następujące parametry opcjonalne:

  • transportType - Protokół transportowy: odmiany protokołu HTTP w wersji 1, AMQP lub MQTT. Wartość domyślna to AMQP. Aby wyświetlić wszystkie dostępne wartości, zobacz TransportType, wyliczenie.
  • transportSettings - Interfejs używany do definiowania różnych ustawień specyficznych dla transportu dla DeviceClient i ModuleClient. Aby uzyskać więcej informacji, zobacz ITransportSettings, interfejs.
  • ClientOptions — Opcje umożliwiające konfigurację wystąpienia klienta urządzenia lub modułu podczas inicjowania.

W tym przykładzie wywołano metodę CreateFromConnectionString DeviceClient definiowania ustawień centrum IoT i identyfikatora urządzenia.

static string connectionString = "{your IoT hub connection string}";
static string deviceID = "{your device ID}";
deviceClient = DeviceClient.CreateFromConnectionString(connectionString,deviceID);

Sondowanie

Sondowanie używa funkcji ReceiveAsync do sprawdzania komunikatów.

Wywołanie metody ReceiveAsync może przyjąć następujące formy:

  • ReceiveAsync() — Przed kontynuowaniem poczekaj domyślny okres limitu czasu dla komunikatu.
  • ReceiveAsync (Timespan) — Odbieranie komunikatu z kolejki urządzenia przy użyciu określonego limitu czasu.
  • ReceiveAsync (CancellationToken) — Odbieranie komunikatu z kolejki urządzenia przy użyciu tokenu anulowania. W przypadku korzystania z tokenu anulowania domyślny okres limitu czasu nie jest używany.

W przypadku korzystania z typu transportu HTTP 1 zamiast protokołu MQTT lub AMQP ReceiveAsync metoda zwraca natychmiast. Obsługiwany wzorzec dla komunikatów z chmury do urządzenia z protokołem HTTP 1 jest sporadycznie połączonych urządzeń, które sprawdzają komunikaty rzadko (co najmniej co 25 minut). Wysłanie większej liczby żądań HTTP 1 powoduje ograniczenie żądań w usłudze IoT Hub. Aby uzyskać więcej informacji na temat różnic między obsługą protokołów MQTT, AMQP i HTTP 1, zobacz Wskazówki dotyczące komunikacji między chmurą a urządzeniem i Wybieranie protokołu komunikacyjnego.

CompleteAsync, metoda

Gdy urządzenie otrzyma komunikat, aplikacja urządzenia wywołuje metodę CompleteAsync , aby powiadomić usługę IoT Hub o pomyślnym przetworzeniu komunikatu i bezpiecznie usunąć komunikat z kolejki urządzeń usługi IoT Hub. Urządzenie powinno wywołać tę metodę po pomyślnym zakończeniu przetwarzania niezależnie od używanego protokołu transportowego.

Porzucanie, odrzucanie lub przekroczenie limitu czasu komunikatu

W przypadku protokołów AMQP i HTTP w wersji 1, ale nie protokołu MQTT, urządzenie może również:

  • Porzucanie komunikatu przez wywołanie metody AbandonAsync. Dzięki temu usługa IoT Hub zachowuje komunikat w kolejce urządzenia na potrzeby przyszłego użycia.
  • Odrzuć komunikat, wywołując polecenie RejectAsync. Spowoduje to trwałe usunięcie komunikatu z kolejki urządzenia.

Jeśli wystąpi coś, co uniemożliwia ukończenie, porzucenie lub odrzucenie komunikatu przez urządzenie, usługa IoT Hub otrzyma komunikat po upływie ustalonego limitu czasu, ponownie w kolejce komunikat do dostarczenia. Z tego powodu logika przetwarzania komunikatów w aplikacji urządzenia musi być idempotentna, dzięki czemu odbieranie tego samego komunikatu wielokrotnie generuje ten sam wynik.

Aby uzyskać więcej informacji na temat cyklu życia komunikatów chmury do urządzenia i sposobu przetwarzania komunikatów z chmury do urządzenia w usłudze IoT Hub, zobacz Wysyłanie komunikatów z chmury do urządzenia z centrum IoT Hub.

Pętla sondowania

Korzystając z sondowania, aplikacja używa pętli kodu, która wielokrotnie wywołuje ReceiveAsync metodę w celu sprawdzenia nowych komunikatów do momentu zatrzymania.

Jeśli używasz ReceiveAsync wartości limitu czasu lub domyślnego limitu czasu, w pętli każde wywołanie ReceiveAsync czeka na określony okres limitu czasu. Jeśli ReceiveAsync wartość zostanie upłynął, null zostanie zwrócona wartość, a pętla będzie kontynuowana.

Po odebraniu komunikatu obiekt Task jest zwracany przez ReceiveAsync element , który powinien zostać przekazany do metody CompleteAsync. Wywołanie w celu CompleteAsync powiadomienia usługi IoT Hub o usunięciu określonego komunikatu z kolejki komunikatów na podstawie parametru Task .

W tym przykładzie pętla wywołuje do ReceiveAsync momentu odebrania komunikatu lub zatrzymania pętli sondowania.

static bool stopPolling = false;

while (!stopPolling)
{
   // Check for a message. Wait for the default DeviceClient timeout period.
   using Message receivedMessage = await _deviceClient.ReceiveAsync();

   // Continue if no message was received
   if (receivedMessage == null)
   {
      continue;
   }
   else  // A message was received
   {
      // Print the message received
      Console.WriteLine($"{DateTime.Now}> Polling using ReceiveAsync() - received message with Id={receivedMessage.MessageId}");
      PrintMessage(receivedMessage);

      // Notify IoT Hub that the message was received. IoT Hub will delete the message from the message queue.
      await _deviceClient.CompleteAsync(receivedMessage);
      Console.WriteLine($"{DateTime.Now}> Completed C2D message with Id={receivedMessage.MessageId}.");
   }

   // Check to see if polling loop should end
   stopPolling = ShouldPollingstop ();
}

Oddzwanianie

Aby odbierać komunikaty z chmury do urządzenia w aplikacji urządzenia, aplikacja musi połączyć się z usługą IoT Hub i skonfigurować odbiornik wywołania zwrotnego w celu przetwarzania komunikatów przychodzących. Przychodzące komunikaty do urządzenia są odbierane z kolejki komunikatów usługi IoT Hub.

Za pomocą wywołania zwrotnego aplikacja urządzenia konfiguruje metodę obsługi komunikatów przy użyciu metody SetReceiveMessageHandlerAsync. Procedura obsługi komunikatów jest wywoływana, a następnie odbierany jest komunikat. Utworzenie metody wywołania zwrotnego w celu odbierania komunikatów eliminuje konieczność ciągłego sondowania dla odebranych komunikatów.

Wywołanie zwrotne jest dostępne tylko przy użyciu następujących protokołów:

  • Mqtt
  • Mqtt_WebSocket_Only
  • Mqtt_Tcp_Only
  • Amqp
  • Amqp_WebSocket_Only
  • Amqp_Tcp_only

Opcja Http1 protokołu nie obsługuje wywołań zwrotnych, ponieważ metody zestawu SDK musiałyby mimo to sondować pod kątem odebranych komunikatów, co powoduje pokonanie reguły wywołania zwrotnego.

W tym przykładzie SetReceiveMessageHandlerAsync konfiguruje metodę obsługi wywołania zwrotnego o nazwie OnC2dMessageReceivedAsync, która jest wywoływana za każdym razem, gdy zostanie odebrany komunikat.

// Subscribe to receive C2D messages through a callback (which isn't supported over HTTP).
await deviceClient.SetReceiveMessageHandlerAsync(OnC2dMessageReceivedAsync, deviceClient);
Console.WriteLine($"\n{DateTime.Now}> Subscribed to receive C2D messages over callback.");

Zasady ponawiania próby odbierania komunikatów

Zasady ponawiania komunikatów klienta urządzenia można zdefiniować przy użyciu elementu DeviceClient.SetRetryPolicy.

Limit czasu ponawiania próby komunikatu jest przechowywany we właściwości DeviceClient.OperationTimeoutInMilliseconds .

Przykład komunikatu odbierania zestawu SDK

Zestaw .NET/C# SDK zawiera przykład Odbieranie komunikatów, który zawiera metody odbierania komunikatów opisane w tej sekcji.

Wysyłanie komunikatów z chmury do urządzeń

W tej sekcji opisano podstawowy kod służący do wysyłania komunikatu z aplikacji zaplecza rozwiązania do urządzenia IoT przy użyciu klasy ServiceClient w zestawie SDK usługi Azure IoT dla platformy .NET. Jak wspomniano wcześniej, aplikacja zaplecza rozwiązania łączy się z usługą IoT Hub i komunikaty są wysyłane do usługi IoT Hub zakodowanej przy użyciu urządzenia docelowego. Usługa IoT Hub przechowuje komunikaty przychodzące do kolejki komunikatów, a komunikaty są dostarczane z kolejki komunikatów usługi IoT Hub do urządzenia docelowego.

Aplikacja zaplecza rozwiązania może również żądać i odbierać opinie dotyczące dostarczania komunikatu wysyłanego do usługi IoT Hub przeznaczonego do dostarczania urządzeń za pośrednictwem kolejki komunikatów.

Deklarowanie obiektu ServiceClient

Obiekt ServiceClient zawiera metody i właściwości niezbędne do wysyłania komunikatów z aplikacji za pośrednictwem usługi IoT Hub do urządzenia.

static ServiceClient serviceClient;

Podaj parametry połączenia

Podaj podstawowe parametry połączenia usługi IoT Hub, aby ServiceClient użyć metody CreateFromConnectionString. Oprócz wymaganych parametry połączenia podstawowych usługi CreateFromConnectionString IoT Hub można przeciążyć metodę, aby uwzględnić następujące parametry opcjonalne:

  • Usługa transportType - Amqp lub Amqp_WebSocket_Only.
  • transportSettings — Ustawienia protokołu AMQP i serwera proxy HTTP dla klienta usługi.
  • ServiceClientOptions - Opcje, które umożliwiają konfigurację wystąpienia klienta usługi podczas inicjowania. Aby uzyskać więcej informacji, zobacz ServiceClientOptions.

W tym przykładzie obiekt jest tworzony ServiceClient przy użyciu parametry połączenia usługi IoT Hub.

static string connectionString = "{your iot hub connection string}";
serviceClient = ServiceClient.CreateFromConnectionString(connectionString);

Wysyłanie asynchronicznego komunikatu chmury do urządzenia

Użyj metody sendAsync , aby wysłać do urządzenia komunikat asynchroniczny z aplikacji za pośrednictwem chmury (IoT Hub). Wywołanie jest wykonywane przy użyciu protokołu AMQP.

sendAsync używa następujących parametrów:

  • deviceID — identyfikator ciągu urządzenia docelowego.
  • message - Komunikat chmura-urządzenie. Komunikat jest typu Komunikat i można odpowiednio sformatować.
  • timeout— opcjonalna wartość limitu czasu. Wartość domyślna to jedna minuta, jeśli nie zostanie określona.

Ten przykład wysyła komunikat testowy do urządzenia docelowego z 10-sekundową wartością limitu czasu.

string targetDevice = "Device-1";
static readonly TimeSpan operationTimeout = TimeSpan.FromSeconds(10);
var commandMessage = new
Message(Encoding.ASCII.GetBytes("Cloud to device message."));
await serviceClient.SendAsync(targetDevice, commandMessage, operationTimeout);

Odbieranie opinii o dostawie

Program wysyłający może zażądać potwierdzenia dostarczenia (lub wygaśnięcia) z usługi IoT Hub dla każdego komunikatu z chmury do urządzenia. Ta opcja umożliwia programowi wysyłającego korzystanie z logiki informowania, ponawiania próby lub kompensacji. Pełny opis operacji i właściwości opinii o wiadomościach opisano w sekcji Opinie o wiadomościach.

Aby otrzymywać opinie dotyczące dostarczania wiadomości:

  • feedbackReceiver Tworzenie obiektu
  • Wysyłanie komunikatów przy użyciu parametru Ack
  • Poczekaj, aż otrzymasz opinię

Tworzenie obiektu feedbackReceiver

Wywołaj metodę GetFeedbackReceiver, aby utworzyć obiekt FeedbackReceiver. FeedbackReceiver zawiera metody, których usługi mogą używać do wykonywania operacji odbierania opinii.

var feedbackReceiver = serviceClient.GetFeedbackReceiver();

Wysyłanie komunikatów przy użyciu parametru Ack

Każda wiadomość musi zawierać wartość właściwości potwierdzenia dostawy Ack w celu otrzymania opinii o dostarczeniu. Właściwość Ack może być jedną z następujących wartości:

  • none (wartość domyślna): nie jest generowany żaden komunikat z opiniami.

  • Positive: otrzymuj wiadomość zwrotną, jeśli wiadomość została ukończona.

  • Negative: otrzymuj wiadomość zwrotną, jeśli komunikat wygasł (lub osiągnięto maksymalną liczbę dostaw) bez ukończenia przez urządzenie.

  • Full: opinie dotyczące wyników i Positive Negative .

W tym przykładzie właściwość jest ustawiona Ack na Full, żądając zarówno pozytywnej, jak i negatywnej opinii dotyczącej dostarczania komunikatów dla jednej wiadomości.

var commandMessage = new
Message(Encoding.ASCII.GetBytes("Cloud to device message."));
commandMessage.Ack = DeliveryAcknowledgement.Full;
await serviceClient.SendAsync(targetDevice, commandMessage);

Poczekaj, aż otrzymasz opinię

Zdefiniuj element CancellationToken. Następnie w pętli wywołaj metodę ReceiveAsync wielokrotnie, sprawdzając komunikaty zwrotne dotyczące dostarczania. Każde wywołanie ReceiveAsync czeka na limit czasu zdefiniowany dla ServiceClient obiektu.

  • ReceiveAsync Jeśli limit czasu wygaśnie bez odebranego komunikatu, ReceiveAsync zwraca wartość , null a pętla będzie kontynuowana.
  • Jeśli zostanie odebrany komunikat z informacją zwrotną, obiekt Task zostanie zwrócony przez ReceiveAsync obiekt , który powinien zostać przekazany do metody CompleteAsync wraz z tokenem anulowania. Wywołanie w celu CompleteAsync usunięcia określonego wysłanego komunikatu z kolejki komunikatów na podstawie parametru Task .
  • W razie potrzeby kod odbioru może wywołać metodę AbandonAsync , aby ponownie umieścić komunikat wysyłania w kolejce.
var feedbackReceiver = serviceClient.GetFeedbackReceiver();

// Define the cancellation token.
CancellationTokenSource source = new CancellationTokenSource();
CancellationToken token = source.Token;
// Call ReceiveAsync, passing the token. Wait for the timout period.
var feedbackBatch = await feedbackReceiver.ReceiveAsync(token);
if (feedbackBatch == null) continue;

W tym przykładzie przedstawiono metodę obejmującą te kroki.

private async static void ReceiveFeedbackAsync()
{
      var feedbackReceiver = serviceClient.GetFeedbackReceiver();

      Console.WriteLine("\nReceiving c2d feedback from service");
      while (true)
      {
         // Check for messages, wait for the timeout period.
         var feedbackBatch = await feedbackReceiver.ReceiveAsync();
         // Continue the loop if null is received after a timeout.
         if (feedbackBatch == null) continue;

         Console.ForegroundColor = ConsoleColor.Yellow;
         Console.WriteLine("Received feedback: {0}",
            string.Join(", ", feedbackBatch.Records.Select(f => f.StatusCode)));
         Console.ResetColor();

         await feedbackReceiver.CompleteAsync(feedbackBatch);
      }
   }

Zwróć uwagę, że ten wzorzec odbierania opinii jest podobny do wzorca używanego do odbierania komunikatów z chmury do urządzenia w aplikacji urządzenia.

Ponowne nawiązywanie połączenia klienta usługi

W przypadku wystąpienia wyjątku klient usługi przekazuje te informacje do aplikacji wywołującej. W tym momencie zaleca się sprawdzenie szczegółów wyjątku i podjęcie niezbędnych działań.

Na przykład:

  • Jeśli jest to wyjątek sieciowy, możesz ponowić próbę wykonania operacji.
  • Jeśli jest to wyjątek zabezpieczeń (nieautoryzowany wyjątek), sprawdź poświadczenia i upewnij się, że są aktualne.
  • Jeśli jest to wyjątek ograniczania przepustowości/limitu przydziału, monitoruj i/lub modyfikuj częstotliwość wysyłania żądań lub zaktualizuj jednostkę skalowania wystąpienia centrum. Aby uzyskać szczegółowe informacje, zobacz Limity przydziału i ograniczanie przepustowości usługi IoT Hub.

Zasady ponawiania wysyłania komunikatów

Zasady ServiceClient ponawiania komunikatów można zdefiniować przy użyciu elementu ServiceClient.SetRetryPolicy.

Przykład wysyłania komunikatu z zestawu SDK

Zestaw .NET/C# SDK zawiera przykład klienta usługi, który zawiera metody wysyłania komunikatów opisane w tej sekcji.

Odbieranie komunikatów z chmury do urządzenia

W tej sekcji opisano sposób odbierania komunikatów z chmury do urządzenia przy użyciu klasy DeviceClient z zestawu AZURE IoT SDK dla języka Java.

Aby aplikacja urządzenia oparta na języku Java odbierała komunikaty z chmury do urządzenia, musi połączyć się z usługą IoT Hub, a następnie skonfigurować odbiornik wywołania zwrotnego i procedurę obsługi komunikatów w celu przetwarzania komunikatów przychodzących z usługi IoT Hub. Aplikacja urządzenia powinna również mieć możliwość wykrywania rozłączeń i obsługi ich w przypadku przerwania połączenia komunikatów urządzenia z usługą IoT Hub.

Importowanie bibliotek zestawu Java SDK usługi Azure IoT

Kod, do których odwołuje się ten artykuł, używa tych bibliotek zestawu SDK.

import com.microsoft.azure.sdk.iot.device.*;
import com.microsoft.azure.sdk.iot.device.exceptions.IotHubClientException;
import com.microsoft.azure.sdk.iot.device.transport.IotHubConnectionStatus;

Deklarowanie obiektu DeviceClient

Wystąpienie obiektu DeviceClient wymaga następujących parametrów:

  • connString — parametry połączenia urządzenia IoT. Parametry połączenia jest zestawem par klucz-wartość, które są oddzielone ciągiem ";", z kluczami i wartościami oddzielonymi znakami "=". Powinien zawierać wartości dla tych kluczy: HostName, DeviceId, and SharedAccessKey.
  • Protokół transportu — DeviceClient połączenie może używać jednego z następujących protokołów transportu IoTHubClientProtocol . AMQP jest najbardziej wszechstronny, umożliwia częste sprawdzanie komunikatów i umożliwia odrzucenie i anulowanie komunikatów. Protokół MQTT nie obsługuje odrzucania komunikatów ani porzucania metod:
    • AMQPS
    • AMQPS_WS
    • HTTPS
    • MQTT
    • MQTT_WS

Na przykład:

static string connectionString = "{a device connection string}";
static protocol = IotHubClientProtocol.AMQPS;
DeviceClient client = new DeviceClient(connectionString, protocol);

Ustawianie metody wywołania zwrotnego komunikatów

Użyj metody setMessageCallback, aby zdefiniować metodę obsługi komunikatów, która jest powiadamiana o odebraniu komunikatu z usługi IoT Hub.

setMessageCallback zawiera następujące parametry:

  • callback - Nazwa metody wywołania zwrotnego. Może to być null.
  • context- Opcjonalny kontekst typu object. Użyj null polecenia , jeśli nie określono.

W tym przykładzie callback metoda o nazwie MessageCallback bez parametru kontekstu jest przekazywana do setMessageCallback.

client.setMessageCallback(new MessageCallback(), null);

Tworzenie procedury obsługi wywołania zwrotnego komunikatów

Procedura obsługi komunikatów wywołania zwrotnego odbiera i przetwarza przychodzący komunikat przekazywany z kolejki komunikatów usługi IoT Hub.

W tym przykładzie program obsługi komunikatów przetwarza komunikat przychodzący, a następnie zwraca element IotHubMessageResult.COMPLETE. Wartość zwracana IotHubMessageResult.COMPLETE powiadamia usługę IoT Hub o pomyślnym przetworzeniu komunikatu i bezpiecznym usunięciu komunikatu z kolejki urządzenia. Urządzenie powinno zostać zwrócone IotHubMessageResult.COMPLETE po pomyślnym zakończeniu przetwarzania, powiadamiając usługę IoT Hub o tym, że komunikat powinien zostać usunięty z kolejki komunikatów, niezależnie od używanego protokołu.

  protected static class MessageCallback implements com.microsoft.azure.sdk.iot.device.MessageCallback
  {
      public IotHubMessageResult onCloudToDeviceMessageReceived(Message msg, Object context)
      {
          System.out.println(
                  "Received message with content: " + new String(msg.getBytes(), Message.DEFAULT_IOTHUB_MESSAGE_CHARSET));
          // Notify IoT Hub that the message
          return IotHubMessageResult.COMPLETE;
      }
  }

Opcje porzucania i odrzucania komunikatów

Chociaż duża liczba przychodzących komunikatów na urządzeniu powinna zostać pomyślnie odebrana i spowodować IotHubMessageResult.COMPLETE, że konieczne może być porzucenie lub odrzucenie komunikatu.

  • W przypadku protokołów AMQP i HTTPS, ale nie MQTT, aplikacja może:
    • IotHubMessageResult.ABANDON komunikat. Usługa IoT Hub ponownie zapisuje ją w kolejce i wysyła ją ponownie później.
    • IotHubMessageResult.REJECT komunikat. Usługa IoT Hub nie kolejkuje ponownie komunikatu i trwale usuwa komunikat z kolejki komunikatów.
  • Klienci korzystający z MQTT programu lub MQTT_WS nie mogą ABANDON ani REJECT komunikatów.

Jeśli wystąpi coś, co uniemożliwia ukończenie, porzucenie lub odrzucenie komunikatu przez urządzenie, usługa IoT Hub otrzyma komunikat po upływie ustalonego limitu czasu, ponownie w kolejce komunikat do dostarczenia. Z tego powodu logika przetwarzania komunikatów w aplikacji urządzenia musi być idempotentna, dzięki czemu odbieranie tego samego komunikatu wielokrotnie generuje ten sam wynik.

Aby uzyskać więcej informacji na temat cyklu życia komunikatów chmury do urządzenia i sposobu przetwarzania komunikatów z chmury do urządzenia w usłudze IoT Hub, zobacz Wysyłanie komunikatów z chmury do urządzenia z centrum IoT Hub.

Uwaga

Jeśli używasz protokołu HTTPS zamiast protokołu MQTT lub AMQP jako transportu, wystąpienie DeviceClient sprawdza, czy komunikaty z usługi IoT Hub są rzadko (co najmniej co 25 minut). Aby uzyskać więcej informacji na temat różnic między obsługą protokołów MQTT, AMQP i HTTPS, zobacz Wskazówki dotyczące komunikacji między chmurą a urządzeniem i Wybieranie protokołu komunikacyjnego.

Tworzenie metody wywołania zwrotnego stanu komunikatu

Aplikacja może użyć metody registerConnectionStatusChangeCallback, aby zarejestrować metodę wywołania zwrotnego, która ma zostać wykonana po zmianie stanu połączenia urządzenia. Dzięki temu aplikacja może wykryć zaniżone połączenie komunikatów i spróbować ponownie nawiązać połączenie.

W tym przykładzie IotHubConnectionStatusChangeCallbackLogger jest rejestrowana jako metoda zmiany stanu połączenia wywołania zwrotnego.

client.registerConnectionStatusChangeCallback(new IotHubConnectionStatusChangeCallbackLogger(), new Object());

Wywołanie zwrotne jest wyzwalane i przekazywane ConnectionStatusChangeContext obiekt.

Wywołaj metodę connectionStatusChangeContext.getNewStatus() , aby uzyskać bieżący stan połączenia.

IotHubConnectionStatus status = connectionStatusChangeContext.getNewStatus();

Zwrócony stan połączenia może być jedną z następujących wartości:

  • IotHubConnectionStatus.DISCONNECTED
  • IotHubConnectionStatus.DISCONNECTED_RETRYING
  • IotHubConnectionStatus.CONNECTED

Wywołaj metodę connectionStatusChangeContext.getNewStatusReason() , aby uzyskać przyczynę zmiany stanu połączenia.

IotHubConnectionStatusChangeReason statusChangeReason = connectionStatusChangeContext.getNewStatusReason();

Wywołaj metodę connectionStatusChangeContext.getCause() , aby znaleźć przyczynę zmiany stanu połączenia. getCause() może zwrócić informację null , jeśli nie są dostępne żadne informacje.

Throwable throwable = connectionStatusChangeContext.getCause();
if (throwable != null)
    throwable.printStackTrace();

Zobacz przykład HandleMessages wymieniony w sekcji przykładowej komunikatu odbieranego przez zestaw SDK w tym artykule, aby zapoznać się z kompletnym przykładem przedstawiającym sposób wyodrębniania stanu zmiany stanu stanu zmiany stanu stanu zmiany stanu stanu zmiany stanu zmiany stanu stanu zmiany stanu stanu i przyczyny zmiany stanu oraz kontekstu stanu urządzenia.

Otwieranie połączenia między urządzeniem a usługą IoT Hub

Użyj opcji otwórz , aby utworzyć połączenie między urządzeniem i usługą IoT Hub. Urządzenie może teraz asynchronicznie wysyłać i odbierać komunikaty do i z usługi IoT Hub. Jeśli klient jest już otwarty, metoda nic nie robi.

client.open(true);

Przykład komunikatu odbierania zestawu SDK

HandleMessages: przykładowa aplikacja urządzenia dołączona do zestawu SDK usługi Microsoft Azure IoT dla języka Java, która łączy się z centrum IoT i odbiera komunikaty z chmury do urządzenia.

Wysyłanie komunikatów z chmury do urządzeń

W tej sekcji opisano sposób wysyłania komunikatu z chmury do urządzenia przy użyciu klasy ServiceClient z zestawu AZURE IoT SDK dla języka Java. Aplikacja zaplecza rozwiązania łączy się z usługą IoT Hub i komunikaty są wysyłane do usługi IoT Hub zakodowanej przy użyciu urządzenia docelowego. Usługa IoT Hub przechowuje komunikaty przychodzące do kolejki komunikatów, a komunikaty są dostarczane z kolejki komunikatów usługi IoT Hub do urządzenia docelowego.

Aplikacja zaplecza rozwiązania może również żądać i odbierać opinie dotyczące dostarczania komunikatu wysyłanego do usługi IoT Hub przeznaczonego do dostarczania urządzeń za pośrednictwem kolejki komunikatów.

Dodawanie instrukcji zależności

Dodaj zależność, aby używać pakietu iothub-java-service-client w aplikacji do komunikowania się z usługą centrum IoT:

<dependency>
  <groupId>com.microsoft.azure.sdk.iot</groupId>
  <artifactId>iot-service-client</artifactId>
  <version>1.7.23</version>
</dependency>

Dodawanie instrukcji importu

Dodaj te instrukcje importowania , aby użyć zestawu SDK java usługi Azure IoT i procedury obsługi wyjątków.

import com.microsoft.azure.sdk.iot.service.*;
import java.io.IOException;
import java.net.URISyntaxException;

Definiowanie protokołu połączenia

Użyj elementu IotHubServiceClientProtocol , aby zdefiniować protokół warstwy aplikacji używany przez klienta usługi do komunikowania się z usługą IoT Hub.

IotHubServiceClientProtocol akceptuje tylko wyliczenie AMQPS lub AMQPS_WS .

private static final IotHubServiceClientProtocol protocol =    
    IotHubServiceClientProtocol.AMQPS;

Tworzenie obiektu ServiceClient

Utwórz obiekt ServiceClient, podając parametry połączenia i protokół usługi Iot Hub.

private static final String connectionString = "{yourhubconnectionstring}";
private static final ServiceClient serviceClient (connectionString, protocol);

Otwieranie połączenia między aplikacją a usługą IoT Hub

otwórz połączenie nadawcy AMQP. Ta metoda tworzy połączenie między aplikacją a usługą IoT Hub.

serviceClient.open();

Otwieranie odbiornika opinii w celu uzyskania opinii dotyczącej dostarczania komunikatów

Możesz użyć elementu FeedbackReceiver , aby uzyskać wysyłanie wiadomości do opinii usługi IoT Hub. A FeedbackReceiver jest wyspecjalizowanym odbiornikiem, którego Receive metoda zwraca wartość FeedbackBatch zamiast Message.

W tym przykładzie FeedbackReceiver obiekt jest tworzony, a instrukcja jest wywoływana w open() celu oczekiwania na opinię.

FeedbackReceiver feedbackReceiver = serviceClient
  .getFeedbackReceiver();
if (feedbackReceiver != null) feedbackReceiver.open();

Dodawanie właściwości komunikatu

Opcjonalnie możesz użyć właściwości setProperties , aby dodać właściwości komunikatu. Te właściwości są uwzględniane w komunikacie wysyłanym do urządzenia i mogą zostać wyodrębnione przez aplikację urządzenia po otrzymaniu.

Map<String, String> propertiesToSend = new HashMap<String, String>();
propertiesToSend.put(messagePropertyKey,messagePropertyKey);
messageToSend.setProperties(propertiesToSend);

Tworzenie i wysyłanie komunikatu asynchronicznego

Obiekt Message przechowuje wiadomość do wysłania. W tym przykładzie jest dostarczany komunikat "Chmura do urządzenia".

Użyj polecenia setDeliveryAcknowledgement , aby zażądać dostarczenia/nie dostarczenia do potwierdzenia kolejki komunikatów usługi IoT Hub. W tym przykładzie żądane potwierdzenie to Full, dostarczone lub nie dostarczone.

Użyj polecenia SendAsync , aby wysłać asynchroniczny komunikat z klienta do urządzenia. Alternatywnie można użyć Send metody (nie asynchronicznej), ale ta funkcja jest synchronizowana wewnętrznie, tak aby tylko jedna operacja wysyłania mogła być dozwolona naraz. Komunikat jest dostarczany z aplikacji do usługi IoT Hub. Usługa IoT Hub umieszcza komunikat w kolejce komunikatów gotowy do dostarczenia do urządzenia docelowego.

Message messageToSend = new Message("Cloud to device message.");
messageToSend.setDeliveryAcknowledgementFinal(DeliveryAcknowledgement.Full);
serviceClient.sendAsync(deviceId, messageToSend);

Odbieranie opinii dotyczącej dostarczania komunikatów

Po wysłaniu komunikatu z aplikacji aplikacja może wywołać metodę odbierania z wartością limitu czasu lub bez tego limitu czasu. Jeśli nie podano wartości limitu czasu, zostanie użyty domyślny limit czasu. Spowoduje to powrót obiektu FeedbackBatch , który zawiera właściwości opinii dotyczącej dostarczania komunikatów, które można zbadać.

W tym przykładzie tworzony jest odbiornik i wywołuje metodę FeedbackBatch getEnqueuedTimeUtc, wyświetlaną w kolejce komunikatu.

FeedbackBatch feedbackBatch = feedbackReceiver.receive(10000);
if (feedbackBatch != null) {
  System.out.println("Message feedback received, feedback time: "
    + feedbackBatch.getEnqueuedTimeUtc().toString());
}

Przykłady wiadomości wysyłanych przez zestaw SDK

  • Przykład klienta usługi — przykład wysyłania komunikatu, #1.

  • Przykład klienta usługi — przykład wysyłania komunikatu, #2.

Instalowanie biblioteki zestawu Azure IoT SDK

Przed wywołaniem dowolnego powiązanego kodu zainstaluj bibliotekę zestawu SDK azure-iot-device na maszynie dewelopera:

pip install azure-iot-device

Istnieją dwie klasy zestawu SDK języka Python używane do wysyłania komunikatów do i z urządzeń IoT. Metody obsługi komunikatów z tych klas opisano w sekcjach na tej stronie.

  • Klasa IoTHubDeviceClient zawiera metody tworzenia synchronicznego połączenia z urządzenia do usługi Azure IoT Hub i odbierania komunikatów z usługi IoT Hub.

  • Klasa IoTHubRegistryManager zawiera interfejsy API dla operacji menedżera rejestru usługi IoT Hub. W tym artykule metody z tej klasy pokazują, jak nawiązać połączenie z usługą IoT Hub i wysłać komunikat do urządzenia.

Odbieranie komunikatów z chmury do urządzenia

W tej sekcji opisano sposób odbierania komunikatów z chmury do urządzenia przy użyciu klasy IoTHubDeviceClient z zestawu AZURE IoT SDK dla języka Python.

Aby aplikacja urządzenia oparta na języku Python odbierała komunikaty z chmury do urządzenia, musi połączyć się z usługą IoT Hub, a następnie skonfigurować procedurę obsługi komunikatów zwrotnych w celu przetwarzania komunikatów przychodzących z usługi IoT Hub.

Importowanie obiektu IoTHubDeviceClient

Dodaj wiersz kodu, aby zaimportować IoTHubDeviceClient funkcje z zestawu AZURE.iot.device SDK.

from azure.iot.device import IoTHubDeviceClient

Łączenie klienta urządzenia

Utwórz wystąpienie klasy IoTHubDeviceClient, przekazując parametry połączenia usługi IoT Hub do create_from_connection_string. Spowoduje to utworzenie połączenia z urządzenia do usługi IoT Hub.

Alternatywnie możesz nawiązać połączenie z IoTHubDeviceClienturządzeniem przy użyciu jednej z następujących metod:

deviceConnectionString = "{your IoT hub connection string}";
client = IoTHubDeviceClient.create_from_connection_string ({deviceConnectionString})

Obsługa ponownego nawiązywania połączenia

IoTHubDeviceClient domyślnie podejmie próbę ponownego opublikowania porzuconego połączenia. Zachowanie ponownego IoTHubDeviceClient łączenia podlega connection_retry i connection_retry_interval parametrom.

Tworzenie procedury obsługi komunikatów

Utwórz funkcję obsługi komunikatów w celu przetwarzania przychodzących komunikatów na urządzeniu.

W tym przykładzie message_handler jest wywoływana po odebraniu komunikatu. Właściwości komunikatu (.items) są drukowane w konsoli przy użyciu pętli .

def message_handler(message):
    global RECEIVED_MESSAGES
    RECEIVED_MESSAGES += 1
    print("")
    print("Message received:")

    # print data from both system and application (custom) properties
    for property in vars(message).items():
        print ("    {}".format(property))

    print("Total calls received: {}".format(RECEIVED_MESSAGES))

Przypisywanie programu obsługi komunikatów

Użyj metody on_message_received, aby przypisać metodę obsługi komunikatów IoTHubDeviceClient do obiektu.

W tym przykładzie metoda obsługi komunikatów o nazwie message_handler jest dołączona do IoTHubDeviceClient client obiektu. Obiekt client czeka na odebranie komunikatu z chmury do urządzenia z usługi IoT Hub. Ten kod czeka do 300 sekund (5 minut) na komunikat lub kończy działanie w przypadku naciśnięcia klawiatury.

try:
    # Attach the handler to the client
    client.on_message_received = message_handler

    while True:
        time.sleep(300)
except KeyboardInterrupt:
    print("IoT Hub C2D Messaging device sample stopped")
finally:
    # Graceful exit
    print("Shutting down IoT Hub Client")
    client.shutdown()

Przykład komunikatu odbierania zestawu SDK

Odbieranie komunikatów — odbieranie komunikatów z chmury do urządzenia (C2D) wysyłanych z usługi Azure IoT Hub do urządzenia.

Wysyłanie komunikatów z chmury do urządzeń

W tej sekcji opisano sposób wysyłania komunikatu z chmury do urządzenia przy użyciu klasy IoTHubRegistryManager z zestawu AZURE IoT SDK dla języka Python. Aplikacja zaplecza rozwiązania łączy się z usługą IoT Hub i komunikaty są wysyłane do usługi IoT Hub zakodowanej przy użyciu urządzenia docelowego. Usługa IoT Hub przechowuje komunikaty przychodzące do kolejki komunikatów, a komunikaty są dostarczane z kolejki komunikatów usługi IoT Hub do urządzenia docelowego.

Importowanie obiektu IoTHubRegistryManager

Dodaj następującą import instrukcję. IoTHubRegistryManager zawiera interfejsy API dla operacji menedżera rejestru usługi IoT Hub.

from azure.iot.hub import IoTHubRegistryManager

Łączenie menedżera rejestru usługi IoT Hub

Utwórz wystąpienie obiektu IoTHubRegistryManager łączącego się z centrum IoT Hub, przekazując parametry połączenia usługi IoT Hub do from_connection_string.

IoTHubConnectionString = "{Primary connection string to an IoT hub}"
registry_manager = IoTHubRegistryManager.from_connection_string(IoTHubConnectionString)

Kompilowanie i wysyłanie komunikatu

Użyj send_c2d_message , aby wysłać komunikat za pośrednictwem chmury (IoT Hub) do urządzenia.

send_c2d_message używa następujących parametrów:

  • deviceID — identyfikator ciągu urządzenia docelowego.
  • message - Komunikat chmura-urządzenie. Komunikat jest typu str (ciąg).
  • properties- Opcjonalna kolekcja właściwości typu dict. Właściwości mogą zawierać właściwości aplikacji i właściwości systemu. Domyślna wartość to {}.

Ten przykład wysyła komunikat testowy do urządzenia docelowego.

# define the device ID
deviceID = "Device-1"

# define the message
message = "{\"c2d test message\"}"

# include optional properties
props={}
props.update(messageId = "message1")
props.update(prop1 = "test property-1")
props.update(prop1 = "test property-2")
prop_text = "Test message"
props.update(testProperty = prop_text)

# send the message through the cloud (IoT Hub) to the device
registry_manager.send_c2d_message(deviceID, message, properties=props)

Przykład wysyłania komunikatu z zestawu SDK

send_message.py — pokazuje, jak wysyłać komunikat z chmury do urządzenia.

Instalowanie pakietów obsługi komunikatów Node.js

Uruchom następujące polecenia, aby zainstalować pakiety azure-iot-device i azure-iothub na maszynie deweloperskiej:

npm install azure-iot-device --save
npm install azure-iothub --save

Pakiet azure-iot-device zawiera obiekty interfejsu z urządzeniami IoT. W tym artykule opisano Client kod klasy odbierający komunikaty z usługi IoT Hub.

Pakiet azure-iothub zawiera obiekty interfejsu z usługą IoT Hub. W tym artykule opisano Client kod klasy, który wysyła komunikat z aplikacji do urządzenia za pośrednictwem usługi IoT Hub.

Odbieranie komunikatów w aplikacji urządzenia

W tej sekcji opisano sposób odbierania komunikatów z chmury do urządzenia przy użyciu pakietu azure-iot-device w zestawie SDK usługi Azure IoT dla Node.js.

Aby aplikacja urządzenia oparta na Node.js odbierała komunikaty z chmury do urządzenia, musi połączyć się z usługą IoT Hub, a następnie skonfigurować odbiornik wywołania zwrotnego i procedurę obsługi komunikatów w celu przetwarzania komunikatów przychodzących z usługi IoT Hub. Aplikacja urządzenia powinna również mieć możliwość wykrywania rozłączeń i obsługi ich w przypadku przerwania połączenia komunikatów urządzenia z usługą IoT Hub.

Tworzenie modułu klienta

W pakiecie azure-iot-device utwórz element Client przy użyciu klasy Klient . Klasa Client zawiera metody, których urządzenie może używać do odbierania z usługi IoT Hub i wysyłania ich do usługi IoT Hub.

const Client = require('azure-iot-device').Client;

Wybieranie protokołu transportowego

Obiekt Client obsługuje następujące protokoły:

  • Amqp
  • Http — W przypadku korzystania z Httpusługi Client wystąpienie sprawdza komunikaty z usługi IoT Hub rzadko (co najmniej co 25 minut).
  • Mqtt
  • MqttWs
  • AmqpWs

Aby uzyskać więcej informacji na temat różnic między obsługą protokołów MQTT, AMQP i HTTPS, zobacz Wskazówki dotyczące komunikacji między chmurą a urządzeniem i Wybieranie protokołu komunikacyjnego.

W tym przykładzie protokół AMQP jest przypisywany do zmiennej Protocol . Ta zmienna Protokołu jest przekazywana do Client.fromConnectionString metody w sekcji Dodawanie parametry połączenia tego artykułu.

const Protocol = require('azure-iot-device-mqtt').Amqp;

Możliwości uzupełniania, odrzucania i porzucania komunikatów

Metody uzupełniania komunikatów, odrzucania i porzucania mogą być używane w zależności od wybranego protokołu.

Protokół AMQP i HTTP

Transporty PROTOKOŁU AMQP i HTTP mogą zakończyć, odrzucić lub porzucić komunikat:

  • Ukończono — aby ukończyć komunikat, usługa, która wysłała komunikat z chmury do urządzenia, zostanie powiadomiona o odebraniu komunikatu. Usługa IoT Hub usuwa komunikat z kolejki komunikatów. Metoda przyjmuje formę client.complete(message, callback function).
  • Odrzuć — aby odrzucić komunikat, usługa, która wysłała komunikat z chmury do urządzenia, zostanie powiadomiona, że komunikat nie jest przetwarzany przez urządzenie. Usługa IoT Hub trwale usuwa komunikat z kolejki urządzenia. Metoda przyjmuje formę client.reject(message, callback function).
  • Porzuć — aby porzucić komunikat, usługa IoT Hub natychmiast spróbuje wysłać ją ponownie. Usługa IoT Hub zachowuje komunikat w kolejce urządzenia na potrzeby przyszłego użycia. Metoda przyjmuje formę client.abandon(message, callback function).
MQTT

Protokół MQTT nie obsługuje funkcji uzupełniania, odrzucania ani porzucania komunikatów. Zamiast tego protokół MQTT domyślnie akceptuje komunikat i komunikat jest usuwany z kolejki komunikatów usługi IoT Hub.

Próby ponownego dostarczenia

Jeśli wystąpi coś, co uniemożliwia ukończenie, porzucenie lub odrzucenie komunikatu przez urządzenie, usługa IoT Hub otrzyma komunikat po upływie ustalonego limitu czasu, ponownie w kolejce komunikat do dostarczenia. Z tego powodu logika przetwarzania komunikatów w aplikacji urządzenia musi być idempotentna, dzięki czemu odbieranie tego samego komunikatu wielokrotnie generuje ten sam wynik.

Dodawanie ciągu usługi IoT Hub i protokołu transportu

Wywołaj metodę fromConnectionString , aby ustanowić połączenie centrum urządzenie-IoT przy użyciu następujących parametrów:

  • connStr — parametry połączenia, która hermetyzuje uprawnienia "łączenie urządzenia" dla centrum IoT. Parametry połączenia zawiera nazwę hosta, identyfikator urządzenia i klucz dostępu współdzielonego w tym formacie: "HostName=<iothub_host_name>; DeviceId=<device_id>; SharedAccessKey=<device_key>"
  • transportCtor — protokół transportowy.
const Protocol = require('azure-iot-device-mqtt').Amqp;
let client = Client.fromConnectionString(deviceConnectionString, Protocol);

Tworzenie przychodzącej procedury obsługi komunikatów

Procedura obsługi komunikatów jest wywoływana dla każdego komunikatu przychodzącego.

Po pomyślnym odebraniu komunikatu, jeśli używasz protokołu AMQP lub transportu HTTP, wywołaj metodę client.complete , aby poinformować usługę IoT Hub, że komunikat można usunąć z kolejki komunikatów.

Na przykład ta procedura obsługi komunikatów drukuje identyfikator komunikatu i treść komunikatu do konsoli, a następnie wywołuje funkcję client.complete powiadamiania usługi IoT Hub o przetworzeniu komunikatu i bezpiecznym usunięciu go z kolejki urządzenia. Wywołanie complete polecenia nie jest wymagane, jeśli używasz transportu MQTT i można go pominąć. Do transportu protokołu AMQP lub HTTPS jest wymagane wywołaniecomplete .

function messageHandler(msg) {
  console.log('Id: ' + msg.messageId + ' Body: ' + msg.data);
  client.complete(msg, printResultFor('completed'));
}

Tworzenie procedury obsługi rozłączania połączenia

Program obsługi rozłączania jest wywoływany po rozłączeniu połączenia. Procedura obsługi rozłączania jest przydatna do implementowania kodu ponownego nawiązywania połączenia.

Ten przykład przechwytuje i wyświetla komunikat o błędzie rozłączenia w konsoli.

function disconnectHandler() {
  clearInterval(sendInterval);
  sendInterval = null;
  client.open().catch((err) => {
    console.error(err.message);
  });
}

Dodawanie odbiorników zdarzeń

Te odbiorniki zdarzeń można określić przy użyciu metody .on .

  • Procedura obsługi połączeń
  • Procedura obsługi błędów
  • Rozłącz program obsługi
  • Procedura obsługi komunikatów

W tym przykładzie przedstawiono wcześniej zdefiniowane programy obsługi komunikatów i rozłączania.

client.on('connect', connectHandler);
client.on('error', errorHandler);
client.on('disconnect', disconnectHandler);
client.on('message', messageHandler);

Otwieranie połączenia z usługą IoT Hub

Użyj metody open, aby otworzyć połączenie między urządzeniem IoT i usługą IoT Hub. Użyj .catch(err) polecenia , aby przechwycić błąd i wywołać kod procedury obsługi.

Na przykład:

client.open()
.catch((err) => {
  console.error('Could not connect: ' + err.message);
});

Przykład komunikatu odbierania zestawu SDK

simple_sample_device — aplikacja urządzenia, która łączy się z centrum IoT Hub i odbiera komunikaty z chmury do urządzenia.

Wysyłanie komunikatów z chmury do urządzeń

W tej sekcji opisano sposób wysyłania komunikatu z chmury do urządzenia przy użyciu pakietu azure-iothub z zestawu AZURE IoT SDK dla Node.js. Jak wspomniano wcześniej, aplikacja zaplecza rozwiązania łączy się z usługą IoT Hub i komunikaty są wysyłane do usługi IoT Hub zakodowanej przy użyciu urządzenia docelowego. Usługa IoT Hub przechowuje komunikaty przychodzące do kolejki komunikatów, a komunikaty są dostarczane z kolejki komunikatów usługi IoT Hub do urządzenia docelowego.

Aplikacja zaplecza rozwiązania może również żądać i odbierać opinie dotyczące dostarczania komunikatu wysyłanego do usługi IoT Hub przeznaczonego do dostarczania urządzeń za pośrednictwem kolejki komunikatów.

Ładowanie klienta i modułów komunikatów

Zadeklaruj Client Client obiekt przy użyciu klasy z azure-iothub pakietu.

Zadeklaruj Message Message obiekt przy użyciu klasy z azure-iot-common pakietu.

'use strict';
var Client = require('azure-iothub').Client;
var Message = require('azure-iot-common').Message;

Tworzenie obiektu Client

Utwórz klienta przy użyciu polecenia fromConnectionString przy użyciu następujących parametrów:

  • Parametry połączenia usługi IoT Hub
  • Typ transportu

W tym przykładzie serviceClient obiekt jest tworzony z typem Amqp transportu.

var connectionString = '{IoT Hub connection string}';
var serviceClient = Client.fromConnectionString(connectionString,`Amqp`);

Otwieranie połączenia klienta

Wywołaj metodę Client open , aby otworzyć połączenie między aplikacją a usługą IoT Hub.

open może być wywoływany z funkcją wywołania zwrotnego wywoływaną po zakończeniu operacji lub bez określania open funkcji wywołania zwrotnego.

W tym przykładzie open metoda zawiera opcjonalną err funkcję wywołania zwrotnego otwartego połączenia. Jeśli wystąpi błąd otwierania, zwracany jest obiekt błędu. Jeśli otwarte połączenie zakończy się pomyślnie, null zostanie zwrócona wartość wywołania zwrotnego.

serviceClient.open(function (err)
if (err)
  console.error('Could not connect: ' + err.message);

Tworzenie komunikatu

Obiekt komunikatu zawiera asynchroniczny komunikat chmura-urządzenie. Funkcja komunikatów działa tak samo jak w przypadku protokołu AMQP, MQTT i HTTP.

Obiekt komunikatu obsługuje kilka właściwości, w tym te właściwości. Zobacz właściwości komunikatu, aby uzyskać pełną listę.

  • ack — Przekazywanie opinii. Opisane w następnej sekcji.
  • properties - Mapa zawierająca klucze ciągów i wartości do przechowywania niestandardowych właściwości komunikatów.
  • messageId — służy do korelowania komunikacji dwukierunkowej.

Dodaj treść komunikatu po utworzeniu wystąpienia obiektu komunikatu. W tym przykładzie 'Cloud to device message.' zostanie dodany komunikat.

var message = new Message('Cloud to device message.');
message.ack = 'full';
message.messageId = "My Message ID";

Potwierdzenie dostarczenia

Program wysyłający może zażądać potwierdzenia dostarczenia (lub wygaśnięcia) z usługi IoT Hub dla każdego komunikatu z chmury do urządzenia. Ta opcja umożliwia programowi wysyłającego korzystanie z logiki informowania, ponawiania próby lub kompensacji. Pełny opis operacji i właściwości opinii o wiadomościach opisano w sekcji Opinie o wiadomościach.

Każda wiadomość, która ma otrzymywać opinie o wiadomościach, musi zawierać wartość właściwości potwierdzenia dostarczenia ack . Właściwość ack może być jedną z następujących wartości:

  • none (wartość domyślna): nie jest generowany żaden komunikat z opiniami.

  • sent: otrzymuj wiadomość zwrotną, jeśli wiadomość została ukończona.

  • : otrzymuj wiadomość zwrotną, jeśli komunikat wygasł (lub osiągnięto maksymalną liczbę dostaw) bez ukończenia przez urządzenie.

  • full: opinia dotycząca zarówno wysłanych, jak i nie wysłanych wyników.

W tym przykładzie właściwość jest ustawiona ack na full, żądając zarówno wysłanej, jak i nie wysłanej opinii dotyczącej dostarczania komunikatów dla jednej wiadomości.

message.ack = 'full';

Funkcja wywołania zwrotnego odbiorcy komunikatów jest połączona z funkcją Client getFeedbackReceiver.

Odbiorca opinii o wiadomościach otrzymuje dwa argumenty:

  • Obiekt błędu (może mieć wartość null)
  • Obiekt AmqpReceiver — emituje zdarzenia, gdy nowe komunikaty opinii są odbierane przez klienta.

Ta przykładowa funkcja odbiera i wyświetla komunikat z informacją zwrotną do konsoli.

function receiveFeedback(err, receiver){
  receiver.on('message', function (msg) {
    console.log('Feedback message:')
    console.log(msg.getData().toString('utf-8'));
  });
}

Ten kod łączy funkcję wywołania zwrotnego receiveFeedback opinii z obiektem usługi Client przy użyciu polecenia getFeedbackReceiver.

serviceClient.getFeedbackReceiver(receiveFeedback);

Definiowanie procedury obsługi wyników uzupełniania komunikatów

Funkcja wywołania zwrotnego wysyłania komunikatów jest wywoływana po wysłaniu każdego komunikatu.

Ta przykładowa funkcja wyświetla wyniki operacji komunikatu send w konsoli. W tym przykładzie printResultFor funkcja jest dostarczana jako parametr send funkcji opisanej w następnej sekcji.

function printResultFor(op) {
  return function printResult(err, res) {
    if (err) console.log(op + ' error: ' + err.toString());
    if (res) console.log(op + ' status: ' + res.constructor.name);
  };
}

Wysyłanie wiadomości

Użyj funkcji send, aby wysłać asynchroniczny komunikat z chmury do urządzenia do aplikacji urządzenia za pośrednictwem usługi IoT Hub.

send obsługuje następujące parametry:

  • deviceID — identyfikator urządzenia docelowego.
  • message — treść komunikatu do wysłania na urządzenie.
  • gotowe — opcjonalna funkcja do wywołania po zakończeniu operacji. Gotowe jest wywoływane z dwoma argumentami:
    • Obiekt błędu (może mieć wartość null).
    • obiekt odpowiedzi specyficzny dla transportu przydatny do rejestrowania lub debugowania.

Ten kod wywołuje metodę send wysyłania komunikatu z chmury do urządzenia do aplikacji urządzenia za pośrednictwem usługi IoT Hub. Funkcja printResultFor wywołania zwrotnego zdefiniowana w poprzedniej sekcji odbiera informacje o potwierdzeniu dostarczania.

var targetDevice = '{device ID}';
serviceClient.send(targetDevice, message, printResultFor('send'));

W tym przykładzie pokazano, jak wysłać komunikat do urządzenia i obsłużyć komunikat opinii, gdy urządzenie potwierdzi komunikat z chmury do urządzenia:

serviceClient.open(function (err) {
  if (err) {
    console.error('Could not connect: ' + err.message);
  } else {
    console.log('Service client connected');
    serviceClient.getFeedbackReceiver(receiveFeedback);
    var message = new Message('Cloud to device message.');
    message.ack = 'full';
    message.messageId = "My Message ID";
    console.log('Sending message: ' + message.getData());
    serviceClient.send(targetDevice, message, printResultFor('send'));
  }
});

Przykład wysyłania komunikatu z zestawu SDK

send_c2d_message.js — wysyłanie komunikatów C2D do urządzenia za pośrednictwem usługi IoT Hub.

Zasady ponownego łączenia połączeń

W tym artykule nie przedstawiono zasad ponawiania próby komunikatów dla urządzenia z połączeniem usługi IoT Hub lub aplikacją zewnętrzną z połączeniem usługi IoT Hub. W kodzie produkcyjnym należy zaimplementować zasady ponawiania połączeń zgodnie z opisem w temacie Zarządzanie ponownymi połączeniami urządzeń w celu tworzenia odpornych aplikacji.

Czas przechowywania komunikatów, próby ponawiania prób i maksymalna liczba dostaw

Zgodnie z opisem w artykule Wysyłanie komunikatów z chmury do urządzenia z usługi IoT Hub można wyświetlać i konfigurować wartości domyślne dla następujących wartości komunikatów przy użyciu opcji konfiguracji usługi IoT Hub w portalu lub interfejsu wiersza polecenia platformy Azure. Te opcje konfiguracji mogą mieć wpływ na dostarczanie komunikatów i opinie.

  • Domyślny czas wygaśnięcia (czas wygaśnięcia) — czas, przez jaki komunikat jest dostępny dla urządzenia do użytku, zanim wygaśnie przez usługę IoT Hub.
  • Czas przechowywania opinii — czas, przez jaki usługa IoT Hub zachowuje opinię na temat wygaśnięcia lub dostarczania komunikatów z chmury do urządzenia.
  • Liczba prób dostarczenia komunikatu z chmury do urządzenia przez usługę IoT Hub.