Delen via

Aan de slag met apparaatbeheer

  • Artikel

Back-end-apps kunnen primitieven van Azure IoT Hub, zoals apparaatdubbels en directe methoden, gebruiken om acties voor apparaatbeheer op afstand op apparaten te starten en te bewaken.

Gebruik een directe methode vanuit een back-endtoepassing om acties voor apparaatbeheer te initiëren, zoals opnieuw opstarten, fabrieksinstellingen terugzetten en firmware-update.

Het apparaat is verantwoordelijk voor:

  • De aanvraag voor de directe methode verwerken die is verzonden vanuit IoT Hub
  • De bijbehorende apparaatspecifieke actie op het apparaat initiëren
  • Statusupdates leveren via gerapporteerde eigenschappen aan IoT Hub

In dit artikel leest u hoe een back-end-app en een apparaat-app kunnen samenwerken om een actie op afstand te starten en te bewaken met behulp van een directe methode.

  • Een service-app roept een directe methode aan om opnieuw op te starten in een apparaat-app via een IoT-hub.
  • Een apparaat-app verwerkt een directe methode om een apparaat opnieuw op te starten.

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.

Notitie

Dit artikel is bedoeld als aanvulling op Azure IoT SDK-voorbeelden waarnaar in dit artikel wordt verwezen. U kunt SDK-hulpprogramma's gebruiken om zowel apparaat- als back-endtoepassingen te bouwen.

Vereisten

  • Een IoT-hub

  • Een geregistreerd apparaat

  • Als uw toepassing gebruikmaakt van het MQTT-protocol, moet u ervoor zorgen dat poort 8883 is geopend in uw firewall. Het MQTT-protocol communiceert via poort 8883. Deze poort is in sommige netwerkomgevingen van bedrijven en onderwijsinstellingen mogelijk geblokkeerd. Zie Verbinding maken met IoT Hub (MQTT) voor meer informatie en manieren om dit probleem te omzeilen.

  • Visual Studio vereist

Overzicht

In dit artikel wordt beschreven hoe u de Azure IoT SDK voor .NET gebruikt om toepassingscode voor apparaten en back-endservices te maken voor directe berichten van apparaten.

Een apparaattoepassing maken

In deze sectie wordt beschreven hoe u apparaattoepassingscode gebruikt om een callback-listener voor directe methoden te maken.

Vereiste NuGet-pakketten 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 te communiceren met apparaatberichten van het apparaat.

Maak verbinding met het apparaat met behulp van de methode CreateFromConnectionString, samen met het apparaat verbindingsreeks en het transportprotocol voor verbindingen.

De CreateFromConnectionStringtransportprotocolparameter TransportType ondersteunt de volgende transportprotocollen:

  • Mqtt
  • Mqtt_WebSocket_Only
  • Mqtt_Tcp_Only
  • Amqp
  • Amqp_WebSocket_Only
  • Amqp_Tcp_Only
  • Http1

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:

Codevoorbeelden

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

Een callback-listener voor directe methoden maken

Gebruik SetMethodHandlerAsync om een callback-listener voor directe methoden te initialiseren. De listener is gekoppeld aan een trefwoord voor de methodenaam, zoals 'reboot'. De naam van de methode kan worden gebruikt in een IoT Hub- of back-endtoepassing om de callback-methode op het apparaat te activeren.

In dit voorbeeld wordt een callback-listener ingesteld die onReboot wordt geactiveerd wanneer de naam van de directe methode opnieuw opstarten wordt aangeroepen.

try
{
      // setup callback for "reboot" method
      deviceClient.SetMethodHandlerAsync("reboot", onReboot, null).Wait();
      Console.WriteLine("Waiting for reboot method\n Press enter to exit.");
      Console.ReadLine();

      Console.WriteLine("Exiting...");

      // as a good practice, remove the "reboot" handler
      deviceClient.SetMethodHandlerAsync("reboot", null, null).Wait();
      deviceClient.CloseAsync().Wait();
}
catch (Exception ex)
{
      Console.WriteLine();
      Console.WriteLine("Error in sample: {0}", ex.Message);
}

Als u doorgaat met het voorbeeld, implementeert de callback-methode onReboot de directe methode op het apparaat.

De handler-functie roept MethodResponse aan om een antwoordbevestiging naar de aanroepende toepassing te verzenden.

static Task<MethodResponse> onReboot(MethodRequest methodRequest, object userContext)
{
      // In a production device, you would trigger a reboot 
      // scheduled to start after this method returns.
      // For this sample, we simulate the reboot by writing to the console
      // and updating the reported properties.
      try
      {
         Console.WriteLine("Rebooting!");
      }
      catch (Exception ex)
      {
         Console.WriteLine();
         Console.WriteLine("Error in sample: {0}", ex.Message);
      }

      string result = @"{""result"":""Reboot started.""}";
      return Task.FromResult(new MethodResponse(Encoding.UTF8.GetBytes(result), 200));
}

Notitie

Om het eenvoudig te houden, implementeert dit artikel geen beleid voor opnieuw proberen. In productiecode moet u beleid voor opnieuw proberen implementeren (zoals een exponentiële uitstel), zoals wordt voorgesteld in de afhandeling van tijdelijke fouten.

Voorbeelden van SDK-apparaten

De Azure IoT SDK voor .NET biedt werkende voorbeelden van apparaat-apps die directe methodetaken verwerken. Zie voor meer informatie:

Een back-endtoepassing maken

In deze sectie wordt beschreven hoe u een directe methode op een apparaat activeert.

De ServiceClient-klasse bevat alle methoden die nodig zijn om een back-endtoepassing te maken om directe methode-aanroepen naar apparaten te verzenden.

Vereist NuGet-servicepakket

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

Voeg deze using instructies toe om de servicebibliotheek te gebruiken.

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

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

Als u een directe methode wilt aanroepen op een apparaat via IoT Hub, heeft uw service de machtiging voor serviceverbinding nodig. Standaard wordt elke IoT Hub gemaakt met een gedeeld toegangsbeleid met de naam service die deze machtiging verleent.

Geef als parameter het CreateFromConnectionStringbeleid voor gedeelde toegang van de service op. Zie Toegang tot IoT Hub beheren met handtekeningen voor gedeelde toegang voor meer informatie over beleid voor gedeelde toegang.

ServiceClient serviceClient;
string connectionString = "{IoT hub service shared access policy 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 methode op een apparaat aanroepen

Een methode op een apparaat aanroepen:

  1. Maak een CloudToDeviceMethod-object . Geef de naam van de directe methode van het apparaat door als een parameter.
  2. Roep InvokeDeviceMethodAsync aan om de methode op het apparaat aan te roepen.

In dit voorbeeld wordt de methode 'opnieuw opstarten' aangeroepen om een herstart op het apparaat te starten. De methode 'reboot' is toegewezen aan een listener op het apparaat, zoals beschreven in de sectie Callback-listener voor directe methoden maken van dit artikel.

string targetDevice = "myDeviceId";
CloudToDeviceMethod method = new CloudToDeviceMethod("reboot");
method.ResponseTimeout = TimeSpan.FromSeconds(30);

CloudToDeviceMethodResult response = await serviceClient.InvokeDeviceMethodAsync(targetDevice, method);

Console.WriteLine("Invoked firmware update on device.");

Voorbeelden van SDK-service

De Azure IoT SDK voor .NET biedt werkende voorbeelden van service-apps die berichttaken verwerken. Zie voor meer informatie:

  • Vereist Java SE Development Kit 8. Zorg ervoor dat u Java 8 selecteert onder Langetermijnondersteuning om naar downloads voor JDK 8 te gaan.

Overzicht

In dit artikel wordt beschreven hoe u de Azure IoT SDK voor Java gebruikt om toepassingscode voor apparaten en back-endservices te maken voor directe methoden voor apparaten.

Een apparaattoepassing maken

In deze sectie wordt beschreven hoe u apparaattoepassingscode gebruikt om een callback-listener voor directe methoden te maken.

De DeviceClient-klasse bevat alle methoden die u nodig hebt om te communiceren met directe methoden op het apparaat.

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.

Instructies voor apparaatimport

Gebruik de volgende instructies voor het importeren van apparaten voor toegang tot de Azure IoT SDK voor Java.

import com.microsoft.azure.sdk.iot.device.*;
import com.microsoft.azure.sdk.iot.device.exceptions.IotHubClientException;
import com.microsoft.azure.sdk.iot.device.twin.DirectMethodPayload;
import com.microsoft.azure.sdk.iot.device.twin.DirectMethodResponse;
import com.microsoft.azure.sdk.iot.device.twin.MethodCallback;
import com.microsoft.azure.sdk.iot.device.transport.IotHubConnectionStatus;
import com.microsoft.azure.sdk.iot.device.twin.SubscriptionAcknowledgedCallback;

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

Verbinding maken met een apparaat:

  1. Gebruik IotHubClientProtocol om een transportprotocol te kiezen. Voorbeeld:

    IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;

  2. Gebruik de DeviceClient constructor om het primaire verbindingsreeks en protocol van het apparaat toe te voegen.

    String connString = "{IoT hub device connection string}";
DeviceClient client = new DeviceClient(connString, protocol);

  3. Open gebruiken om het apparaat te verbinden met IoT Hub. Als de client al is geopend, doet de methode niets.

    client.open(true);

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:

Codevoorbeelden

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

Een callback-listener voor directe methoden maken

Gebruik subscribeToMethods om een callback-listener voor directe methoden te initialiseren. subscribeToMethods luistert naar binnenkomende directe methoden totdat de verbinding is beëindigd. De naam en nettolading van de methode worden ontvangen voor elke aanroep van de directe methode.

De listener moet DirectMethodResponse aanroepen om een bevestiging van een methodeantwoord naar de aanroepende toepassing te verzenden.

Bijvoorbeeld:

client.subscribeToMethods(
    (methodName, methodData, context) ->
    {
        System.out.println("Received a direct method invocation with name " + methodName + " and payload " + methodData.getPayloadAsJsonString());
        return new DirectMethodResponse(200, methodData);
    },
    null);
System.out.println("Successfully subscribed to direct methods");

Notitie

Om het eenvoudig te houden, implementeert dit artikel geen beleid voor opnieuw proberen. In productiecode moet u beleid voor opnieuw proberen implementeren (zoals een exponentiële uitstel), zoals wordt voorgesteld in de afhandeling van tijdelijke fouten.

Voorbeelden van SDK-apparaten

De Azure IoT SDK voor Java bevat een werkend voorbeeld om de concepten van de apparaat-app te testen die in dit artikel worden beschreven. Zie Voorbeeld van directe methode voor meer informatie.

Een back-endtoepassing maken

In deze sectie wordt beschreven hoe u een externe herstart op een apparaat start met behulp van een directe methode.

De ServiceClientklasse DeviceMethod bevat methoden die services kunnen gebruiken voor toegang tot directe methoden.

Instructies voor het importeren van services

Gebruik de volgende importinstructies voor services voor toegang tot de Azure IoT SDK voor Java.

import com.microsoft.azure.sdk.iot.service.methods.DirectMethodRequestOptions;
import com.microsoft.azure.sdk.iot.service.methods.DirectMethodsClient;
import com.microsoft.azure.sdk.iot.service.methods.DirectMethodResponse;

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

Gebruik de DeviceMethod-constructor om de primaire verbindingsreeks van de service toe te voegen en verbinding te maken met IoT Hub.

Als u een directe methode wilt aanroepen op een apparaat via IoT Hub, heeft uw service de machtiging voor serviceverbinding nodig. Standaard wordt elke IoT Hub gemaakt met een gedeeld toegangsbeleid met de naam service die deze machtiging verleent.

Als parameter voor de DeviceMethod constructor levert u het beleid voor gedeelde toegang van de service . Zie Toegang tot IoT Hub beheren met handtekeningen voor gedeelde toegang voor meer informatie over beleid voor gedeelde toegang.

Voorbeeld:

String iotHubConnectionString = "HostName=xxxxx.azure-devices.net;SharedAccessKeyName=service;SharedAccessKey=xxxxxxxxxxxxxxxxxxxxxxxx";
DeviceMethod methodClient = new DeviceMethod(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.

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

In dit voorbeeld zijn clientgeheim, client-id en tenant-id van Microsoft Entra-app-registratie toegevoegd aan omgevingsvariabelen. Deze omgevingsvariabelen worden gebruikt om ClientSecretCredentialBuilder de referentie 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:

Codevoorbeelden

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

Een methode op een apparaat aanroepen

Roep DeviceMethod.invoke aan om een methode op een apparaat aan te roepen en de resultaatstatus te retourneren.

De invoke nettoladingparameter is optioneel. Gebruik null deze optie als er geen nettolading is opgegeven. De nettoladingparameter kan verschillende gegevensformulieren aannemen, waaronder tekenreeks, bytematrix en HashMap. Zie Directe methodetests voor voorbeelden.

In dit voorbeeld wordt de methode 'opnieuw opstarten' aangeroepen om een herstart op het apparaat te starten. De methode 'reboot' is toegewezen aan een listener op het apparaat, zoals beschreven in de sectie Callback-listener voor directe methoden maken van dit artikel.

Voorbeeld:

String deviceId = "myFirstDevice";
String methodName = "reboot";
String payload = "Test payload";
Long responseTimeout = TimeUnit.SECONDS.toSeconds(30);
Long connectTimeout = TimeUnit.SECONDS.toSeconds(5);

MethodResult result = methodClient.invoke(deviceId, methodName, responseTimeout, connectTimeout, payload);
if (result == null)
{
    throw new IOException("Method invoke returns null");
}
System.out.println("Status=" + result.getStatus());

Voorbeelden van SDK-service

De Azure IoT SDK voor Java biedt een werkend voorbeeld van service-apps die directe methodetaken verwerken. Zie voor meer informatie:

  • Python SDK : Python-versie 3.7 of hoger wordt aanbevolen. Zorg ervoor dat u de 32-bits of 64-bits installatie gebruikt, zoals vereist door uw configuratie. Zorg ervoor dat u Python toevoegt aan uw platformspecifieke omgevingsvariabele als u hierom wordt gevraagd tijdens de installatie.

Overzicht

In dit artikel wordt beschreven hoe u de Azure IoT SDK voor Python gebruikt om toepassingscode voor apparaten en back-endservices te maken voor directe methoden voor apparaten.

Pakketten installeren

De azure-iot-device-bibliotheek moet zijn geïnstalleerd om apparaattoepassingen te maken.

pip install azure-iot-device

De azure-iot-hub-bibliotheek moet zijn geïnstalleerd om back-endservicetoepassingen te maken.

pip install azure-iot-hub

Een apparaattoepassing maken

In deze sectie wordt beschreven hoe u apparaattoepassingscode gebruikt om een callback-listener voor directe methoden te maken.

De Klasse IoTHubDeviceClient bevat methoden die kunnen worden gebruikt om met directe methoden te werken.

Instructie voor apparaatimport

Voeg deze importinstructie toe voor toegang IoTHubDeviceClient tot en MethodResponse.

# import the device client library
from azure.iot.device import IoTHubDeviceClient, MethodResponse

Verbinding maken met een apparaat

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

Gebruik create_from_connection_string om een toepassing te verbinden met een apparaat met behulp van een apparaat verbindingsreeks.

# substitute the device connection string in conn_str
# and add it to the IoTHubDeviceClient object
conn_str = "{IoT hub device connection string}"
device_client = IoTHubDeviceClient.create_from_connection_string(conn_str)

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

Een directe methode callback maken

Gebruik on_method_request_received om een handlerfunctie of coroutine te maken die wordt aangeroepen wanneer een directe methode wordt ontvangen. De listener is gekoppeld aan een trefwoord voor de methodenaam, zoals 'reboot'. De naam van de methode kan worden gebruikt in een IoT Hub- of back-endtoepassing om de callback-methode op het apparaat te activeren.

De handler-functie moet een MethodResponse maken en deze doorgeven aan send_method_response om een bevestiging van een directe methodeantwoord te verzenden naar de aanroepende toepassing.

In dit voorbeeld wordt een handler voor directe methoden ingesteld met de naam method_request_handler.

try:
    # Attach the handler to the client
    client.on_method_request_received = method_request_handler
except:
    # In the event of failure, clean up
    client.shutdown()

In dit voorbeeld implementeert de method_request_handler callback-methode de directe methode op het apparaat. De code wordt uitgevoerd wanneer de directe methode rebootDevice wordt aangeroepen vanuit een servicetoepassing. De methode roept send_method_response aan om een bevestiging van een directe methodereactie naar de aanroepende toepassing te verzenden.

# Define the handler for method requests
def method_request_handler(method_request):
    if method_request.name == "rebootDevice":
        # Act on the method by rebooting the device
        print("Rebooting device")
        time.sleep(20)
        print("Device rebooted")
        # Create a method response indicating the method request was resolved
        resp_status = 200
        resp_payload = {"Response": "This is the response from the device"}
        method_response = MethodResponse(method_request.request_id, resp_status, resp_payload)
    else:
        # Create a method response indicating the method request was for an unknown method
        resp_status = 404
        resp_payload = {"Response": "Unknown method"}
        method_response = MethodResponse(method_request.request_id, resp_status, resp_payload)

    # Send the method response
    client.send_method_response(method_response)

Voorbeelden van SDK-apparaten

De Azure IoT SDK voor Python biedt een werkend voorbeeld van een apparaat-app die directe methodetaken verwerkt. Zie De methode Receive Direct voor meer informatie.

Een back-endtoepassing maken

In deze sectie wordt beschreven hoe u een back-endservicetoepassing gebruikt om een directe methode op een apparaat aan te roepen.

De IoTHubRegistryManager-klasse bevat alle methoden die nodig zijn om een back-endtoepassing te maken om berichten naar een apparaat te verzenden.

Instructies voor het importeren van services

Voeg deze importinstructies toe om verbinding te maken met IoT Hub, directe methoden voor cloud-naar-apparaat te verzenden en reacties van directe methoden voor apparaten te ontvangen.

from azure.iot.hub import IoTHubRegistryManager
from azure.iot.hub.models import CloudToDeviceMethod, CloudToDeviceMethodResult

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

Maak verbinding met IoT Hub met behulp van from_connection_string.

Als u een directe methode wilt aanroepen op een apparaat via IoT Hub, heeft uw service de machtiging voor serviceverbinding nodig. Standaard wordt elke IoT Hub gemaakt met een gedeeld toegangsbeleid met de naam service die deze machtiging verleent.

Geef als parameter het from_connection_stringbeleid voor gedeelde toegang van de service op. Zie Toegang tot IoT Hub beheren met handtekeningen voor gedeelde toegang voor meer informatie over beleid voor gedeelde toegang.

Voorbeeld:

# Connect to IoT hub
IOTHUB_CONNECTION_STRING = "{IoT hub service connection string}"
iothub_registry_manager = IoTHubRegistryManager.from_connection_string(IOTHUB_CONNECTION_STRING)

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 Python-apps verifiëren bij Azure-services met behulp van de Azure SDK voor Python voor Python voor een overzicht van python-verificatie

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 Referentieketens in de Azure Identity-clientbibliotheek voor Python 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 importpakket en de bijbehorende import instructie:

pip install azure-identity

from azure.identity import DefaultAzureCredential

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.

from azure.identity import DefaultAzureCredential
credential = DefaultAzureCredential()

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

from_token_credential 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 referenties van de Azure-service worden vervolgens opgegeven om IoTHubRegistryManager.from_token_credential de verbinding met IoT Hub te maken.

import sys
import os

from azure.identity import DefaultAzureCredential
from azure.iot.hub import IoTHubRegistryManager

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

# Set environment variables
os.environ['AZURE_CLIENT_SECRET'] = clientSecretValue
os.environ['AZURE_CLIENT_ID'] = clientID
os.environ['AZURE_TENANT_ID'] = tenantID

# Acquire a credential object
credential = DefaultAzureCredential()

# Use Entra to authorize IoT Hub service
print("Connecting to IoTHubRegistryManager...")
iothub_registry_manager = IoTHubRegistryManager.from_token_credential(
url="MyAzureDomain.azure-devices.net",
token_credential=credential)
Codevoorbeelden

Zie Microsoft Authentication Library (MSAL) voor Python voor werkende voorbeelden van Microsoft Entra-serviceverificatie.

Een methode op een apparaat aanroepen

U kunt een directe methode aanroepen op naam op een apparaat. De naam van de methode identificeert de methode. In het volgende en vorige apparaatvoorbeeld dat wordt weergegeven in Create a direct method callback, is de naam van de directe methode 'rebootDevice'.

Een directe methode op een apparaat aanroepen:

  1. Maak een CloudToDeviceMethod-object . Geef de naam en nettolading van de methode op als parameters.
  2. Roep invoke_device_method aan om een directe methode op een apparaat aan te roepen. Geef de apparaat-id en CloudToDeviceMethod het nettoladingobject op als parameters.

In dit voorbeeld wordt aangeroepen CloudToDeviceMethod om een directe methode met de naam rebootDevice op een apparaat aan te roepen. Nadat de directe methode is aangeroepen, wordt de nettolading van de directe methodeantwoord weergegeven.

CONNECTION_STRING = "{IoTHubConnectionString}"
DEVICE_ID = "{deviceId}"

METHOD_NAME = "rebootDevice"
METHOD_PAYLOAD = "{\"method_number\":\"42\"}"
TIMEOUT = 60
WAIT_COUNT = 10

try:
    print ( "" )
    print ( "Invoking device to reboot..." )

    # Call the direct method.
    deviceMethod = CloudToDeviceMethod(method_name=METHOD_NAME, payload=METHOD_PAYLOAD)
    response = registry_manager.invoke_device_method(DEVICE_ID, deviceMethod)

    print ( "Successfully invoked the device to reboot." )

    print ( "The device has returned this payload:" )
    print ( response.payload )

except Exception as ex:
    print ( "" )
    print ( "Unexpected error {0}".format(ex) )
    return

Voorbeelden van SDK-service

De Azure IoT SDK voor Python biedt werkende voorbeelden van service-apps die directe methodetaken verwerken. Zie voor meer informatie:

  • Vereist Node.js versie 10.0.x of hoger

Overzicht

In dit artikel wordt beschreven hoe u de Azure IoT SDK voor Node.js gebruikt om code voor apparaat- en back-endservicetoepassingen te maken voor directe methoden voor apparaten.

Een apparaattoepassing maken

In deze sectie wordt beschreven hoe u apparaattoepassingscode gebruikt om een directe methode callback te maken.

SDK-pakket 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

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

  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:

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.

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);
De verbinding met IoT Hub openen

Gebruik de open methode om verbinding te openen tussen een IoT-apparaat en IoT Hub.

Voorbeeld:

client.open(function(err) {
  if (err) {
    console.error('error connecting to hub: ' + err);
    process.exit(1);
  }
})

Een directe methode callback maken

Roep onDeviceMethod aan om een callback-handlerfunctie of coroutine te maken die wordt aangeroepen wanneer een directe methode wordt ontvangen. De listener is gekoppeld aan een trefwoord voor de methodenaam, zoals 'reboot'. De naam van de methode kan worden gebruikt in een IoT Hub- of back-endtoepassing om de callback-methode op het apparaat te activeren.

De callback-handlerfunctie moet worden aangeroepen response.send om een antwoordbevestigingsbericht naar de aanroepende toepassing te verzenden.

In dit voorbeeld wordt een directe methodehandler ingesteld die wordt aangeroepen onReboot wanneer de directe methodenaam opnieuw opstarten wordt gebruikt.

client.onDeviceMethod('reboot', onReboot);

In dit voorbeeld implementeert de onReboot callback-methode de directe methode op het apparaat. De code wordt uitgevoerd wanneer de directe methode voor opnieuw opstarten wordt aangeroepen vanuit een servicetoepassing. De functie roept response.send een antwoordbevestigingsbericht naar de aanroepende toepassing aan.

var onReboot = function(request, response) {

    // Respond the cloud app for the direct method
    response.send(200, 'Reboot started', function(err) {
        if (err) {
            console.error('An error occurred when sending a method response:\n' + err.toString());
        } else {
            console.log('Response to method \'' + request.methodName + '\' sent successfully.');
        }
    });

    // Add your device's reboot API for physical restart.
    console.log('Rebooting!');
};

Voorbeelden van SDK-apparaten

De Azure IoT SDK voor Node.js biedt werkende voorbeelden van apparaat-apps die apparaatbeheertaken verwerken. Zie voor meer informatie:

Een back-endtoepassing maken

In deze sectie wordt beschreven hoe u een directe methode op een apparaat aanroept.

Service SDK-pakket installeren

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

npm install azure-iothub --save

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

Gebruik fromConnectionString om verbinding te maken met IoT Hub.

Als u een directe methode wilt aanroepen op een apparaat via IoT Hub, heeft uw service de machtiging voor serviceverbinding nodig. Standaard wordt elke IoT Hub gemaakt met een gedeeld toegangsbeleid met de naam service die deze machtiging verleent.

Als parameter voor CreateFromConnectionStringhet leveren van het beleid voor gedeelde toegang van de service verbindingsreeks. Zie Toegang tot IoT Hub beheren met handtekeningen voor gedeelde toegang voor meer informatie over beleid voor gedeelde toegang.

var Client = require('azure-iothub').Client;
var connectionString = '{IoT hub shared access policy connection string}';
var client = Client.fromConnectionString(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.

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

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

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 methode op een apparaat aanroepen

Gebruik invokeDeviceMethod om een directe methode op naam op een apparaat aan te roepen. De parameter voor de methodenaam identificeert de directe methode.

In dit voorbeeld wordt de methode 'opnieuw opstarten' aangeroepen om een herstart op het apparaat te starten. De methode 'reboot' is toegewezen aan een callback-handlerfunctie op het apparaat, zoals beschreven in de sectie Een directe methode callback van dit artikel maken.

var startRebootDevice = function(deviceToReboot) {

    var methodName = "reboot";

    var methodParams = {
        methodName: methodName,
        payload: null,
        timeoutInSeconds: 30
    };

    client.invokeDeviceMethod(deviceToReboot, methodParams, function(err, result) {
        if (err) {
            console.error("Direct method error: "+err.message);
        } else {
            console.log("Successfully invoked the device to reboot.");  
        }
    });
};

Voorbeelden van SDK-service

De Azure IoT SDK voor Node.js biedt werkende voorbeelden van service-apps die apparaatbeheertaken verwerken. Zie voor meer informatie: