Delen via

Cloud-naar-apparaat-berichten verzenden en ontvangen

  • Artikel

Azure IoT Hub is een volledig beheerde service waarmee bidirectionele communicatie mogelijk is, waaronder cloud-naar-apparaat-berichten (C2D) van back-ends van oplossingen tot miljoenen apparaten.

In dit artikel wordt beschreven hoe u de Azure IoT SDK's gebruikt om de volgende typen toepassingen te bouwen:

  • Apparaattoepassingen die cloud-naar-apparaat-berichten ontvangen en verwerken vanuit een IoT Hub-berichtenwachtrij.

  • Back-endtoepassingen die cloud-naar-apparaat-berichten verzenden naar één apparaat via een IoT Hub-berichtenwachtrij.

Dit artikel is bedoeld als aanvulling op runnable SDK-voorbeelden waarnaar in dit artikel wordt verwezen.

Notitie

De functies die in dit artikel worden beschreven, zijn alleen beschikbaar in de standaardlaag van de IoT Hub. Zie De juiste IoT Hub-laag voor uw oplossing kiezen voor meer informatie over de Basic- en Standard-/gratis IoT Hub-lagen.

Overzicht

Als een apparaattoepassing cloud-naar-apparaat-berichten wil ontvangen, moet deze verbinding maken met IoT Hub en vervolgens een berichtenhandler instellen om binnenkomende berichten te verwerken. De Azure IoT Hub-apparaat-SDK's bieden klassen en methoden die een apparaat kan gebruiken om berichten van de service te ontvangen en te verwerken. In dit artikel worden belangrijke elementen besproken van elke apparaattoepassing die berichten ontvangt, waaronder:

  • Een apparaatclientobject declareren
  • Verbinding maken met IoT Hub
  • Berichten ophalen uit de IoT Hub-berichtenwachtrij
  • Het bericht verwerken en een bevestiging terugsturen naar IoT Hub
  • Beleid voor opnieuw proberen van een ontvangstbericht configureren

Voor een back-endtoepassing om cloud-naar-apparaat-berichten te verzenden, moet deze verbinding maken met een IoT Hub en berichten verzenden via een IoT Hub-berichtenwachtrij. De Sdk's van de Azure IoT Hub-service bieden klassen en methoden die een toepassing kan gebruiken om berichten naar apparaten te verzenden. In dit artikel worden belangrijke elementen besproken van elke toepassing die berichten naar apparaten verzendt, waaronder:

  • Een serviceclientobject declareren
  • Verbinding maken met IoT Hub
  • Het bericht bouwen en verzenden
  • Feedback over bezorging ontvangen
  • Beleid voor opnieuw proberen voor verzenden van berichten configureren

Inzicht in de berichtenwachtrij

Om inzicht te hebben in cloud-naar-apparaat-berichten, is het belangrijk dat u een aantal basisprincipes begrijpt van de werking van berichtenwachtrijen voor IoT Hub-apparaten.

Cloud-naar-apparaat-berichten die vanuit een back-endtoepassing van een oplossing naar een IoT-apparaat worden verzonden, worden gerouteerd via IoT Hub. Er is geen directe peer-to-peer-berichtencommunicatie tussen de back-endtoepassing van de oplossing en het doelapparaat. IoT Hub plaatst binnenkomende berichten in de berichtenwachtrij, klaar om te worden gedownload door ioT-doelapparaten.

IoT Hub bewaart cloud-naar-apparaat-berichten in wachtrijen per apparaat om ten minste één keer te garanderen. Apparaten moeten expliciet bevestigen dat een bericht is voltooid voordat IoT Hub het bericht uit de wachtrij verwijdert. Deze aanpak garandeert tolerantie tegen connectiviteits- en apparaatfouten.

Wanneer IoT Hub een bericht in een berichtenwachtrij van een apparaat plaatst, wordt de berichtstatus ingesteld op Enqueued. Wanneer een apparaatthread een bericht uit de wachtrij haalt, vergrendelt IoT Hub het bericht door de berichtstatus in te stellen op Onzichtbaar. Deze status voorkomt dat andere threads op het apparaat hetzelfde bericht verwerken. Wanneer een apparaatthread de verwerking van een bericht heeft voltooid, wordt IoT Hub op de hoogte stellen en wordt vervolgens de berichtstatus ingesteld op Voltooid.

Een apparaattoepassing die een bericht ontvangt en verwerkt, wordt gezegd om het bericht te voltooien . Indien nodig kan een apparaat echter ook het volgende doen:

  • Negeer het bericht, waardoor IoT Hub het instelt op de status Dead lettered. Apparaten die verbinding maken via het MQTT-protocol (Message Queuing Telemetry Transport) kunnen geen cloud-naar-apparaat-berichten weigeren.
  • Laat het bericht, waardoor IoT Hub het bericht weer in de wachtrij plaatst, waarbij de status van het bericht is ingesteld op Enqueued. Apparaten die verbinding maken via het MQTT-protocol kunnen geen cloud-naar-apparaat-berichten verlaten.

Zie Cloud-naar-apparaat-berichten verzenden vanuit een IoT-hub voor meer informatie over de levenscyclus van berichten in de cloud naar het apparaat en hoe IoT Hub cloud-naar-apparaat-berichten verwerkt.

Cloud-naar-apparaat-berichten ontvangen

In deze sectie wordt beschreven hoe u cloud-naar-apparaat-berichten ontvangt met behulp van de Klasse DeviceClient in de Azure IoT SDK voor .NET.

Er zijn twee opties die een apparaatclienttoepassing kan gebruiken om berichten te ontvangen:

  • Polling: de apparaattoepassing controleert op nieuwe IoT Hub-berichten met behulp van een codelus (bijvoorbeeld een while of for lus). De lus wordt voortdurend uitgevoerd en controleert op berichten.
  • Callback: De apparaattoepassing stelt een asynchrone berichthandlermethode in die onmiddellijk wordt aangeroepen wanneer een bericht binnenkomt.

Een DeviceClient-object declareren

DeviceClient bevat methoden en eigenschappen die nodig zijn voor het ontvangen van berichten van IoT Hub.

Voorbeeld:

static DeviceClient deviceClient;

De verbindingsparameters opgeven

Geef de primaire verbindingsreeks en apparaat-id van IoT Hub op DeviceClient met behulp van de methode CreateFromConnectionString. Naast de vereiste primaire IoT Hub-verbindingsreeks kan de CreateFromConnectionString methode worden overbelast om deze optionele parameters op te nemen:

  • transportType - Het transportprotocol: variaties van HTTP-versie 1, AMQP of MQTT. AMQP is de standaardwaarde. Zie TransportType Enum voor alle beschikbare waarden.
  • transportSettings - Interface die wordt gebruikt voor het definiëren van verschillende transportspecifieke instellingen voor DeviceClient en ModuleClient. Zie ITransportSettings Interface voor meer informatie.
  • ClientOptions - Opties waarmee de configuratie van het apparaat- of moduleclientexemplaren tijdens de initialisatie is toegestaan.

In dit voorbeeld wordt aanroepen CreateFromConnectionString om de ioT-hub- en apparaat-id-instellingen voor de DeviceClient verbinding te definiëren.

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

Navragen

Polling maakt gebruik van ReceiveAsync om te controleren op berichten.

Een aanroep om deze formulieren te ReceiveAsync kunnen aannemen:

  • ReceiveAsync() - Wacht op de standaardtime-outperiode voor een bericht voordat u doorgaat.
  • ReceiveAsync (Timespan) - Ontvang een bericht uit de apparaatwachtrij met behulp van een specifieke time-out.
  • ReceiveAsync (CancellationToken) - Ontvang een bericht uit de apparaatwachtrij met behulp van een annuleringstoken. Wanneer u een annuleringstoken gebruikt, wordt de standaardtime-outperiode niet gebruikt.

Wanneer u een transporttype HTTP 1 gebruikt in plaats van MQTT of AMQP, wordt de ReceiveAsync methode onmiddellijk geretourneerd. Het ondersteunde patroon voor cloud-naar-apparaat-berichten met HTTP 1 is onregelmatig verbonden apparaten die regelmatig controleren op berichten (minimaal om de 25 minuten). Het uitgeven van meer HTTP 1 ontvangt resultaten in ioT Hub die de aanvragen beperkt. Zie de richtlijnen voor communicatie tussen cloud-naar-apparaat en kies een communicatieprotocol voor meer informatie over de verschillen tussen MQTT-, AMQP- en HTTP 1-ondersteuning.

Methode CompleteAsync

Nadat het apparaat een bericht heeft ontvangen, roept de apparaattoepassing de CompleteAsync-methode aan om IoT Hub op de hoogte te stellen dat het bericht is verwerkt en dat het bericht veilig kan worden verwijderd uit de wachtrij van het IoT Hub-apparaat. Het apparaat moet deze methode aanroepen wanneer de verwerking is voltooid, ongeacht het transportprotocol dat wordt gebruikt.

Bericht verlaten, weigeren of time-out

Met AMQP- en HTTP-versie 1-protocollen, maar niet met het MQTT-protocol, kan het apparaat ook:

  • Een bericht verlaten door AbandonAsync aan te roepen. Dit resulteert in IoT Hub in het bewaren van het bericht in de apparaatwachtrij voor toekomstig verbruik.
  • Een bericht weigeren door WeigerenAsync aan te roepen. Hierdoor wordt het bericht definitief uit de apparaatwachtrij verwijderd.

Als er iets gebeurt waardoor het apparaat het bericht niet kan voltooien, afbreken of afwijzen, wordt het bericht na een vaste time-outperiode opnieuw in de wachtrij geplaatst. Daarom moet de logica voor berichtverwerking in de apparaat-app idempotent zijn, zodat het ontvangen van hetzelfde bericht meerdere keren hetzelfde resultaat oplevert.

Zie Cloud-naar-apparaat-berichten verzenden vanuit een IoT-hub voor meer informatie over de levenscyclus van berichten in de cloud naar het apparaat en hoe IoT Hub cloud-naar-apparaat-berichten verwerkt.

Polling-lus

Bij het gebruik van polling gebruikt een toepassing een codelus waarmee de ReceiveAsync methode herhaaldelijk wordt aangeroepen om te controleren op nieuwe berichten totdat deze is gestopt.

Als u een time-outwaarde of de standaardtime-out gebruikt ReceiveAsync , wacht elke aanroep in de lus op ReceiveAsync de opgegeven time-outperiode. Als ReceiveAsync er een time-out optreedt, wordt een null waarde geretourneerd en wordt de lus voortgezet.

Wanneer een bericht wordt ontvangen, wordt er een taakobject geretourneerd dat ReceiveAsync moet worden doorgegeven aan CompleteAsync. Een aanroep om IoT Hub op de hoogte te brengen van CompleteAsync het opgegeven bericht uit de berichtenwachtrij op basis van de Task parameter.

In dit voorbeeld wordt de lus aangeroepen ReceiveAsync totdat een bericht is ontvangen of de polling-lus is gestopt.

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

Terugbellen

Als u callback-cloud-naar-apparaat-berichten in de apparaattoepassing wilt ontvangen, moet de toepassing verbinding maken met de IoT Hub en een callback-listener instellen om binnenkomende berichten te verwerken. Binnenkomende berichten naar het apparaat worden ontvangen van de IoT Hub-berichtenwachtrij.

Met callback stelt de apparaattoepassing een berichthandlermethode in met behulp van SetReceiveMessageHandlerAsync. De berichthandler wordt aangeroepen en er wordt een bericht ontvangen. Als u een callback-methode maakt om berichten te ontvangen, hoeft u niet voortdurend te peilen naar ontvangen berichten.

Callback is alleen beschikbaar met behulp van deze protocollen:

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

De Http1 protocoloptie biedt geen ondersteuning voor callbacks omdat de SDK-methoden toch moeten peilen naar ontvangen berichten, waardoor het callback-principe wordt verslagen.

In dit voorbeeld SetReceiveMessageHandlerAsync stelt u een callback-handlermethode in met de naam OnC2dMessageReceivedAsync, die wordt aangeroepen telkens wanneer een bericht wordt ontvangen.

// 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.");

Beleid voor opnieuw proberen van berichten ontvangen

Het beleid voor opnieuw proberen van apparaatclientberichten kan worden gedefinieerd met deviceClient.SetRetryPolicy.

De time-out voor opnieuw proberen van het bericht wordt opgeslagen in de eigenschap DeviceClient.OperationTimeoutInMilliseconds .

Voorbeeld van SDK-bericht ontvangen

De .NET/C#-SDK bevat een voorbeeld van bericht ontvangen dat de methoden voor het ontvangen van berichten bevat die in deze sectie worden beschreven.

Cloud-naar-apparaat-berichten verzenden

In deze sectie wordt essentiële code beschreven voor het verzenden van een bericht van een back-endtoepassing van een oplossing naar een IoT-apparaat met behulp van de ServiceClient-klasse in de Azure IoT SDK voor .NET. Zoals eerder is besproken, wordt een back-endtoepassing van een oplossing verbinding gemaakt met een IoT Hub en berichten verzonden naar IoT Hub die is gecodeerd met een doelapparaat. IoT Hub slaat binnenkomende berichten op in de berichtenwachtrij en berichten worden bezorgd vanuit de IoT Hub-berichtenwachtrij naar het doelapparaat.

Een back-endtoepassing van een oplossing kan ook feedback over bezorging aanvragen en ontvangen voor een bericht dat is verzonden naar IoT Hub die is bestemd voor apparaatbezorging via de berichtenwachtrij.

Een ServiceClient-object declareren

ServiceClient bevat methoden en eigenschappen die nodig zijn om berichten van een toepassing via IoT Hub naar een apparaat te verzenden.

static ServiceClient serviceClient;

Geef de verbindingsreeks

Geef de primaire ioT Hub-verbindingsreeks op voor ServiceClient het gebruik van de methode CreateFromConnectionString. Naast de vereiste primaire IoT Hub-verbindingsreeks kan de CreateFromConnectionString methode worden overbelast om deze optionele parameters op te nemen:

  • transportType - Amqp of Amqp_WebSocket_Only.
  • transportSettings - De AMQP- en HTTP-proxyinstellingen voor serviceclient.
  • ServiceClientOptions - Opties waarmee de configuratie van het serviceclientexemplaren tijdens de initialisatie is toegestaan. Zie ServiceClientOptions voor meer informatie.

In dit voorbeeld wordt het ServiceClient object gemaakt met behulp van de IoT Hub-verbindingsreeks.

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

Een asynchroon cloud-naar-apparaat-bericht verzenden

Gebruik sendAsync om een asynchroon bericht vanuit een toepassing via de cloud (IoT Hub) naar het apparaat te verzenden. De aanroep wordt uitgevoerd met behulp van het AMQP-protocol.

sendAsync gebruikt deze parameters:

  • deviceID - De tekenreeks-id van het doelapparaat.
  • message - Het cloud-naar-apparaat-bericht. Het bericht is van het type Bericht en kan dienovereenkomstig worden opgemaakt.
  • timeout - Een optionele time-outwaarde. De standaardwaarde is één minuut als deze niet is opgegeven.

In dit voorbeeld wordt een testbericht verzonden naar het doelapparaat met een time-outwaarde van 10 seconden.

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

Feedback over bezorging ontvangen

Een verzendend programma kan bevestigingen voor levering (of vervaldatum) aanvragen van IoT Hub voor elk cloud-naar-apparaat-bericht. Met deze optie kan het verzendende programma gebruikmaken van inform-, retry- of compensatielogica. Een volledige beschrijving van de feedbackbewerkingen en eigenschappen van berichten worden beschreven in Berichtfeedback.

Feedback over de bezorging van berichten ontvangen:

  • feedbackReceiver Het object maken
  • Berichten verzenden met behulp van de Ack parameter
  • Wachten om feedback te ontvangen

Het feedbackReceiver-object maken

Roep GetFeedbackReceiver aan om een FeedbackReceiver-object te maken. FeedbackReceiver bevat methoden die services kunnen gebruiken om feedback te ontvangen bewerkingen uit te voeren.

var feedbackReceiver = serviceClient.GetFeedbackReceiver();

Berichten verzenden met de Ack-parameter

Elk bericht moet een waarde bevatten voor de eigenschap leveringsbevestiging Ack om feedback over bezorging te ontvangen. De Ack eigenschap kan een van deze waarden zijn:

  • geen (standaard): er wordt geen feedbackbericht gegenereerd.

  • Positive: ontvang een feedbackbericht als het bericht is voltooid.

  • Negative: ontvang een feedbackbericht als het bericht is verlopen (of het maximum aantal bezorgingen is bereikt) zonder dat het apparaat is voltooid.

  • Full: feedback voor zowel Positive als Negative resultaten.

In dit voorbeeld is de Ack eigenschap ingesteld op Full, waarbij zowel positieve als negatieve feedback over de bezorging van berichten voor één bericht wordt aangevraagd.

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

Wachten om feedback te ontvangen

Definieer een CancellationToken. Roep vervolgens in een lus herhaaldelijk ReceiveAsync aan, waarbij wordt gecontroleerd op feedbackberichten over bezorging. Elke aanroep om te ReceiveAsync wachten op de time-outperiode die is gedefinieerd voor het ServiceClient object.

  • Als een ReceiveAsync time-out verloopt zonder ontvangen bericht, ReceiveAsync wordt de lus geretourneerd en wordt de lus null voortgezet.
  • Als er een feedbackbericht wordt ontvangen, wordt er een taakobject geretourneerd dat ReceiveAsync moet worden doorgegeven aan CompleteAsync , samen met het annuleringstoken. Een aanroep om het opgegeven verzonden bericht uit de berichtenwachtrij te CompleteAsync verwijderen op basis van de Task parameter.
  • Indien nodig kan de ontvangstcode AbandonAsync aanroepen om een verzendbericht weer in de wachtrij te plaatsen.
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;

In dit voorbeeld ziet u een methode die deze stappen bevat.

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

Houd er rekening mee dat dit ontvangstpatroon van feedback vergelijkbaar is met het patroon dat wordt gebruikt voor het ontvangen van cloud-naar-apparaat-berichten in de apparaattoepassing.

Opnieuw verbinding maken met serviceclient

Bij het tegenkomen van een uitzondering stuurt de serviceclient die informatie door naar de aanroepende toepassing. Op dat moment wordt aanbevolen dat u de details van de uitzondering inspecteert en de benodigde actie onderneemt.

Voorbeeld:

  • Als het een netwerkonderzondering is, kunt u de bewerking opnieuw proberen.
  • Als het een beveiligingsonderzondering (niet-geautoriseerde uitzondering) is, controleert u uw referenties en controleert u of deze up-to-date zijn.
  • Als het om een beperking/quotum gaat dan uitzondering, controleert en/of wijzigt u de frequentie van het verzenden van aanvragen of werkt u de schaaleenheid van uw hubinstantie bij. Zie Quota en beperking van IoT Hub voor meer informatie.

Beleid voor opnieuw proberen van berichten verzenden

Het ServiceClient beleid voor opnieuw proberen van berichten kan worden gedefinieerd met behulp van ServiceClient.SetRetryPolicy.

Voorbeeld van SDK-bericht verzenden

De .NET/C#SDK bevat een serviceclientvoorbeeld dat de methoden voor het verzenden van berichten bevat die in deze sectie worden beschreven.

Cloud-naar-apparaat-berichten ontvangen

In deze sectie wordt beschreven hoe u cloud-naar-apparaat-berichten ontvangt met behulp van de DeviceClient-klasse van de Azure IoT SDK voor Java.

Voor een op Java gebaseerde apparaattoepassing om cloud-naar-apparaat-berichten te ontvangen, moet deze verbinding maken met IoT Hub en vervolgens een callback-listener en berichthandler instellen om binnenkomende berichten van IoT Hub te verwerken. De apparaattoepassing moet ook verbinding kunnen detecteren en afhandelen als de apparaat-naar-IoT Hub-berichtverbinding is verbroken.

Azure IoT Java SDK-bibliotheken importeren

De code waarnaar in dit artikel wordt verwezen, maakt gebruik van deze SDK-bibliotheken.

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;

Een DeviceClient-object declareren

Voor de instantiëring van het DeviceClient-object zijn deze parameters vereist:

  • connString: het IoT-apparaat verbindingsreeks. De verbindingsreeks is een set sleutel-waardeparen die worden gescheiden door ';', met de sleutels en waarden gescheiden door '='. Deze moet waarden voor deze sleutels bevatten: HostName, DeviceId, and SharedAccessKey.
  • Transportprotocol : de DeviceClient verbinding kan een van de volgende IoTHubClientProtocol-transportprotocolprotocol's gebruiken. AMQP is de meest veelzijdige, maakt het mogelijk om berichten regelmatig te controleren en staat afkeuring van berichten toe en annuleert. MQTT biedt geen ondersteuning voor methoden voor het afwijzen of verlaten van berichten:
    • AMQPS
    • AMQPS_WS
    • HTTPS
    • MQTT
    • MQTT_WS

Voorbeeld:

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

De callback-methode voor berichten instellen

Gebruik de methode setMessageCallback om een berichthandlermethode te definiëren die wordt gewaarschuwd wanneer een bericht wordt ontvangen van IoT Hub.

setMessageCallback bevat deze parameters:

  • callback - De naam van de callback-methode. Kan zijn null.
  • context - Een optionele context van het type object. Gebruik null deze optie als deze niet is opgegeven.

In dit voorbeeld wordt een methode met de callback naam MessageCallback zonder contextparameter doorgegeven aan setMessageCallback.

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

Een callback-handler voor berichten maken

Een callback-berichtenhandler ontvangt en verwerkt een binnenkomend bericht dat is doorgegeven vanuit de IoT Hub-berichtenwachtrij.

In dit voorbeeld verwerkt de berichthandler een binnenkomend bericht en retourneert vervolgens IotHubMessageResult.COMPLETE. Een IotHubMessageResult.COMPLETE retourwaarde meldt IoT Hub dat het bericht is verwerkt en dat het bericht veilig uit de apparaatwachtrij kan worden verwijderd. Het apparaat moet worden geretourneerd IotHubMessageResult.COMPLETE wanneer de verwerking is voltooid, waarbij IoT Hub wordt geïnformeerd dat het bericht uit de berichtenwachtrij moet worden verwijderd, ongeacht het protocol dat wordt gebruikt.

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

Opties voor het afbreken en afwijzen van berichten

Hoewel het grote aantal binnenkomende berichten naar een apparaat met succes moet worden ontvangen en ertoe moet leiden IotHubMessageResult.COMPLETE, kan het nodig zijn om een bericht af te schaffen of af te wijzen.

  • Met AMQP en HTTPS, maar niet met MQTT, kan een toepassing het volgende doen:
    • IotHubMessageResult.ABANDON het bericht. IoT Hub stuurt deze opnieuw in de wachtrij en verzendt deze later opnieuw.
    • IotHubMessageResult.REJECT het bericht. IoT Hub stuurt het bericht niet opnieuw in de wachtrij en verwijdert het bericht definitief uit de berichtenwachtrij.
  • Clients die berichten gebruiken MQTT of REJECT MQTT_WS niet ABANDON gebruiken.

Als er iets gebeurt waardoor het apparaat het bericht niet kan voltooien, afbreken of afwijzen, wordt het bericht na een vaste time-outperiode opnieuw in de wachtrij geplaatst. Daarom moet de logica voor berichtverwerking in de apparaat-app idempotent zijn, zodat het ontvangen van hetzelfde bericht meerdere keren hetzelfde resultaat oplevert.

Zie Cloud-naar-apparaat-berichten verzenden vanuit een IoT-hub voor meer informatie over de levenscyclus van berichten in de cloud naar het apparaat en hoe IoT Hub cloud-naar-apparaat-berichten verwerkt.

Notitie

Als u HTTPS gebruikt in plaats van MQTT of AMQP als transport, controleert het DeviceClient-exemplaar onregelmatig op berichten van IoT Hub (minimaal om de 25 minuten). Zie De communicatierichtlijnen voor cloud-naar-apparaat en kies een communicatieprotocol voor meer informatie over de verschillen tussen MQTT-, AMQP- en HTTPS-ondersteuning.

De callbackmethode voor de berichtstatus maken

Een toepassing kan registerConnectionStatusChangeCallback gebruiken om een callback-methode te registreren die moet worden uitgevoerd wanneer de verbindingsstatus van het apparaat wordt gewijzigd. Op deze manier kan de toepassing een verbinding met downed berichten detecteren en opnieuw verbinding maken.

In dit voorbeeld IotHubConnectionStatusChangeCallbackLogger wordt deze geregistreerd als de callbackmethode voor de verbindingsstatuswijziging.

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

De callback wordt geactiveerd en een ConnectionStatusChangeContext object doorgegeven.

Aanroep connectionStatusChangeContext.getNewStatus() om de huidige verbindingsstatus op te halen.

IotHubConnectionStatus status = connectionStatusChangeContext.getNewStatus();

De geretourneerde verbindingsstatus kan een van deze waarden zijn:

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

Aanroepen connectionStatusChangeContext.getNewStatusReason() om de reden voor de wijziging van de verbindingsstatus op te halen.

IotHubConnectionStatusChangeReason statusChangeReason = connectionStatusChangeContext.getNewStatusReason();

Aanroepen connectionStatusChangeContext.getCause() om de reden voor de wijziging van de verbindingsstatus te vinden. getCause() kan retourneren null als er geen informatie beschikbaar is.

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

Zie het handleMessages-voorbeeld dat wordt vermeld in de sectie voorbeeld van het SDK-bericht ontvangen van dit artikel voor een volledig voorbeeld waarin wordt getoond hoe u de statuswijzigingsstatus van de callback-methode voor de callback-methode kunt extraheren, waarom de status van het apparaat is gewijzigd en de context.

De verbinding tussen apparaat en IoT Hub openen

Gebruik open om een verbinding te maken tussen het apparaat en IoT Hub. Het apparaat kan nu asynchroon berichten verzenden en ontvangen van en naar een IoT Hub. Als de client al is geopend, doet de methode niets.

client.open(true);

Voorbeeld van SDK-bericht ontvangen

HandleMessages: een voorbeeld van een apparaat-app die is opgenomen in de Microsoft Azure IoT SDK voor Java, die verbinding maakt met uw IoT-hub en cloud-naar-apparaat-berichten ontvangt.

Cloud-naar-apparaat-berichten verzenden

In deze sectie wordt beschreven hoe u een cloud-naar-apparaat-bericht verzendt met behulp van de ServiceClient-klasse van de Azure IoT SDK voor Java. Een back-endtoepassing van een oplossing maakt verbinding met een IoT Hub en berichten worden verzonden naar IoT Hub gecodeerd met een doelapparaat. IoT Hub slaat binnenkomende berichten op in de berichtenwachtrij en berichten worden bezorgd vanuit de IoT Hub-berichtenwachtrij naar het doelapparaat.

Een back-endtoepassing van een oplossing kan ook feedback over bezorging aanvragen en ontvangen voor een bericht dat is verzonden naar IoT Hub die is bestemd voor apparaatbezorging via de berichtenwachtrij.

De afhankelijkheidsinstructie toevoegen

Voeg de afhankelijkheid toe om het iothub-java-service-clientpakket in uw toepassing te gebruiken om te communiceren met uw IoT Hub-service:

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

Importinstructies toevoegen

Voeg deze importinstructies toe om de Azure IoT Java SDK en uitzonderingshandler te gebruiken.

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

Het verbindingsprotocol definiëren

Gebruik IotHubServiceClientProtocol om het toepassingslaagprotocol te definiëren dat door de serviceclient wordt gebruikt om te communiceren met een IoT Hub.

IotHubServiceClientProtocol accepteert alleen de AMQPS of AMQPS_WS opsomming.

private static final IotHubServiceClientProtocol protocol =    
    IotHubServiceClientProtocol.AMQPS;

Het ServiceClient-object maken

Maak het ServiceClient-object en geef het Iot Hub-verbindingsreeks en protocol op.

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

De verbinding tussen de toepassing en IoT Hub openen

open de AMQP-afzenderverbinding. Met deze methode maakt u de verbinding tussen de toepassing en IoT Hub.

serviceClient.open();

Een feedbackontvanger openen voor feedback over berichtbezorging

U kunt een FeedbackReceiver gebruiken om verzonden berichten te ontvangen naar IoT Hub-feedback. A FeedbackReceiver is een gespecialiseerde ontvanger waarvan de Receive methode een FeedbackBatch in plaats van een Message.

In dit voorbeeld wordt het FeedbackReceiver object gemaakt en wordt de open() instructie aangeroepen om te wachten op feedback.

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

Berichteigenschappen toevoegen

U kunt eventueel setProperties gebruiken om berichteigenschappen toe te voegen. Deze eigenschappen zijn opgenomen in het bericht dat naar het apparaat wordt verzonden en kunnen na ontvangst door de apparaattoepassing worden geëxtraheerd.

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

Een asynchroon bericht maken en verzenden

Het berichtobject slaat het bericht op dat moet worden verzonden. In dit voorbeeld wordt een 'Cloud-naar-apparaatbericht' bezorgd.

Gebruik setDeliveryAcknowledgement om bevestiging van de berichtenwachtrij van IoT Hub aan te vragen. In dit voorbeeld wordt Fullde gevraagde bevestiging geleverd of niet geleverd.

Gebruik SendAsync om een asynchroon bericht van de client naar het apparaat te verzenden. U kunt ook de Send methode (niet asynchroon) gebruiken, maar deze functie wordt intern gesynchroniseerd, zodat slechts één verzendbewerking tegelijk is toegestaan. Het bericht wordt vanuit de toepassing bezorgd bij IoT Hub. IoT Hub plaatst het bericht in de berichtenwachtrij, klaar om te worden bezorgd op het doelapparaat.

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

Feedback ontvangen over de bezorging van berichten

Nadat een bericht is verzonden vanuit de toepassing, kan de toepassing het ontvangen aanroepen met of zonder een time-outwaarde. Als er geen time-outwaarde wordt opgegeven, wordt de standaardtime-out gebruikt. Hiermee wordt een FeedbackBatch-object geretourneerd dat eigenschappen voor feedback over berichtbezorging bevat die kunnen worden onderzocht.

In dit voorbeeld worden de FeedbackBatch ontvanger en oproepen getEnqueuedTimeUtc gemaakt, waarna de tijd van het bericht wordt afgedrukt.

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

Voorbeelden van sdk-berichten verzenden

De Azure IoT SDK-bibliotheek installeren

Installeer de SDK-bibliotheek van azure-iot-device op uw ontwikkelcomputer voordat u verwante code aanroept:

pip install azure-iot-device

Er zijn twee Python SDK-klassen die worden gebruikt voor het verzenden van berichten naar en van IoT-apparaten. Methoden voor berichtafhandeling van deze klassen worden beschreven in secties op deze pagina.

  • De Klasse IoTHubDeviceClient bevat methoden voor het maken van een synchrone verbinding van een apparaat met een Azure IoT Hub en het ontvangen van berichten van IoT Hub.

  • De klasse IoTHubRegistryManager bevat API's voor IoT Hub Registry Manager-bewerkingen. In dit artikel laten methoden van deze klasse zien hoe u verbinding maakt met IoT Hub en een bericht verzendt naar een apparaat.

Cloud-naar-apparaat-berichten ontvangen

In deze sectie wordt beschreven hoe u cloud-naar-apparaat-berichten ontvangt met behulp van de IoTHubDeviceClient-klasse van de Azure IoT SDK voor Python.

Voor een op Python gebaseerde apparaattoepassing om cloud-naar-apparaat-berichten te ontvangen, moet deze verbinding maken met IoT Hub en vervolgens een callback-berichthandler instellen om binnenkomende berichten van IoT Hub te verwerken.

Het IoTHubDeviceClient-object importeren

Voeg een coderegel toe om de IoTHubDeviceClient functies te importeren uit de SDK azure.iot.device.

from azure.iot.device import IoTHubDeviceClient

De apparaatclient verbinden

Instantieer de IoTHubDeviceClient en geef een IoT Hub-verbindingsreeks door aan create_from_connection_string. Hiermee maakt u een verbinding van het apparaat met IoT Hub.

U kunt ook verbinding maken met IoTHubDeviceClienteen apparaat met behulp van een van de volgende methoden:

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

Opnieuw verbinden afhandelen

IoTHubDeviceClient probeert standaard een verbroken verbinding te herstellen. Gedrag voor opnieuw verbinden wordt bepaald door de IoTHubDeviceClient connection_retry en connection_retry_interval parameters.

Een berichthandler maken

Maak de functie berichthandler om binnenkomende berichten naar het apparaat te verwerken.

In dit voorbeeld message_handler wordt het aangeroepen wanneer een bericht wordt ontvangen. De berichteigenschappen (.items) worden afgedrukt naar de console met behulp van een lus.

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

De berichthandler toewijzen

Gebruik de methode on_message_received om de berichthandlermethode toe te wijzen aan het IoTHubDeviceClient object.

In dit voorbeeld wordt een berichthandlermethode met de naam message_handler gekoppeld aan het IoTHubDeviceClient client object. Het client object wacht totdat een cloud-naar-apparaat-bericht van een IoT Hub wordt ontvangen. Deze code wacht maximaal 300 seconden (5 minuten) voor een bericht of sluit af als er op een toetsenbordtoets wordt gedrukt.

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

Voorbeeld van SDK-bericht ontvangen

Bericht ontvangen: C2D-berichten (Cloud to Device) ontvangen die vanuit de Azure IoT Hub naar een apparaat worden verzonden.

Cloud-naar-apparaat-berichten verzenden

In deze sectie wordt beschreven hoe u een cloud-naar-apparaat-bericht verzendt met behulp van de ioTHubRegistryManager-klasse van de Azure IoT SDK voor Python. Een back-endtoepassing van een oplossing maakt verbinding met een IoT Hub en berichten worden verzonden naar IoT Hub gecodeerd met een doelapparaat. IoT Hub slaat binnenkomende berichten op in de berichtenwachtrij en berichten worden bezorgd vanuit de IoT Hub-berichtenwachtrij naar het doelapparaat.

Het IoTHubRegistryManager-object importeren

Voeg de volgende import instructie toe. IoTHubRegistryManager bevat API's voor IoT Hub Registry Manager-bewerkingen.

from azure.iot.hub import IoTHubRegistryManager

De IoT Hub-registerbeheerder verbinden

Instantieer het IoTHubRegistryManager-object dat verbinding maakt met een IoT-hub, waarbij een IoT Hub-verbindingsreeks wordt doorgegeven aan from_connection_string.

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

Een bericht maken en verzenden

Gebruik send_c2d_message om een bericht via de cloud (IoT Hub) naar het apparaat te verzenden.

send_c2d_message gebruikt deze parameters:

  • deviceID - De tekenreeks-id van het doelapparaat.
  • message - Het cloud-naar-apparaat-bericht. Het bericht is van het type str (tekenreeks).
  • properties - Een optionele verzameling eigenschappen van het type dict. Eigenschappen kunnen toepassingseigenschappen en systeemeigenschappen bevatten. De standaardwaarde is {}.

In dit voorbeeld wordt een testbericht verzonden naar het doelapparaat.

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

Voorbeeld van SDK-bericht verzenden

send_message.py - Demonstreert hoe u een cloud-naar-apparaat-bericht verzendt.

De Node.js messaging-pakketten installeren

Voer deze opdrachten uit om de azure-iot-device - en azure-iothub-pakketten te installeren op uw ontwikkelcomputer:

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

Het pakket azure-iot-device bevat objecten die interface hebben met IoT-apparaten. In dit artikel wordt klassecode beschreven Client die berichten ontvangt van IoT Hub.

Het azure-iothub-pakket bevat objecten die interface hebben met IoT Hub. In dit artikel wordt klassecode beschreven Client waarmee een bericht van een toepassing naar een apparaat wordt verzonden via IoT Hub.

Berichten ontvangen in de apparaattoepassing

In deze sectie wordt beschreven hoe u cloud-naar-apparaat-berichten ontvangt met behulp van het pakket azure-iot-device in de Azure IoT SDK voor Node.js.

Voor een Node.js-gebaseerde apparaattoepassing om cloud-naar-apparaat-berichten te ontvangen, moet deze verbinding maken met IoT Hub en vervolgens een callback-listener en berichthandler instellen om binnenkomende berichten van IoT Hub te verwerken. De apparaattoepassing moet ook verbinding kunnen detecteren en afhandelen als de apparaat-naar-IoT Hub-berichtverbinding is verbroken.

Een clientmodule maken

Maak vanuit het azure-iot-device pakket een Client met behulp van de clientklasse . De Client klasse bevat methoden die een apparaat kan gebruiken om te ontvangen van en te verzenden naar IoT Hub.

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

Een transportprotocol kiezen

Het Client object ondersteunt deze protocollen:

  • Amqp
  • Http - Bij gebruik Httpcontroleert het Client exemplaar zelden op berichten van IoT Hub (minimaal om de 25 minuten).
  • Mqtt
  • MqttWs
  • AmqpWs

Zie De communicatierichtlijnen voor cloud-naar-apparaat en kies een communicatieprotocol voor meer informatie over de verschillen tussen MQTT-, AMQP- en HTTPS-ondersteuning.

In dit voorbeeld wordt het AMQP-protocol toegewezen aan een Protocol variabele. Deze protocolvariabele wordt doorgegeven aan de Client.fromConnectionString methode in de sectie Verbindingsreeks van dit artikel toevoegen.

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

Mogelijkheden voor het voltooien, afwijzen en verlaten van berichten

Methoden voor het voltooien, afwijzen en verlaten van berichten kunnen worden gebruikt, afhankelijk van het gekozen protocol.

AMQP en HTTP

De AMQP- en HTTP-transporten kunnen een bericht voltooien, afwijzen of afbreken:

  • Voltooid : om een bericht te voltooien, wordt de service die het cloud-naar-apparaat-bericht heeft verzonden op de hoogte gesteld dat het bericht wordt ontvangen. IoT Hub verwijdert het bericht uit de berichtenwachtrij. De methode heeft de vorm van client.complete(message, callback function).
  • Weigeren : als u een bericht wilt weigeren, wordt de service die het cloud-naar-apparaat-bericht heeft verzonden, op de hoogte gesteld dat het bericht niet door het apparaat wordt verwerkt. IoT Hub verwijdert het bericht definitief uit de apparaatwachtrij. De methode heeft de vorm van client.reject(message, callback function).
  • Verlaten : als u een bericht wilt verlaten, probeert IoT Hub het bericht onmiddellijk opnieuw te verzenden. IoT Hub behoudt het bericht in de wachtrij van het apparaat voor toekomstig verbruik. De methode heeft de vorm van client.abandon(message, callback function).
MQTT

MQTT biedt geen ondersteuning voor functies voor het voltooien, weigeren of afbreken van berichten. In plaats daarvan accepteert MQTT standaard een bericht en wordt het bericht verwijderd uit de IoT Hub-berichtenwachtrij.

Nieuwe pogingen om opnieuw te worden livery

Als er iets gebeurt waardoor het apparaat het bericht niet kan voltooien, afbreken of afwijzen, wordt het bericht na een vaste time-outperiode opnieuw in de wachtrij geplaatst. Daarom moet de logica voor berichtverwerking in de apparaat-app idempotent zijn, zodat het ontvangen van hetzelfde bericht meerdere keren hetzelfde resultaat oplevert.

Het IoT Hub-tekenreeks- en transportprotocol toevoegen

Roep fromConnectionString aan om een apparaat-naar-IoT-hubverbinding tot stand te brengen met behulp van deze parameters:

  • connStr- Een verbindingsreeks die machtigingen voor apparaatverbinding inkapselt voor een IoT-hub. De verbindingsreeks bevat hostnaam, apparaat-id en gedeelde toegangssleutel in deze indeling: "HostName=<iothub_host_name>; DeviceId=<device_id>; SharedAccessKey=<device_key>"
  • transportCtor - Het transportprotocol.
const Protocol = require('azure-iot-device-mqtt').Amqp;
let client = Client.fromConnectionString(deviceConnectionString, Protocol);

Een handler voor binnenkomende berichten maken

De berichthandler wordt aangeroepen voor elk binnenkomend bericht.

Nadat een bericht is ontvangen, roept u, als u AMQP of HTTP-transport gebruikt, de client.complete methode aan om IoT Hub te informeren dat het bericht uit de berichtenwachtrij kan worden verwijderd.

Deze berichtenhandler drukt bijvoorbeeld de bericht-id en de hoofdtekst van het bericht af naar de console en roept client.complete vervolgens aan om IoT Hub op de hoogte te stellen dat het bericht is verwerkt en dat het veilig uit de apparaatwachtrij kan worden verwijderd. De aanroep naar complete is niet vereist als u MQTT-transport gebruikt en kan worden weggelaten. Een aanroep naarcomplete is vereist voor AMQP- of HTTPS-transport.

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

Een handler voor verbinding verbreken maken

De verbindingshandler wordt aangeroepen wanneer de verbinding is verbroken. Een verbindingshandler is handig voor het implementeren van code voor opnieuw verbinden.

In dit voorbeeld wordt het foutbericht over de verbinding met de console onderschept en weergegeven.

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

Gebeurtenislisteners toevoegen

U kunt deze gebeurtenislisteners opgeven met behulp van de methode .on .

  • Verbindingshandler
  • Fouthandler
  • Verbinding verbreken handler
  • Berichthandler

Dit voorbeeld bevat het bericht en de handlers voor de verbinding die eerder zijn gedefinieerd.

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

De verbinding met IoT Hub openen

Gebruik de open methode om een verbinding te openen tussen een IoT-apparaat en IoT Hub. Gebruik .catch(err) dit om een fout op te vangen en handlercode aan te roepen.

Voorbeeld:

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

Voorbeeld van SDK-bericht ontvangen

simple_sample_device: een apparaat-app die verbinding maakt met uw IoT-hub en cloud-naar-apparaat-berichten ontvangt.

Cloud-naar-apparaat-berichten verzenden

In deze sectie wordt beschreven hoe u een cloud-naar-apparaat-bericht verzendt met behulp van het azure-iothub-pakket van de Azure IoT SDK voor Node.js. Zoals eerder is besproken, wordt een back-endtoepassing van een oplossing verbinding gemaakt met een IoT Hub en berichten verzonden naar IoT Hub die is gecodeerd met een doelapparaat. IoT Hub slaat binnenkomende berichten op in de berichtenwachtrij en berichten worden bezorgd vanuit de IoT Hub-berichtenwachtrij naar het doelapparaat.

Een back-endtoepassing van een oplossing kan ook feedback over bezorging aanvragen en ontvangen voor een bericht dat is verzonden naar IoT Hub die is bestemd voor apparaatbezorging via de berichtenwachtrij.

De client- en berichtmodules laden

Declareer een Client object met behulp van de Client klasse uit het azure-iothub pakket.

Declareer een Message object met behulp van de Message klasse uit het azure-iot-common pakket.

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

Het clientobject maken

Maak de client met behulp van fromConnectionString met behulp van deze parameters:

  • IoT Hub-verbindingsreeks
  • Transporttype

In dit voorbeeld wordt het serviceClient object gemaakt met het Amqp transporttype.

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

De clientverbinding openen

Roep de Client open methode aan om een verbinding tussen een toepassing en IoT Hub te openen.

open kan worden aangeroepen met of zonder een callback-functie op te geven die wordt aangeroepen wanneer de open bewerking is voltooid.

In dit voorbeeld bevat de open methode een optionele err callback-functie voor open verbindingen. Als er een geopende fout optreedt, wordt een foutobject geretourneerd. Als de open verbinding is geslaagd, wordt er een null callbackwaarde geretourneerd.

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

Een bericht maken

Het berichtobject bevat het asynchrone cloud-naar-apparaat-bericht. De berichtfunctionaliteit werkt op dezelfde manier via AMQP, MQTT en HTTP.

Het berichtobject ondersteunt verschillende eigenschappen, waaronder deze eigenschappen. Bekijk de berichteigenschappen voor een volledige lijst.

  • ack - Feedback geven. Beschreven in de volgende sectie.
  • properties - Een kaart met tekenreekssleutels en -waarden voor het opslaan van aangepaste berichteigenschappen.
  • messageId : wordt gebruikt om communicatie in twee richtingen te correleren.

Voeg de berichttekst toe wanneer het berichtobject wordt geïnstantieerd. In dit voorbeeld wordt een 'Cloud to device message.' bericht toegevoegd.

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

Bevestiging van bezorging

Een verzendend programma kan bevestigingen voor levering (of vervaldatum) aanvragen van IoT Hub voor elk cloud-naar-apparaat-bericht. Met deze optie kan het verzendende programma gebruikmaken van inform-, retry- of compensatielogica. Een volledige beschrijving van de feedbackbewerkingen en eigenschappen van berichten worden beschreven in Berichtfeedback.

Elk bericht dat berichtenfeedback moet ontvangen, moet een waarde bevatten voor de bevestigingseigenschap van de bezorging. De ack eigenschap kan een van deze waarden zijn:

  • geen (standaard): er wordt geen feedbackbericht gegenereerd.

  • sent: ontvang een feedbackbericht als het bericht is voltooid.

  • : ontvang een feedbackbericht als het bericht is verlopen (of het maximum aantal bezorgingen is bereikt) zonder dat het apparaat is voltooid.

  • full: feedback voor zowel verzonden als niet verzonden resultaten.

In dit voorbeeld is de ack eigenschap ingesteld op full, waarbij zowel verzonden als geen feedback over de bezorging van berichten voor één bericht wordt aangevraagd.

message.ack = 'full';

De callbackfunctie van de ontvanger van het bericht is gekoppeld aan de Client functie getFeedbackReceiver.

De ontvanger van het bericht ontvangt twee argumenten:

  • Foutobject (kan null zijn)
  • AmqpReceiver-object - Verzendt gebeurtenissen wanneer nieuwe feedbackberichten worden ontvangen door de client.

Deze voorbeeldfunctie ontvangt en drukt een feedbackbericht over bezorging af naar de console.

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

Deze code koppelt de receiveFeedback callback-functie voor feedback aan het serviceobject Client met behulp van getFeedbackReceiver.

serviceClient.getFeedbackReceiver(receiveFeedback);

Een handler voor het voltooien van berichten definiëren

De callbackfunctie voor het verzenden van berichten wordt aangeroepen nadat elk bericht is verzonden.

Met deze voorbeeldfunctie worden berichtbewerkingsresultaten afgedrukt send naar de console. In dit voorbeeld wordt de printResultFor functie geleverd als een parameter voor de send functie die in de volgende sectie wordt beschreven.

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

Een bericht verzenden

Gebruik de functie Verzenden om een asynchroon cloud-naar-apparaat-bericht naar de apparaat-app te verzenden via IoT Hub.

send ondersteunt deze parameters:

  • deviceID : de apparaat-id van het doelapparaat.
  • bericht : de hoofdtekst van het bericht dat naar het apparaat moet worden verzonden.
  • done - De optionele functie die moet worden aangeroepen wanneer de bewerking is voltooid. Gereed wordt aangeroepen met twee argumenten:
    • Foutobject (kan null zijn).
    • transportspecifiek antwoordobject handig voor logboekregistratie of foutopsporing.

Met deze code wordt send een cloud-naar-apparaat-bericht verzonden naar de apparaat-app via IoT Hub. De callback-functie printResultFor die in de vorige sectie is gedefinieerd, ontvangt de bevestigingsgegevens van de levering.

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

In dit voorbeeld ziet u hoe u een bericht naar uw apparaat verzendt en het feedbackbericht verwerkt wanneer het apparaat het cloud-naar-apparaat-bericht bevestigt:

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

Voorbeeld van SDK-bericht verzenden

send_c2d_message.js: C2D-berichten verzenden naar een apparaat via IoT Hub.

Beleid voor opnieuw verbinden van verbinding

In dit artikel wordt geen beleid voor het opnieuw proberen van berichten gedemonstreert voor het apparaat naar een IoT Hub-verbinding of een externe toepassing met een IoT Hub-verbinding. In productiecode moet u beleid voor het opnieuw proberen van verbindingen implementeren, zoals beschreven in Apparaatherconnecties beheren om tolerante toepassingen te maken.

Bewaartijd voor berichten, nieuwe pogingen en maximaal aantal bezorgingen

Zoals beschreven in Cloud-naar-apparaat-berichten verzenden vanuit IoT Hub, kunt u de standaardwaarden voor de volgende berichtwaarden weergeven en configureren met behulp van de ioT Hub-configuratieopties van de portal of de Azure CLI. Deze configuratieopties kunnen van invloed zijn op de bezorging en feedback van berichten.

  • Standaard-TTL (time to live): de hoeveelheid tijd die een bericht beschikbaar is voor een apparaat dat moet worden gebruikt voordat het is verlopen door IoT Hub.
  • Retentietijd voor feedback: de hoeveelheid tijd die IoT Hub heeft, behoudt de feedback voor het verlopen of leveren van cloud-naar-apparaat-berichten.
  • Het aantal keren dat IoT Hub een cloud-naar-apparaat-bericht probeert te leveren aan een apparaat.