Cloud-naar-apparaat-berichten verzenden en ontvangen

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 binnenkomende berichten.

Vereist NuGet-pakket voor apparaat

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

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 IoT Hub primaire verbindingsreeks en de apparaat-ID op aan DeviceClient met behulp van de CreateFromConnectionString methode. 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 moduleclientexemplaar tijdens het initialiseren mogelijk wordt gemaakt.

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:

1. Gebruik DeviceAuthenticationWithX509Certificate om een object te maken dat apparaat- en certificaatgegevens bevat. DeviceAuthenticationWithX509Certificate wordt doorgegeven als de tweede parameter aan DeviceClient.Create (stap 2).

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 authDeviceAuthenticationWithX509Certificate 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:

• Identiteiten verifiëren met X.509-certificaten
• Zelfstudie: Certificaten maken en uploaden voor testen

Codevoorbeelden

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

• Verbinding maken met X.509-certificaat
• DeviceClientX509AuthenticationE2ETests
• Begeleid project: IoT-apparaten veilig en op schaal inrichten met IoT Hub Device Provisioning Service

Terugroepfunctie

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 naar ReceiveAsync kan de volgende vormen 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). Door meer HTTP 1-verzoeken uit te sturen, zorgt IoT Hub voor een beperking van de aanvragen. 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 afbreken, 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 erin dat IoT Hub het bericht in de apparaatwachtrij bewaart voor toekomstig gebruik.
• 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 ReceiveAsync gebruikt met een time-outwaarde of de standaardtime-out, wacht elke oproep in de lus op ReceiveAsync gedurende de opgegeven time-outperiode. Als een time-out optreedt bij ReceiveAsync, wordt een null waarde geretourneerd en de lus gaat verder.

Wanneer een bericht wordt ontvangen, wordt er een Task object geretourneerd door ReceiveAsync dat moet worden doorgegeven aan CompleteAsync. Een aanroep naar CompleteAsync stelt IoT Hub in staat om het opgegeven bericht uit de berichtenwachtrij te verwijderen op basis van de Task parameter.

In dit voorbeeld voert de lus ReceiveAsync uit 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 het ontvangen van een SDK-bericht

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, maakt een back-endtoepassing van een oplossing verbinding met een IoT Hub en worden berichten verzonden naar IoT Hub die gecodeerd zijn voor 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

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 de serviceclient tijdens de initialisatie kan worden ingesteld. 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
• Referentiebewijs voor federatieve identiteit

Voor Microsoft Entra-apps zijn mogelijk specifieke rolmachtigingen vereist, afhankelijk van bewerkingen die worden uitgevoerd. Voorbeeld: IoT Hub Twin Contributor is vereist om lees- en schrijftoegang tot een IoT Hub-apparaat en module twins mogelijk te maken. 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

nl-NL: De eenvoudigste manier om Microsoft Entra te gebruiken om een back-endtoepassing te verifiëren, is door DefaultAzureCredential te gebruiken, maar het wordt aanbevolen om in een productieomgeving een andere methode te gebruiken, zoals een specifieke of een uitgeklede TokenCredential. 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:

• JobClient
• RegistryManager
• DigitalTwinClient
• Klantenservice

In dit voorbeeld wordt het TokenCredential doorgegeven aan ServiceClient.Create om een ServiceClient verbindingsobject te creëren.

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

In dit voorbeeld wordt het TokenCredential doorgegeven aan RegistryManager.Create om 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 tekenreeksidentificatie van het doelapparaat.
• Het bericht van de cloud naar het apparaat. 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 bewerkingen voor het ontvangen van feedback uit te voeren.

var feedbackReceiver = serviceClient.GetFeedbackReceiver();

Berichten versturen met behulp van 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: je ontvangt een feedbackbericht als het bericht is verlopen (of het maximum aantal bezorgpogingen is bereikt) zonder dat het door 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 oproep naar ReceiveAsync wacht op de time-outperiode die is gedefinieerd voor het ServiceClient object.

• Als een ReceiveAsync time-out verloopt zonder ontvangen bericht, retourneert ReceiveAsyncnull en loopt de lus verder.
• Als er een feedbackbericht wordt ontvangen, wordt er een Task-object geretourneerd dat ReceiveAsync moet worden doorgegeven aan CompleteAsync, samen met de annuleringstoken. Een oproep verwijdert het opgegeven verzonden bericht uit de berichtenwachtrij op basis van de CompleteAsync 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 er een beperking/quotum overschreden is, een uitzondering, bewaakt en/of wijzigt u de frequentie van het verzenden van verzoeken, of werkt u uw hubinstantie schaaleenheid 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.

SDK-voorbeeld voor het verzenden van berichten

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

Verifiëren met behulp van een gedeelde toegangssleutel

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

• connString - De verbindingsreeks van het IoT-apparaat. 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:

1. Bouw het SSLContext-object met buildSSLContext.
2. Voeg de SSLContext informatie toe aan een ClientOptions-object .
3. 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:

• Identiteiten verifiëren met X.509-certificaten
• Zelfstudie: Certificaten maken en uploaden voor testen

Codevoorbeelden

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

• Voorbeeld van send-receive x509
• Gebeurtenis x509 verzenden

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 indien niet 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 IotHubMessageResult.COMPLETE retourneren wanneer de verwerking succesvol is voltooid, waarbij IoT Hub wordt geïnformeerd dat het bericht uit de berichtenwachtrij moet worden verwijderd, onafhankelijk van het protocol dat het 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 moet leiden tot IotHubMessageResult.COMPLETE, kan het nodig zijn om een bericht achterwege te laten of af te wijzen.

• Met AMQP en HTTPS, maar niet met MQTT, kan een toepassing het volgende doen:
  • IotHubMessageResult.ABANDON het bericht. IoT Hub plaatst het opnieuw in de wachtrij en verzendt het later opnieuw.
  • IotHubMessageResult.REJECT het bericht. IoT Hub plaatst het bericht niet opnieuw in de wachtrij en verwijdert het definitief uit de berichtenwachtrij.
• Clients die MQTT of MQTT_WS gebruiken, kunnen geen ABANDON- of REJECT-berichten 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.

Maak de callbackmethode voor berichtstatus.

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 verbroken berichtenverbinding detecteren en proberen opnieuw verbinding te 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();

Bel connectionStatusChangeContext.getCause() om de reden voor de wijziging in 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 ontvangen van SDK-berichten in dit artikel, voor een compleet voorbeeld dat toont hoe u de statuswijziging, de reden voor de wijziging in de apparaatstatus en de context voor de callback-methode voor statuswijziging kunt extraheren.

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 het ontvangen van een SDK-bericht

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.

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

Importverklaringen 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

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 aan en voorzie het van de IoT Hub-verbindingstekenreeks en het protocol.

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

De verbinding tussen de toepassing en IoT Hub openen

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

serviceClient.open();

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.

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

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
• Referentiebewijs voor federatieve identiteit

Voor Microsoft Entra-apps zijn mogelijk specifieke rolmachtigingen vereist, afhankelijk van bewerkingen die worden uitgevoerd. Voorbeeld: IoT Hub Twin Contributor is vereist om lees- en schrijftoegang tot een IoT Hub-apparaat en module twins mogelijk te maken. 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

nl-NL: De eenvoudigste manier om Microsoft Entra te gebruiken om een back-endtoepassing te verifiëren, is door DefaultAzureCredential te gebruiken, maar het wordt aanbevolen om in een productieomgeving een andere methode te gebruiken, zoals een specifieke of een uitgeklede TokenCredential. 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 TokenCredential is gemaakt, geeft u deze door aan ServiceClient of een andere builder als de parameter referentiegegevens.

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. Wanneer succesvol, retourneert deze methode een TokenCredential die kan worden doorgegeven aan ServiceClient of een andere builder als de parameter 'credential'.

In dit voorbeeld zijn clientgeheim, client-id en tenant-id van Microsoft Entra-app-registratie toegevoegd aan omgevingsvariabelen. Deze omgevingsvariabelen worden door ClientSecretCredentialBuilder gebruikt om de referentie op te bouwen.

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:

• AuthorizationCodeCredential
• AzureCliCredential
• AzureDeveloperCliCredential
• AzurePipelinesCredential
• ChainedTokenCredential
• ClientAssertionCredential
• ClientCertificateCredential
• DeviceCodeCredential
• Milieu Credential
• InteractiveBrowserCredential
• Beheerde IdentityCredential
• NamensOfCredential

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 retourneert in plaats van een Message.

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

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 een bevestiging aan te vragen van wel/niet afgeleverd aan de berichtenwachtrij van IoT Hub. In dit voorbeeld wordt de gevraagde bevestiging Full 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 wordt de FeedbackBatch ontvanger gemaakt en wordt getEnqueuedTimeUtc aangeroepen, 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 berichten verzonden door SDK

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.

Importverklaring voor apparaat

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

Verifiëren met behulp van een gedeelde toegangssleutel

Een apparaat verbinden met IoT Hub:

1. Roep create_from_connection_string aan om de primaire verbindingsreeks van het apparaat toe te voegen.
2. 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:

1. Gebruik create_from_x509_certificate om de X.509-certificaatparameters toe te voegen
2. Roep connect aan om de apparaatclient aan te sluiten

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:

• Identiteiten verifiëren met X.509-certificaten
• Zelfstudie: Certificaten maken en uploaden voor testen

Codevoorbeelden

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

Herverbinding afhandelen

IoTHubDeviceClient probeert standaard een verbroken verbinding te herstellen. Gedrag voor opnieuw verbinden wordt bepaald door de IoTHubDeviceClientconnection_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 callbackberichtverwerker.

In dit voorbeeld wordt message_handler aangeroepen wanneer een bericht wordt ontvangen. De berichteigenschappen (.items) worden afgedrukt op de console via 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))

Wijs de berichthandler toe.

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 IoTHubDeviceClientclient 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 het ontvangen van een SDK-bericht

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

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

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
• Referentiebewijs voor federatieve identiteit

Voor Microsoft Entra-apps zijn mogelijk specifieke rolmachtigingen vereist, afhankelijk van bewerkingen die worden uitgevoerd. Voorbeeld: IoT Hub Twin Contributor is vereist om lees- en schrijftoegang tot een IoT Hub-apparaat en module twins mogelijk te maken. 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

nl-NL: De eenvoudigste manier om Microsoft Entra te gebruiken om een back-endtoepassing te verifiëren, is door DefaultAzureCredential te gebruiken, maar het wordt aanbevolen om in een productieomgeving een andere methode te gebruiken, zoals een specifieke of een uitgeklede TokenCredential. 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:

• JobClient
• RegistryManager
• DigitalTwinClient
• Klantenservice

In dit voorbeeld wordt het TokenCredential doorgegeven aan ServiceClient.Create om een ServiceClient verbindingsobject te creëren.

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

In dit voorbeeld wordt het TokenCredential doorgegeven aan RegistryManager.Create om 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 tekenreeksidentificatie van het doelapparaat.
• Het bericht van de cloud naar het apparaat. 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)

SDK-voorbeeld voor het verzenden van berichten

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 in staat zijn om verbroken verbindingen te detecteren en af te handelen wanneer 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

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:

1. Roep fromConnectionString aan om de apparaat- of identiteitsmodule-verbindingsreeks en het transporttype toe te voegen aan het Client-object. 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

2. Configureer een JSON-variabele met certificaatgegevens en geef deze door aan DeviceClientOptions.

3. Roep setOptions aan om een X.509-certificaat en -sleutel (en eventueel een wachtwoordzin) toe te voegen aan het clienttransport.

4. 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:

• Identiteiten verifiëren met X.509-certificaten
• Certificaten maken en uploaden voor testen

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 het gebruik van Http controleert het Client exemplaar niet vaak 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.

Hernieuwde afleverpogingen

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.

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;

Voeg de apparaatverbindingstekst en het transportprotocol toe.

Aanroepen vanuitConnectionString om verbindingsparameters voor apparaten op te geven:

• connStr - de verbindingsreeks van het apparaat.
• 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 verbindingsafhandelaar wordt aangeroepen wanneer de verbinding is verbroken. Een afhandelaar voor verbreken van de verbinding is handig voor het implementeren van code voor opnieuw verbinden.

In dit voorbeeld wordt de verbrekingsfout onderschept en op de console 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 .

• Verbindingsafhandelaar
• Errorverwerker
• Afhandelaar voor verbreken van verbinding
• Berichthandler

Dit voorbeeld omvat de eerder gedefinieerde bericht- en ontkoppelingshandlers.

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, maakt een back-endtoepassing van een oplossing verbinding met een IoT Hub en worden berichten verzonden naar IoT Hub die gecodeerd zijn voor 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 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

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

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.

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

• Aan de slag met gebruikersverificatie in Azure
• Azure Identity-clientbibliotheek voor JavaScript

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
• Referentiebewijs voor federatieve identiteit

Voor Microsoft Entra-apps zijn mogelijk specifieke rolmachtigingen vereist, afhankelijk van bewerkingen die worden uitgevoerd. Voorbeeld: IoT Hub Twin Contributor is vereist om lees- en schrijftoegang tot een IoT Hub-apparaat en module twins mogelijk te maken. 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

nl-NL: De eenvoudigste manier om Microsoft Entra te gebruiken om een back-endtoepassing te verifiëren, is door DefaultAzureCredential te gebruiken, maar het wordt aanbevolen om in een productieomgeving een andere methode te gebruiken, zoals een specifieke of een uitgeklede TokenCredential. 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

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

• Register
• Klant
• JobClient

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 Azure domein-URL en referenties worden vervolgens aan Registry.fromTokenCredential verstrekt om 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

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 eigenschap voor ontvangstbevestiging ack. 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 bezorgpogingen is bereikt) zonder door het apparaat te zijn 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 Client via 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 resultatenhandler voor het voltooien van berichten definiëren

De callbackfunctie voor de voltooiing van 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.

De code send wordt gebruikt om een cloud-naar-apparaat-bericht te verzenden 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'));
  }
});

SDK-voorbeeld voor het verzenden van berichten

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.