Cloud-naar-apparaat-berichten verzenden en ontvangen

Artikel
01/06/2025

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.

Een apparaattoepassing maken

In deze sectie wordt beschreven hoe u cloud-naar-apparaat-berichten ontvangt.

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

Callback: De apparaattoepassing stelt een asynchrone berichthandlermethode in die onmiddellijk wordt aangeroepen wanneer een bericht binnenkomt.
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.

Vereist NuGet-pakket voor apparaten

Voor apparaatclienttoepassingen die zijn geschreven in C# is het NuGet-pakket Microsoft.Azure.Devices.Client vereist.

Voeg deze using instructies toe om de apparaatbibliotheek te gebruiken.

using Microsoft.Azure.Devices.Client;
using Microsoft.Azure.Devices.Shared;

Een apparaat verbinden met IoT Hub

Een apparaat-app kan worden geverifieerd met IoT Hub met behulp van de volgende methoden:

Gedeelde toegangssleutel
X.509-certificaat

Belangrijk

Dit artikel bevat stappen voor het verbinden van een apparaat met behulp van een Shared Access Signature, ook wel symmetrische sleutelverificatie genoemd. Deze verificatiemethode is handig voor testen en evalueren, maar het verifiëren van een apparaat met X.509-certificaten is een veiligere benadering. Zie Best practices > voor beveiliging voor verbindingsbeveiliging voor meer informatie.

Verifiëren met behulp van een gedeelde toegangssleutel

De DeviceClient-klasse bevat alle methoden die nodig zijn om berichten op het apparaat te ontvangen.

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 verbinding gemaakt met een apparaat met behulp van het Mqtt transportprotocol.

static string DeviceConnectionString = "{IoT hub device connection string}";
static deviceClient = null;
deviceClient = DeviceClient.CreateFromConnectionString(DeviceConnectionString, 
   TransportType.Mqtt);

Verifiëren met behulp van een X.509-certificaat

Een apparaat verbinden met IoT Hub met behulp van een X.509-certificaat:

Gebruik DeviceAuthenticationWithX509Certificate om een object te maken dat apparaat- en certificaatgegevens bevat. DeviceAuthenticationWithX509Certificate wordt doorgegeven als de tweede parameter aan DeviceClient.Create (stap 2).
Gebruik DeviceClient.Create om het apparaat te verbinden met IoT Hub met behulp van een X.509-certificaat.

In dit voorbeeld worden apparaat- en certificaatgegevens ingevuld in het auth DeviceAuthenticationWithX509Certificate object waarnaar wordt doorgegeven DeviceClient.Create.

In dit voorbeeld ziet u waarden voor certificaatinvoerparameter als lokale variabelen voor duidelijkheid. Sla in een productiesysteem gevoelige invoerparameters op in omgevingsvariabelen of een andere veiligere opslaglocatie. Gebruik Environment.GetEnvironmentVariable("HOSTNAME") bijvoorbeeld om de omgevingsvariabele hostnaam te lezen.

RootCertPath = "~/certificates/certs/sensor-thl-001-device.cert.pem";
Intermediate1CertPath = "~/certificates/certs/sensor-thl-001-device.intermediate1.cert.pem";
Intermediate2CertPath = "~/certificates/certs/sensor-thl-001-device.intermediate2.cert.pem";
DevicePfxPath = "~/certificates/certs/sensor-thl-001-device.cert.pfx";
DevicePfxPassword = "1234";
DeviceName = "MyDevice";
HostName = "xxxxx.azure-devices.net";

var chainCerts = new X509Certificate2Collection();
chainCerts.Add(new X509Certificate2(RootCertPath));
chainCerts.Add(new X509Certificate2(Intermediate1CertPath));
chainCerts.Add(new X509Certificate2(Intermediate2CertPath));
using var deviceCert = new X509Certificate2(DevicePfxPath, DevicePfxPassword);
using var auth = new DeviceAuthenticationWithX509Certificate(DeviceName, deviceCert, chainCerts);

using var deviceClient = DeviceClient.Create(
    HostName,
    auth,
    TransportType.Amqp);

Zie voor meer informatie over certificaatverificatie:

Codevoorbeelden

Zie voor werkende voorbeelden van X.509-certificaatverificatie van apparaat:

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

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.

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

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.

Een back-endtoepassing maken

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.

Service NuGet-pakket toevoegen

Voor back-endservicetoepassingen is het NuGet-pakket Microsoft.Azure.Devices vereist.

Verbinding maken met IoT Hub

U kunt een back-endservice verbinden met IoT Hub met behulp van de volgende methoden:

Beleid voor gedeelde toegang
Microsoft Entra

Belangrijk

Dit artikel bevat stappen voor het maken van verbinding met een service met behulp van een handtekening voor gedeelde toegang. Deze verificatiemethode is handig voor testen en evalueren, maar verificatie bij een service met Microsoft Entra ID of beheerde identiteiten is een veiligere benadering. Zie Best practices > voor beveiliging voor cloudbeveiliging voor meer informatie.

Verbinding maken met behulp van een beleid voor gedeelde toegang

Een back-endtoepassing verbinden met een apparaat met 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 en standaardtransportAmqp.

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

Verbinding maken met Microsoft Entra

Een back-end-app die gebruikmaakt van Microsoft Entra, moet een beveiligingstokenreferentie verifiëren en verkrijgen voordat u verbinding maakt met IoT Hub. Dit token wordt doorgegeven aan een IoT Hub-verbindingsmethode. Zie Toegang tot IoT Hub beheren met behulp van Microsoft Entra ID voor algemene informatie over het instellen en gebruiken van Microsoft Entra voor IoT Hub.

Microsoft Entra-app configureren

U moet een Microsoft Entra-app instellen die is geconfigureerd voor uw voorkeursverificatiereferenties. De app bevat parameters zoals het clientgeheim dat door de back-endtoepassing wordt gebruikt om te verifiëren. De beschikbare configuraties voor app-verificatie zijn:

Clientgeheim
Certificaat
Referenties voor federatieve identiteit

Voor Microsoft Entra-apps zijn mogelijk specifieke rolmachtigingen vereist, afhankelijk van bewerkingen die worden uitgevoerd. IoT Hub Twin-inzender is bijvoorbeeld vereist om lees- en schrijftoegang tot een IoT Hub-apparaat en moduledubbels in te schakelen. Zie Toegang tot IoT Hub beheren met behulp van Azure RBAC-roltoewijzing voor meer informatie.

Zie quickstart: Een toepassing registreren bij het Microsoft Identity Platform voor meer informatie over het instellen van een Microsoft Entra-app.

Verifiëren met DefaultAzureCredential

De eenvoudigste manier om Microsoft Entra te gebruiken om een back-endtoepassing ChainedTokenCredentialte verifiëren, is door DefaultAzureCredential te gebruiken, maar het wordt aanbevolen om een andere methode te gebruiken in een productieomgeving, inclusief een specifieke TokenCredential of geparseerde toepassing. Ter vereenvoudiging beschrijft deze sectie verificatie met behulp van DefaultAzureCredential en clientgeheim. Zie Gebruiksrichtlijnen voor DefaultAzureCredential voor meer informatie over de voor- en nadelen van het gebruik.DefaultAzureCredential

DefaultAzureCredential ondersteunt verschillende verificatiemechanismen en bepaalt het juiste referentietype op basis van de omgeving waarin het wordt uitgevoerd. Er wordt geprobeerd om meerdere referentietypen in een volgorde te gebruiken totdat er een werkende referentie wordt gevonden.

Microsoft Entra vereist deze NuGet-pakketten en bijbehorende using instructies:

Azure.Core
Azure.Identity

using Azure.Core;
using Azure.Identity;

In dit voorbeeld worden clientgeheim, client-id en tenant-id van Microsoft Entra-app-registratie toegevoegd aan omgevingsvariabelen. Deze omgevingsvariabelen worden gebruikt om DefaultAzureCredential de toepassing te verifiëren. Het resultaat van een geslaagde Microsoft Entra-verificatie is een beveiligingstokenreferentie die wordt doorgegeven aan een IoT Hub-verbindingsmethode.

string clientSecretValue = "xxxxxxxxxxxxxxx";
string clientID = "xxxxxxxxxxxxxx";
string tenantID = "xxxxxxxxxxxxx";

Environment.SetEnvironmentVariable("AZURE_CLIENT_SECRET", clientSecretValue);
Environment.SetEnvironmentVariable("AZURE_CLIENT_ID", clientID);
Environment.SetEnvironmentVariable("AZURE_TENANT_ID", tenantID);

TokenCredential tokenCredential = new DefaultAzureCredential();

De resulterende TokenCredential kan vervolgens worden doorgegeven aan een verbinding met de IoT Hub-methode voor elke SDK-client die Microsoft Entra-referenties accepteert:

In dit voorbeeld wordt het TokenCredential doorgegeven om een ServiceClient-verbindingsobject te ServiceClient.Create maken.

string hostname = "xxxxxxxxxx.azure-devices.net";
using var serviceClient = ServiceClient.Create(hostname, tokenCredential, TransportType.Amqp);

In dit voorbeeld wordt het TokenCredential doorgegeven om RegistryManager.Create een RegistryManager-object te maken.

string hostname = "xxxxxxxxxx.azure-devices.net";
registryManager = RegistryManager.Create(hostname, tokenCredential);

Voorbeeld van code

Zie Het voorbeeld van verificatie op basis van rollen voor een werkende voorbeeld van Microsoft Entra-serviceverificatie.

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

Een apparaattoepassing maken

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.

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 apparaat verbinden met IoT Hub

Een apparaat-app kan worden geverifieerd met IoT Hub met behulp van de volgende methoden:

Gedeelde toegangssleutel
X.509-certificaat

Belangrijk

Verifiëren met behulp van een gedeelde toegangssleutel

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 = "{IOT hub device connection string}";
static protocol = IotHubClientProtocol.AMQPS;
DeviceClient client = new DeviceClient(connectionString, protocol);

Verifiëren met behulp van een X.509-certificaat

Een apparaat verbinden met IoT Hub met behulp van een X.509-certificaat:

Bouw het SSLContext-object met buildSSLContext.
Voeg de SSLContext informatie toe aan een ClientOptions-object .
Roep DeviceClient aan met behulp van de ClientOptions informatie om de apparaat-naar-IoT Hub-verbinding te maken.

In dit voorbeeld ziet u waarden voor certificaatinvoerparameter als lokale variabelen voor duidelijkheid. Sla in een productiesysteem gevoelige invoerparameters op in omgevingsvariabelen of een andere veiligere opslaglocatie. Gebruik Environment.GetEnvironmentVariable("PUBLICKEY") bijvoorbeeld om een omgevingsvariabele met een openbare sleutelcertificaattekenreeks te lezen.

private static final String publicKeyCertificateString =
        "-----BEGIN CERTIFICATE-----\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "-----END CERTIFICATE-----\n";

//PEM encoded representation of the private key
private static final String privateKeyString =
        "-----BEGIN EC PRIVATE KEY-----\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "-----END EC PRIVATE KEY-----\n";

SSLContext sslContext = SSLContextBuilder.buildSSLContext(publicKeyCertificateString, privateKeyString);
ClientOptions clientOptions = ClientOptions.builder().sslContext(sslContext).build();
DeviceClient client = new DeviceClient(connString, protocol, clientOptions);

Zie voor meer informatie over certificaatverificatie:

Codevoorbeelden

Zie voor werkende voorbeelden van X.509-certificaatverificatie van apparaat:

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.

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.

Een back-endtoepassing maken

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.

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;

Verbinding maken met de IoT Hub

U kunt een back-endservice verbinden met IoT Hub met behulp van de volgende methoden:

Beleid voor gedeelde toegang
Microsoft Entra

Belangrijk

Verbinding maken met behulp van een beleid voor gedeelde toegang

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.

IotHubServiceClientProtocol protocol = IotHubServiceClientProtocol.AMQPS;

Het ServiceClient-object maken

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

String connectionString = "{yourhubconnectionstring}";
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();

Verbinding maken met Microsoft Entra

Zie Azure-verificatie met Java en Azure Identity voor een overzicht van Java SDK-verificatie.

Ter vereenvoudiging richt deze sectie zich op het beschrijven van verificatie met behulp van clientgeheim.

Microsoft Entra-app configureren

Clientgeheim
Certificaat
Referenties voor federatieve identiteit

Zie quickstart: Een toepassing registreren bij het Microsoft Identity Platform voor meer informatie over het instellen van een Microsoft Entra-app.

Verifiëren met DefaultAzureCredential

De eenvoudigste manier om Microsoft Entra te gebruiken om een back-endtoepassing ChainedTokenCredentialte verifiëren, is door DefaultAzureCredential te gebruiken, maar het wordt aanbevolen om een andere methode te gebruiken in een productieomgeving, inclusief een specifieke TokenCredential of geparseerde toepassing. Zie Referentieketens in de Azure Identity-clientbibliotheek voor Java voor meer informatie over de voor- en nadelen van het gebruik.DefaultAzureCredential

DefaultAzureCredential ondersteunt verschillende verificatiemechanismen en bepaalt het juiste referentietype op basis van de omgeving waarin het wordt uitgevoerd. Er wordt geprobeerd om meerdere referentietypen in een volgorde te gebruiken totdat er een werkende referentie wordt gevonden.

U kunt microsoft Entra-app-referenties verifiëren met behulp van DefaultAzureCredentialBuilder. Sla verbindingsparameters zoals tenantID, client-id en clientgeheimwaarden op als omgevingsvariabelen. Zodra de server TokenCredential is gemaakt, geeft u deze door aan ServiceClient of een andere opbouwfunctie als de parameter referentie.

In dit voorbeeld DefaultAzureCredentialBuilder wordt geprobeerd een verbinding te verifiëren vanuit de lijst die wordt beschreven in DefaultAzureCredential. Het resultaat van een geslaagde Microsoft Entra-verificatie is een beveiligingstokenreferentie die wordt doorgegeven aan een constructor zoals ServiceClient.

TokenCredential defaultAzureCredential = new DefaultAzureCredentialBuilder().build();

Verifiëren met ClientSecretCredentialBuilder

U kunt ClientSecretCredentialBuilder gebruiken om een referentie te maken met behulp van clientgeheiminformatie. Als dit lukt, retourneert deze methode een TokenCredential die kan worden doorgegeven aan ServiceClient of een andere opbouwfunctie als de parameter referentie.

string clientSecretValue = System.getenv("AZURE_CLIENT_SECRET");
string clientID = System.getenv("AZURE_CLIENT_ID");
string tenantID = System.getenv("AZURE_TENANT_ID");

TokenCredential credential =
     new ClientSecretCredentialBuilder()
          .tenantId(tenantID)
          .clientId(clientID)
          .clientSecret(clientSecretValue)
          .build();

Andere verificatieklassen

De Java SDK bevat ook deze klassen die een back-end-app verifiëren met Microsoft Entra:

Codevoorbeelden

Zie het voorbeeld van verificatie op basis van rollen voor werkvoorbeelden van de Microsoft Entra-service.

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

Er zijn twee voorbeelden voor het verzenden van berichten:

Voorbeeld van serviceclient : voorbeeld van bericht verzenden, #1.
Voorbeeld van serviceclient : voorbeeld van bericht verzenden, #2.

Een apparaattoepassing maken

In deze sectie wordt beschreven hoe u cloud-naar-apparaat-berichten ontvangt.

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 azure-iot-device-bibliotheek moet zijn geïnstalleerd om apparaattoepassingen te maken.

pip install azure-iot-device

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.

Instructie voor apparaatimport

Voeg deze code toe om de IoTHubDeviceClient functies te importeren uit de SDK azure.iot.device.

from azure.iot.device import IoTHubDeviceClient

Een apparaat verbinden met IoT Hub

Een apparaat-app kan worden geverifieerd met IoT Hub met behulp van de volgende methoden:

Gedeelde toegangssleutel
X.509-certificaat

Belangrijk

Verifiëren met behulp van een gedeelde toegangssleutel

Een apparaat verbinden met IoT Hub:

Roep create_from_connection_string aan om het primaire verbindingsreeks van het apparaat toe te voegen.
Roep verbinding aan om verbinding te maken met de apparaatclient.

Voorbeeld:

# Add your IoT hub primary connection string
CONNECTION_STRING = "{Device primary connection string}"
device_client = IoTHubDeviceClient.create_from_connection_string(CONNECTION_STRING)

# Connect the client
device_client.connect()

Verifiëren met behulp van een X.509-certificaat

Een apparaat verbinden met IoT Hub met behulp van een X.509-certificaat:

Gebruik create_from_x509_certificate om de X.509-certificaatparameters toe te voegen
Verbinding maken aanroepen om de apparaatclient te verbinden

In dit voorbeeld ziet u waarden voor certificaatinvoerparameter als lokale variabelen voor duidelijkheid. Sla in een productiesysteem gevoelige invoerparameters op in omgevingsvariabelen of een andere veiligere opslaglocatie. Gebruik os.getenv("HOSTNAME") bijvoorbeeld om de omgevingsvariabele hostnaam te lezen.

# The Azure IoT hub name
hostname = "xxxxx.azure-devices.net"

# The device that has been created on the portal using X509 CA signing or self-signing capabilities
device_id = "MyDevice"

# The X.509 certificate file name
cert_file = "~/certificates/certs/sensor-thl-001-device.cert.pfx"
key_file = "~/certificates/certs/sensor-thl-001-device.cert.key"
# The optional certificate pass phrase
pass_phrase = "1234"

x509 = X509(
    cert_file,
    key_file,
    pass_phrase,
)

# The client object is used to interact with your Azure IoT hub.
device_client = IoTHubDeviceClient.create_from_x509_certificate(
    hostname=hostname, device_id=device_id, x509=x509
)

# Connect to IoT Hub
await device_client.connect()

Zie voor meer informatie over certificaatverificatie:

Codevoorbeelden

Zie de voorbeelden waarvan de bestandsnamen eindigen op x509 bij Async Hub-scenario's voor werkvoorbeelden van X.509-certificaten.

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 een berichtenhandlerfunctie om binnenkomende berichten naar het apparaat te verwerken. Dit wordt toegewezen door on_message_received (volgende stap) als de callback-berichthandler.

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.

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.

Een back-endtoepassing maken

In deze sectie wordt beschreven hoe u een cloud-naar-apparaat-bericht verzendt. 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.

De IoTHubRegistryManager-klasse bevat alle methoden die nodig zijn om een back-endtoepassing te maken om te communiceren met cloud-naar-apparaat-berichten van de service. De azure-iot-hub-bibliotheek moet zijn geïnstalleerd om back-endservicetoepassingen te maken.

pip install azure-iot-hub

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

Verbinding maken met IoT Hub

U kunt een back-endservice verbinden met IoT Hub met behulp van de volgende methoden:

Beleid voor gedeelde toegang
Microsoft Entra

Belangrijk

Verbinding maken met behulp van een beleid voor gedeelde toegang

Maak verbinding met IoT Hub met behulp van from_connection_string.

Voorbeeld:

IoTHubConnectionString = "{IoT hub service connection string}"
registry_manager = IoTHubRegistryManager.from_connection_string(IoTHubConnectionString)

Verbinding maken met Microsoft Entra

Microsoft Entra-app configureren

Clientgeheim
Certificaat
Referenties voor federatieve identiteit

Zie quickstart: Een toepassing registreren bij het Microsoft Identity Platform voor meer informatie over het instellen van een Microsoft Entra-app.

Verifiëren met DefaultAzureCredential

Microsoft Entra vereist deze NuGet-pakketten en bijbehorende using instructies:

Azure.Core
Azure.Identity

using Azure.Core;
using Azure.Identity;

string clientSecretValue = "xxxxxxxxxxxxxxx";
string clientID = "xxxxxxxxxxxxxx";
string tenantID = "xxxxxxxxxxxxx";

Environment.SetEnvironmentVariable("AZURE_CLIENT_SECRET", clientSecretValue);
Environment.SetEnvironmentVariable("AZURE_CLIENT_ID", clientID);
Environment.SetEnvironmentVariable("AZURE_TENANT_ID", tenantID);

TokenCredential tokenCredential = new DefaultAzureCredential();

De resulterende TokenCredential kan vervolgens worden doorgegeven aan een verbinding met de IoT Hub-methode voor elke SDK-client die Microsoft Entra-referenties accepteert:

In dit voorbeeld wordt het TokenCredential doorgegeven om een ServiceClient-verbindingsobject te ServiceClient.Create maken.

string hostname = "xxxxxxxxxx.azure-devices.net";
using var serviceClient = ServiceClient.Create(hostname, tokenCredential, TransportType.Amqp);

In dit voorbeeld wordt het TokenCredential doorgegeven om RegistryManager.Create een RegistryManager-object te maken.

string hostname = "xxxxxxxxxx.azure-devices.net";
registryManager = RegistryManager.Create(hostname, tokenCredential);

Voorbeeld van code

Zie Het voorbeeld van verificatie op basis van rollen voor een werkende voorbeeld van Microsoft Entra-serviceverificatie.

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

De Azure IoT SDK voor Python biedt een werkend voorbeeld van een service-app die laat zien hoe u een cloud-naar-apparaat-bericht verzendt. Zie send_message.py laat zien hoe u een cloud-naar-apparaat-bericht verzendt voor meer informatie.

Een apparaattoepassing maken

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.

SDK-pakketten installeren

Het pakket azure-iot-device bevat objecten die interface hebben met IoT-apparaten. Voer deze opdracht uit om de SDK voor het apparaat azure-iot-device te installeren op uw ontwikkelcomputer:

npm install azure-iot-device --save

Een apparaat verbinden met IoT Hub

Een apparaat-app kan worden geverifieerd met IoT Hub met behulp van de volgende methoden:

X.509-certificaat
Gedeelde toegangssleutel

Belangrijk

Verifiëren met behulp van een X.509-certificaat

Het X.509-certificaat is gekoppeld aan het apparaat-naar-IoT Hub-verbindingstransport.

Een apparaat-naar-IoT Hub-verbinding configureren met behulp van een X.509-certificaat:

Roep fromConnectionString aan om het apparaat of de identiteitsmodule toe te voegen verbindingsreeks en het transporttype aan het Client object toe te voegen. Voeg x509=true toe aan de verbindingsreeks om aan te geven dat een certificaat wordt toegevoegd aan DeviceClientOptions. Voorbeeld:
- Een apparaat verbindingsreeks:
  
  HostName=xxxxx.azure-devices.net;DeviceId=Device-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true
- Een identiteitsmodule verbindingsreeks:
  
  HostName=xxxxx.azure-devices.net;DeviceId=Device-1;ModuleId=Module-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true
Configureer een JSON-variabele met certificaatgegevens en geef deze door aan DeviceClientOptions.
Roep setOptions aan om een X.509-certificaat en -sleutel (en eventueel een wachtwoordzin) toe te voegen aan het clienttransport.
Roep open om de verbinding van het apparaat naar IoT Hub te openen.

In dit voorbeeld ziet u informatie over certificaatconfiguratie in een JSON-variabele. De certificeringsconfiguratie clientOptions wordt doorgegeven aan setOptionsen de verbinding wordt geopend met behulp van open.

const Client = require('azure-iot-device').Client;
const Protocol = require('azure-iot-device-mqtt').Mqtt;
// Connection string illustrated for demonstration only. Never hard-code the connection string in production. Instead use an environmental variable or other secure storage.
const connectionString = `HostName=xxxxx.azure-devices.net;DeviceId=Device-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true`
const client = Client.fromConnectionString(connectionString, Protocol);

var clientOptions = {
   cert: myX509Certificate,
   key: myX509Key,
   passphrase: passphrase,
   http: {
     receivePolicy: {
       interval: 10
     }
   }
 }

 client.setOptions(clientOptions);
 client.open(connectCallback);

Zie voor meer informatie over certificaatverificatie:

Voorbeeld van code

Zie Eenvoudig voorbeeldapparaat X.509 voor een werkend voorbeeld van X.509-certificaatverificatie.

Verifiëren met behulp van een gedeelde toegangssleutel

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

Installeer de benodigde transportprotocollen op uw ontwikkelcomputer.

Met deze opdracht wordt bijvoorbeeld het Amqp protocol geïnstalleerd:

npm install azure-iot-device-amqp --save

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

Een clientobject maken

Maak een Client object met behulp van het geïnstalleerde pakket.

Voorbeeld:

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

Een protocolobject maken

Maak een Protocol object met behulp van een geïnstalleerd transportpakket.

In dit voorbeeld wordt het AMQP-protocol toegewezen:

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

Het apparaat verbindingsreeks en transportprotocol toevoegen

Aanroepen vanuitConnectionString om verbindingsparameters voor apparaten op te geven:

connStr : het apparaat verbindingsreeks.
transportCtor - Het transportprotocol.

In dit voorbeeld wordt het Amqp transportprotocol gebruikt:

const deviceConnectionString = "{IoT hub device connection string}"
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);
});

Voorbeelden van SDK-apparaten

De Azure IoT SDK voor Node.js biedt een werkend voorbeeld van een apparaat-app die het ontvangen van berichten afhandelt. Zie voor meer informatie:

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

Een back-endtoepassing maken

In deze sectie wordt beschreven hoe u een cloud-naar-apparaat-bericht verzendt. 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.

Service SDK-pakket installeren

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.

Voer deze opdracht uit om azure-iothub te installeren op uw ontwikkelcomputer:

npm install azure-iothub --save

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;

Verbinding maken met IoT Hub

U kunt een back-endservice verbinden met IoT Hub met behulp van de volgende methoden:

Beleid voor gedeelde toegang
Microsoft Entra

Belangrijk

Verbinding maken met behulp van een beleid voor gedeelde toegang

Gebruik fromConnectionString om verbinding te maken met IoT Hub.

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

var connectionString = '{IoT hub device 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);

Verbinding maken met Microsoft Entra

Zie voor een overzicht van Node.js SDK-verificatie:

Microsoft Entra-app configureren

Clientgeheim
Certificaat
Referenties voor federatieve identiteit

Zie quickstart: Een toepassing registreren bij het Microsoft Identity Platform voor meer informatie over het instellen van een Microsoft Entra-app.

Verifiëren met DefaultAzureCredential

De eenvoudigste manier om Microsoft Entra te gebruiken om een back-endtoepassing ChainedTokenCredentialte verifiëren, is door DefaultAzureCredential te gebruiken, maar het wordt aanbevolen om een andere methode te gebruiken in een productieomgeving, inclusief een specifieke TokenCredential of geparseerde toepassing. Ter vereenvoudiging beschrijft deze sectie verificatie met behulp van DefaultAzureCredential en clientgeheim. Zie Referentieketens in de Azure Identity-clientbibliotheek voor JavaScript voor meer informatie over de voor- en nadelen van het gebruik DefaultAzureCredential

Microsoft Entra vereist dit pakket:

npm install --save @azure/identity

In dit voorbeeld zijn clientgeheim, client-id en tenant-id van Microsoft Entra-app-registratie toegevoegd aan omgevingsvariabelen. Deze omgevingsvariabelen worden gebruikt om DefaultAzureCredential de toepassing te verifiëren. Het resultaat van een geslaagde Microsoft Entra-verificatie is een beveiligingstokenreferentie die wordt doorgegeven aan een IoT Hub-verbindingsmethode.

import { DefaultAzureCredential } from "@azure/identity";

// Azure SDK clients accept the credential as a parameter
const credential = new DefaultAzureCredential();

Het resulterende referentietoken kan vervolgens worden doorgegeven aan fromTokenCredential om verbinding te maken met IoT Hub voor elke SDK-client die Microsoft Entra-referenties accepteert:

fromTokenCredential vereist twee parameters:

De URL van de Azure-service: de Azure-service-URL moet de indeling {Your Entra domain URL}.azure-devices.net hebben zonder voorvoegsel https:// . Bijvoorbeeld: MyAzureDomain.azure-devices.net.
Het Azure-referentietoken

In dit voorbeeld wordt de Azure-referentie verkregen met behulp van DefaultAzureCredential. De URL en referentie van het Azure-domein worden vervolgens opgegeven om Registry.fromTokenCredential de verbinding met IoT Hub te maken.

const { DefaultAzureCredential } = require("@azure/identity");

let Registry = require('azure-iothub').Registry;

// Define the client secret values
clientSecretValue = 'xxxxxxxxxxxxxxx'
clientID = 'xxxxxxxxxxxxxx'
tenantID = 'xxxxxxxxxxxxx'

// Set environment variables
process.env['AZURE_CLIENT_SECRET'] = clientSecretValue;
process.env['AZURE_CLIENT_ID'] = clientID;
process.env['AZURE_TENANT_ID'] = tenantID;

// Acquire a credential object
const credential = new DefaultAzureCredential()

// Create an instance of the IoTHub registry
hostName = 'MyAzureDomain.azure-devices.net';
let registry = Registry.fromTokenCredential(hostName,credential);

Codevoorbeelden

Zie Voorbeelden van Azure-identiteiten voor werkvoorbeelden van Microsoft Entra-serviceverificatie.

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

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 ontvanger van de berichtfeedback koppelen

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

De Azure IoT SDK voor Node.js biedt werkende voorbeelden van een service-app waarmee berichtentaken worden verzonden. Zie voor meer informatie:

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.

Delen via

Cloud-naar-apparaat-berichten verzenden en ontvangen

Overzicht

Inzicht in de berichtenwachtrij

Een apparaattoepassing maken

Vereist NuGet-pakket voor apparaten

Een apparaat verbinden met IoT Hub

Verifiëren met behulp van een gedeelde toegangssleutel

Verifiëren met behulp van een X.509-certificaat

Codevoorbeelden

Terugbellen

Navragen

Methode CompleteAsync

Bericht verlaten, weigeren of time-out

Polling-lus

Beleid voor opnieuw proberen van berichten ontvangen

Voorbeeld van SDK-bericht ontvangen

Een back-endtoepassing maken

Service NuGet-pakket toevoegen

Verbinding maken met IoT Hub

Verbinding maken met behulp van een beleid voor gedeelde toegang

Verbinding maken met Microsoft Entra

Microsoft Entra-app configureren

Verifiëren met DefaultAzureCredential

Voorbeeld van code

Een asynchroon cloud-naar-apparaat-bericht verzenden

Feedback over bezorging ontvangen

Het feedbackReceiver-object maken

Berichten verzenden met de Ack-parameter

Wachten om feedback te ontvangen

Opnieuw verbinding maken met serviceclient

Beleid voor opnieuw proberen van berichten verzenden

Voorbeeld van SDK-bericht verzenden

Een apparaattoepassing maken

Azure IoT Java SDK-bibliotheken importeren

Een apparaat verbinden met IoT Hub

Verifiëren met behulp van een gedeelde toegangssleutel

Verifiëren met behulp van een X.509-certificaat

Codevoorbeelden

De callback-methode voor berichten instellen

Een callback-handler voor berichten maken

Opties voor het afbreken en afwijzen van berichten

De callbackmethode voor de berichtstatus maken

De verbinding tussen apparaat en IoT Hub openen

Voorbeeld van SDK-bericht ontvangen

Een back-endtoepassing maken

De afhankelijkheidsinstructie toevoegen

Importinstructies toevoegen

Verbinding maken met de IoT Hub

Verbinding maken met behulp van een beleid voor gedeelde toegang

Het verbindingsprotocol definiëren

Het ServiceClient-object maken

De verbinding tussen de toepassing en IoT Hub openen

Verbinding maken met Microsoft Entra

Microsoft Entra-app configureren

Verifiëren met DefaultAzureCredential

Verifiëren met ClientSecretCredentialBuilder

Andere verificatieklassen

Codevoorbeelden

Een feedbackontvanger openen voor feedback over berichtbezorging

Berichteigenschappen toevoegen

Een asynchroon bericht maken en verzenden

Feedback ontvangen over de bezorging van berichten

Voorbeelden van sdk-berichten verzenden

Een apparaattoepassing maken

Instructie voor apparaatimport

Een apparaat verbinden met IoT Hub

Verifiëren met behulp van een gedeelde toegangssleutel

Verifiëren met behulp van een X.509-certificaat

Codevoorbeelden

Opnieuw verbinden afhandelen

Een berichthandler maken

De berichthandler toewijzen

Voorbeeld van SDK-bericht ontvangen

Een back-endtoepassing maken

Het IoTHubRegistryManager-object importeren

Verbinding maken met IoT Hub

Verbinding maken met behulp van een beleid voor gedeelde toegang

Verbinding maken met Microsoft Entra

Microsoft Entra-app configureren