Delen via

Aan de slag met apparaatdubbels

  • Artikel

Gebruik de Azure IoT Hub-apparaat-SDK en service-SDK om toepassingen te ontwikkelen die algemene taken voor apparaatdubbels verwerken. Apparaatdubbels zijn JSON-documenten die apparaatstatusgegevens opslaan, waaronder metagegevens, configuraties en voorwaarden. IoT Hub houdt een apparaatdubbel vast voor elk apparaat dat er verbinding mee maakt.

U kunt apparaatdubbels gebruiken voor het volgende:

  • Metagegevens van apparaten opslaan vanuit de back-end van uw oplossing
  • Huidige statusinformatie rapporteren, zoals beschikbare mogelijkheden en voorwaarden, bijvoorbeeld de gebruikte connectiviteitsmethode vanuit uw apparaat-app
  • De status van langlopende werkstromen, zoals firmware- en configuratie-updates, synchroniseren tussen een apparaat-app en een back-end-app
  • Query's uitvoeren op de metagegevens, configuratie of status van uw apparaat

Zie Apparaatdubbels begrijpen en gebruiken in IoT Hub voor meer informatie over apparaatdubbels, waaronder wanneer u apparaatdubbels gebruikt.

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.

In dit artikel leest u hoe u twee typen toepassingen ontwikkelt:

  • Apparaat-apps kunnen aanvragen verwerken om de gewenste eigenschappen bij te werken en reageren met wijzigingen in gerapporteerde eigenschappen.
  • Service-apps kunnen tags voor apparaatdubbels bijwerken, nieuwe gewenste eigenschappen instellen en apparaten opvragen op basis van waarden voor apparaatdubbels.

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 apparaat- en back-endservice te maken voor apparaatdubbels.

Een apparaattoepassing maken

Apparaattoepassingen kunnen gerapporteerde eigenschappen van dubbels lezen en schrijven en op de hoogte worden gesteld van wijzigingen in gewenste dubbeleigenschappen die zijn ingesteld door een back-endtoepassing of IoT Hub.

In deze sectie wordt beschreven hoe u apparaattoepassingscode gebruikt voor het volgende:

  • Een apparaatdubbel ophalen en gerapporteerde eigenschappen onderzoeken
  • Gerapporteerde eigenschappen van apparaatdubbel bijwerken
  • Een callback-handler voor het bijwerken van de gewenste eigenschap maken

Vereist NuGet-apparaatpakket

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

Voeg deze using instructie toe om de apparaatbibliotheek te gebruiken.

using Microsoft.Azure.Devices.Client;

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 apparaatdubbels vanaf het apparaat.

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

De CreateFromConnectionString transportprotocolparameter TransportType ondersteunt de volgende transportprotocollen:

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

Het Http1 protocol wordt niet ondersteund voor apparaatdubbelupdates.

In dit voorbeeld wordt verbinding gemaakt met een apparaat met behulp van het Mqtt transportprotocol.

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

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 auth DeviceAuthenticationWithX509Certificate object waarnaar wordt doorgegeven DeviceClient.Create.

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

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

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

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

Zie voor meer informatie over certificaatverificatie:

Codevoorbeelden

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

Een apparaatdubbel ophalen en eigenschappen onderzoeken

Roep GetTwinAsync aan om de huidige eigenschappen van de apparaatdubbel op te halen. Er zijn veel eigenschappen van dubbelobjecten die u kunt gebruiken voor toegang tot specifieke gebieden van de Twin JSON-gegevens, waaronder Properties, Status, Tagsen .Version

In dit voorbeeld worden eigenschappen van apparaatdubbels opgehaald en worden de dubbelwaarden in JSON-indeling afgedrukt.

Console.WriteLine("Retrieving twin...");
Twin twin = await _deviceClient.GetTwinAsync();
Console.WriteLine("\tInitial twin value received:");
Console.WriteLine($"\t{twin.ToJson()}");

Gerapporteerde eigenschappen van apparaatdubbel bijwerken

Een gerapporteerde eigenschap van een dubbel bijwerken:

  1. Een TwinCollection-object maken voor de gerapporteerde eigenschapsupdate
  2. Een of meer gerapporteerde eigenschappen in het TwinCollection object bijwerken
  3. UpdateReportedPropertiesAsync gebruiken om gerapporteerde eigenschapswijzigingen naar de IoT Hub-service te pushen

Voorbeeld:

try
{
Console.WriteLine("Sending sample start time as reported property");
TwinCollection reportedProperties = new TwinCollection();
reportedProperties["DateTimeLastAppLaunch"] = DateTime.UtcNow;
await _deviceClient.UpdateReportedPropertiesAsync(reportedProperties);
}
catch (Exception ex)
{
   Console.WriteLine();
   Console.WriteLine("Error in sample: {0}", ex.Message);
}

Een callback-handler voor het bijwerken van de gewenste eigenschap maken

Maak een callback-handler voor het bijwerken van de gewenste eigenschap die wordt uitgevoerd wanneer een gewenste eigenschap wordt gewijzigd in de apparaatdubbel door de naam van de callback-handlermethode door te geven aan SetDesiredPropertyUpdateCallbackAsync.

Met deze aanroep wordt bijvoorbeeld het systeem ingesteld om een methode met de naamOnDesiredPropertyChangedAsync te informeren wanneer een gewenste eigenschap wordt gewijzigd.

await _deviceClient.SetDesiredPropertyUpdateCallbackAsync(OnDesiredPropertyChangedAsync, null);

De eigenschappen van de dubbel worden als een TwinCollection doorgegeven aan de callback-methode en kunnen als structuren worden onderzocht KeyValuePair .

In dit voorbeeld worden de gewenste eigenschapsupdates ontvangen als een TwinCollection, waarna de KeyValuePair verzamelingsupdates worden doorlopen en afgedrukt. Nadat de KeyValuePair verzameling is doorlopen, wordt de code aanroepen UpdateReportedPropertiesAsync om de DateTimeLastDesiredPropertyChangeReceived gerapporteerde eigenschap bij te werken om de laatst bijgewerkte tijd up-to-date te houden.

private async Task OnDesiredPropertyChangedAsync(TwinCollection desiredProperties, object userContext)
{
   var reportedProperties = new TwinCollection();

   Console.WriteLine("\tDesired properties requested:");
   Console.WriteLine($"\t{desiredProperties.ToJson()}");

   // For the purpose of this sample, we'll blindly accept all twin property write requests.
   foreach (KeyValuePair<string, object> desiredProperty in desiredProperties)
   {
         Console.WriteLine($"Setting {desiredProperty.Key} to {desiredProperty.Value}.");
         reportedProperties[desiredProperty.Key] = desiredProperty.Value;
   }

   Console.WriteLine("\tAlso setting current time as reported property");
   reportedProperties["DateTimeLastDesiredPropertyChangeReceived"] = DateTime.UtcNow;

   await _deviceClient.UpdateReportedPropertiesAsync(reportedProperties);
}

Voorbeeld van SDK-apparaat

De Azure IoT SDK voor .NET biedt een werkend voorbeeld van een apparaat-app waarmee taken van apparaatdubbels worden verwerkt. Zie TwinSample voor meer informatie.

Een back-endtoepassing maken

Een back-endtoepassing maakt verbinding met een apparaat via IoT Hub en kan gerapporteerde en gewenste eigenschappen van het apparaat lezen, gewenste eigenschappen schrijven en apparaatquery's uitvoeren.

In deze sectie wordt beschreven hoe u back-endtoepassingscode maakt voor:

  • Apparaatdubbelvelden lezen en bijwerken
  • Een apparaatdubbelquery maken

De Klasse RegistryManager bevat alle methoden die nodig zijn om een back-endtoepassing te maken om te communiceren met apparaatdubbels van de service.

Service NuGet-pakket toevoegen

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

Verbinding maken met IoT Hub

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

  • Beleid voor gedeelde toegang
  • Microsoft Entra

Belangrijk

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

Verbinding maken met behulp van een beleid voor gedeelde toegang

Een back-endtoepassing verbinden met een apparaat met createFromConnectionString. Uw toepassing heeft de serviceverbindingsmachtiging nodig om de gewenste eigenschappen van een apparaatdubbel te wijzigen en er is een leesmachtiging voor het register nodig om een query uit te voeren op het identiteitsregister. Er is geen standaardbeleid voor gedeelde toegang dat alleen deze twee machtigingen bevat, dus u moet er een maken als er nog geen beleid bestaat. Geef dit beleid voor gedeelde toegang op verbindingsreeks als parameter aan fromConnectionString. Zie Toegang tot IoT Hub beheren met handtekeningen voor gedeelde toegang voor meer informatie over beleid voor gedeelde toegang.

using Microsoft.Azure.Devices;
static RegistryManager registryManager;
static string connectionString = "{Shared access policy connection string}";
registryManager = RegistryManager.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.

Apparaatdubbelvelden lezen en bijwerken

U kunt huidige apparaatdubbelvelden ophalen in een Twin-object door GetTwinAsync aan te roepen.

De Twin klasse bevat eigenschappen die overeenkomen met elke sectie van een apparaatdubbel. Gebruik de Twin klasse-eigenschappen om apparaatdubbelvelden weer te geven en bij te werken. U kunt de Twin objecteigenschappen gebruiken om meerdere dubbelvelden bij te werken voordat u de updates naar het apparaat schrijft met behulp van UpdateTwinAsync.

Nadat u dubbele veldupdates hebt uitgevoerd, roept u UpdateTwinAsync aan om objectveldupdates terug te schrijven Twin naar een apparaat. Gebruik try en catch logica in combinatie met een fouthandler om onjuist opgemaakte patchfouten te ondervangen van UpdateTwinAsync.

Apparaatdubbeltags lezen en bijwerken

Gebruik de eigenschap Tags voor apparaatdubbels om taggegevens van het apparaat te lezen en te schrijven.

Tags bijwerken met behulp van een dubbelobject

In dit voorbeeld maakt u een location tagpatch, wijst u deze toe aan het Twin object met behulp van de Tags eigenschap en past u vervolgens de patch toe met behulp van UpdateTwinAsync.

// Retrieve the device twin
var twin = await registryManager.GetTwinAsync("myDeviceId");

// Create the tag patch
var tagspatch =
   @"{
   tags: {
         location: {
            region: 'US',
            plant: 'Redmond43'
         }
   }
}";

// Assign the patch to the Twin object
twin.Tags["location"] = tagspatch;

// Apply the patch to update the device twin tags section
try
{
   await registryManager.UpdateTwinAsync(twin.DeviceId, patch, twin.ETag);
}
catch (Exception e)
{
   console.WriteLine("Twin update failed.", e.Message);
}
Tags bijwerken met behulp van een JSON-tekenreeks

U kunt een patch voor het bijwerken van apparaatdubbels met JSON-indeling maken en toepassen. IoT Hub parseert en past de patch toe als deze correct is opgemaakt.

In dit voorbeeld wordt aangeroepen GetTwinAsync om de huidige velden voor apparaatdubbels op te halen in een Twin object, een patch met JSON-indeling tag met regio- en locatiegegevens te maken en roept u vervolgens UpdateTwinAsync aan om de patch toe te passen om de apparaatdubbel bij te werken. Er wordt een foutbericht weergegeven als UpdateTwinAsync dit is mislukt.

// Retrieve the device twin
var twin = await registryManager.GetTwinAsync("myDeviceId");

// Create the JSON tags patch
var patch =
   @"{
      tags: {
            location: {
               region: 'US',
               plant: 'Redmond43'
            }
      }
   }";
// Apply the patch to update the device twin tags
try
{
   await registryManager.UpdateTwinAsync(twin.DeviceId, patch, twin.ETag);
}
catch (Exception e)
{
   console.WriteLine("Twin update failed.", e.Message);
}

Gewenste eigenschappen van dubbel weergeven en bijwerken

Gebruik de eigenschap TwinProperties.Desired van de apparaatdubbel om de gewenste eigenschapsgegevens van het apparaat te lezen en te schrijven. Desired Dubbeleigenschappen bijwerken met behulp van een patch met JSON-indeling.

In dit voorbeeld wordt aangeroepen GetTwinAsync om de huidige apparaatdubbelvelden op te halen in een Twin object, de gewenste eigenschap van de dubbel bij te werken en vervolgens aanroepen UpdateTwinAsync om het Twin object toe te passen om de apparaatdubbel speed bij te werken.

// Retrieve the device twin
var twin = await registryManager.GetTwinAsync("myDeviceId");

twin.Properties.Desired["speed"] = "type: '5G'";
await registryManager.UpdateTwinAsync(twin.DeviceId, twin, twin.ETag);

Andere updatemethoden voor dubbels

U kunt ook dubbelupdates toepassen met behulp van deze SDK-methoden:

  • Roep ReplaceTwinAsync aan om de hele apparaatdubbel te vervangen.
  • Roep UpdateTwins2Async aan om een lijst met tweelingen bij te werken die eerder in het systeem zijn gemaakt.

Een apparaatdubbelquery maken

In deze sectie ziet u twee query's voor apparaatdubbels. Apparaatdubbelquery's zijn SQL-achtige query's die een resultatenset met apparaatdubbels retourneren.

Als u een query voor een apparaatdubbel wilt maken, roept u CreateQuery aan om een SQL-query met dubbels te verzenden en een IQuery-interface te verkrijgen. U kunt desgewenst een tweede parameter aanroepen CreateQuery om een maximum aantal items per pagina op te geven.

Roep de volgende aanroep GetNextAsTwinAsync of GetNextAsJsonAsync methode zo vaak als nodig is om alle dubbelresultaten op te halen.

De IQuery interface bevat een Booleaanse eigenschap HasMoreResults die u kunt gebruiken om te controleren of er meer dubbelresultaten zijn om op te halen.

Deze voorbeeldquery selecteert alleen de apparaatdubbels van apparaten die zich in de fabriek redmond43 bevinden.

var query = registryManager.CreateQuery(
"SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'", 100);
var twinsInRedmond43 = await query.GetNextAsTwinAsync();
Console.WriteLine("Devices in Redmond43: {0}", 
string.Join(", ", twinsInRedmond43.Select(t => t.DeviceId)));

Deze voorbeeldquery verfijnt de eerste query om alleen de apparaten te selecteren die ook zijn verbonden via een mobiel netwerk.

query = registryManager.CreateQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' AND properties.reported.connectivity.type = 'cellular'", 100);
var twinsInRedmond43UsingCellular = await query.GetNextAsTwinAsync();
Console.WriteLine("Devices in Redmond43 using cellular network: {0}", 
string.Join(", ", twinsInRedmond43UsingCellular.Select(t => t.DeviceId)));

Voorbeeld van SDK-service

De Azure IoT SDK voor .NET biedt een werkend voorbeeld van een service-app waarmee taken van apparaatdubbels worden verwerkt. Zie Het voorbeeld van Registerbeheer 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 apparaat- en back-endservice te maken voor apparaatdubbels.

Een apparaattoepassing maken

Apparaattoepassingen kunnen gerapporteerde eigenschappen van dubbels lezen en schrijven en op de hoogte worden gesteld van wijzigingen in gewenste dubbeleigenschappen die zijn ingesteld door een back-endtoepassing of IoT Hub.

In deze sectie wordt beschreven hoe u apparaattoepassingscode maakt voor:

  • Een apparaatdubbel ophalen en weergeven
  • Gerapporteerde eigenschappen van apparaatdubbel bijwerken
  • Abonneren op gewenste eigenschapswijzigingen

De DeviceClient-klasse bevat alle methoden die u nodig hebt om te communiceren met apparaatdubbels vanaf 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.DeviceTwin.*;

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

Een apparaat verbinden met IoT Hub:

  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 apparaatdubbel ophalen en weergeven

Nadat u de clientverbinding hebt geopend, roept u getTwin aan om de huidige dubbeleigenschappen in een Twin object op te halen.

Voorbeeld:

private static Twin twin;
System.out.println("Getting current twin");
twin = client.getTwin();
System.out.println("Received current twin:");
System.out.println(twin);

Gerapporteerde eigenschappen van apparaatdubbel bijwerken

Nadat u de huidige dubbel hebt opgehaald, kunt u beginnen met het maken van gerapporteerde eigenschapsupdates. U kunt ook gerapporteerde eigenschapsupdates maken zonder de huidige dubbel op te halen zolang u de juiste gerapporteerde versie van de eigenschappen hebt. Als u gerapporteerde eigenschappen verzendt en een fout 'voorwaarde mislukt' ontvangt, is de gerapporteerde versie van de eigenschappen verouderd. In dat geval haalt u de nieuwste versie op door opnieuw aan te roepen getTwin .

Gerapporteerde eigenschappen bijwerken:

  1. Roep getReportedProperties aan om de gerapporteerde eigenschappen van de dubbel op te halen in een TwinCollection-object .

  2. Gebruik put om een gerapporteerde eigenschap in het TwinCollection object bij te werken. Roep put aan voor elke gerapporteerde eigenschapsupdate.

  3. Gebruik updateReportedProperties om de groep gerapporteerde eigenschappen toe te passen die zijn bijgewerkt met behulp van de put methode.

Voorbeeld:

TwinCollection reportedProperties = twin.getReportedProperties();

int newTemperature = new Random().nextInt(80);
reportedProperties.put("HomeTemp(F)", newTemperature);
System.out.println("Updating reported property \"HomeTemp(F)\" to value " + newTemperature);

ReportedPropertiesUpdateResponse response = client.updateReportedProperties(reportedProperties);
System.out.println("Successfully set property \"HomeTemp(F)\" to value " + newTemperature);

Abonneren op gewenste eigenschapswijzigingen

Roep subscribeToDesiredProperties aan om u te abonneren op wijzigingen in de gewenste eigenschap. Deze client ontvangt een callback met een Twin object telkens wanneer een gewenste eigenschap wordt bijgewerkt. Deze callback bevat de volledige gewenste eigenschappenset of alleen de bijgewerkte gewenste eigenschap, afhankelijk van hoe de gewenste eigenschap is gewijzigd.

In dit voorbeeld wordt geabonneerd op wijzigingen in de gewenste eigenschap. Alle gewenste eigenschapswijzigingen worden doorgegeven aan een handler met de naam DesiredPropertiesUpdatedHandler.

client.subscribeToDesiredProperties(new DesiredPropertiesUpdatedHandler(), null);

In dit voorbeeld worden met de DesiredPropertiesUpdatedHandler gewenste eigenschap callback-handler-aanroepen getDesiredProperties opgehaald om de eigenschapswijzigingen op te halen en worden vervolgens de bijgewerkte dubbeleigenschappen afgedrukt.

  private static class DesiredPropertiesUpdatedHandler implements DesiredPropertiesCallback
  {
      @Override
      public void onDesiredPropertiesUpdated(Twin desiredPropertyUpdateTwin, Object context)
      {
          if (twin == null)
          {
              // No need to care about this update because these properties will be present in the twin retrieved by getTwin.
              System.out.println("Received desired properties update before getting current twin. Ignoring this update.");
              return;
          }

          // desiredPropertyUpdateTwin.getDesiredProperties() contains all the newly updated desired properties as well as the new version of the desired properties
          twin.getDesiredProperties().putAll(desiredPropertyUpdateTwin.getDesiredProperties());
          twin.getDesiredProperties().setVersion(desiredPropertyUpdateTwin.getDesiredProperties().getVersion());
          System.out.println("Received desired property update. Current twin:");
          System.out.println(twin);
      }
  }

Voorbeeld van SDK-apparaat

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 apparaatdubbel voor meer informatie.

Een back-endtoepassing maken

In deze sectie wordt beschreven hoe u een back-endtoepassing maakt die:

  • Apparaatdubbeltags bijwerken
  • Query's uitvoeren op apparaten met behulp van filters op de tags en eigenschappen

De ServiceClient Klasse DeviceTwin bevat methoden die services kunnen gebruiken voor toegang tot apparaatdubbels.

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.devicetwin.*;
import com.microsoft.azure.sdk.iot.service.exceptions.IotHubException;

Verbinding maken met de IoT Hub

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

  • Beleid voor gedeelde toegang
  • Microsoft Entra

Belangrijk

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 een DeviceTwin-constructor om de verbinding met IoT Hub te maken. Het DeviceTwin object verwerkt de communicatie met uw IoT-hub.

Uw toepassing heeft de serviceverbindingsmachtiging nodig om de gewenste eigenschappen van een apparaatdubbel te wijzigen en er is een leesmachtiging voor het register nodig om een query uit te voeren op het identiteitsregister. Er is geen standaardbeleid voor gedeelde toegang dat alleen deze twee machtigingen bevat, dus u moet er een maken als er nog geen beleid bestaat. Geef dit beleid voor gedeelde toegang op verbindingsreeks als parameter aan fromConnectionString. Zie Toegang tot IoT Hub beheren met handtekeningen voor gedeelde toegang voor meer informatie over beleid voor gedeelde toegang.

Het object DeviceTwinDevice vertegenwoordigt de apparaatdubbel met de eigenschappen en tags.

Voorbeeld:

public static final String iotHubConnectionString = "{Shared access policy connection string}";
public static final String deviceId = "myDeviceId";
public static final String region = "US";
public static final String plant = "Redmond43";

// Get the DeviceTwin and DeviceTwinDevice objects
DeviceTwin twinClient = new DeviceTwin(iotHubConnectionString);
DeviceTwinDevice device = new DeviceTwinDevice(deviceId);

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.

Apparaatdubbelvelden bijwerken

Apparaatdubbelvelden bijwerken:

  1. GetTwin gebruiken om de huidige apparaatdubbelvelden op te halen

    In dit voorbeeld worden de apparaatdubbelvelden opgehaald en afgedrukt:

    // Get the device twin from IoT Hub
System.out.println("Device twin before update:");
twinClient.getTwin(device);
System.out.println(device);

  2. HashSet Een object gebruiken voor add een groep dubbeltagparen

  3. SetTags gebruiken om een groep tagparen van een tags object toe te voegen aan een DeviceTwinDevice object

  4. UpdateTwin gebruiken om de dubbel bij te werken in de IoT-hub

    In dit voorbeeld worden de tags voor regio- en plantapparaatdubbels voor een apparaatdubbel bijgewerkt:

    // Update device twin tags if they are different
// from the existing values
String currentTags = device.tagsToString();
if ((!currentTags.contains("region=" + region) && !currentTags.contains("plant=" + plant))) {

// Create the tags and attach them to the DeviceTwinDevice object
Set<Pair> tags = new HashSet<Pair>();
tags.add(new Pair("region", region));
tags.add(new Pair("plant", plant));
device.setTags(tags);

// Update the device twin in IoT Hub
System.out.println("Updating device twin");
twinClient.updateTwin(device);
}

// Retrieve and display the device twin with the tag values from IoT Hub
System.out.println("Device twin after update:");
twinClient.getTwin(device);
System.out.println(device);

Een apparaatdubbelquery maken

In deze sectie ziet u twee query's voor apparaatdubbels. Apparaatdubbelquery's zijn SQL-achtige query's die een resultatenset met apparaatdubbels retourneren.

De queryklasse bevat methoden die kunnen worden gebruikt om QUERY's in SQL-stijl te maken voor IoT Hub voor tweelingen, taken, apparaattaken of onbewerkte gegevens.

Een apparaatquery maken:

  1. CreateSqlQuery gebruiken om de SQL-query voor dubbels te bouwen

  2. QueryTwin gebruiken om de query uit te voeren

  3. HasNextDeviceTwin gebruiken om te controleren of er een andere apparaatdubbel in de resultatenset staat

  4. GetNextDeviceTwin gebruiken om de volgende apparaatdubbel op te halen uit de resultatenset

In het volgende voorbeeld worden maximaal 100 apparaten geretourneerd.

Deze voorbeeldquery selecteert alleen de apparaatdubbels van apparaten die zich in de fabriek redmond43 bevinden.

// Query the device twins in IoT Hub
System.out.println("Devices in Redmond:");

// Construct the query
SqlQuery sqlQuery = SqlQuery.createSqlQuery("*", SqlQuery.FromType.DEVICES, "tags.plant='Redmond43'", null);

// Run the query, returning a maximum of 100 devices
Query twinQuery = twinClient.queryTwin(sqlQuery.getQuery(), 100);
while (twinClient.hasNextDeviceTwin(twinQuery)) {
  DeviceTwinDevice d = twinClient.getNextDeviceTwin(twinQuery);
  System.out.println(d.getDeviceId());
}

Deze voorbeeldquery verfijnt de eerste query om alleen de apparaten te selecteren die ook zijn verbonden via een mobiel netwerk.

System.out.println("Devices in Redmond using a cellular network:");

// Construct the query
sqlQuery = SqlQuery.createSqlQuery("*", SqlQuery.FromType.DEVICES, "tags.plant='Redmond43' AND properties.reported.connectivityType = 'cellular'", null);

// Run the query, returning a maximum of 100 devices
twinQuery = twinClient.queryTwin(sqlQuery.getQuery(), 3);
while (twinClient.hasNextDeviceTwin(twinQuery)) {
  DeviceTwinDevice d = twinClient.getNextDeviceTwin(twinQuery);
  System.out.println(d.getDeviceId());
}

Voorbeeld van SDK-service

De Azure IoT SDK voor Java biedt een werkend voorbeeld van een service-app waarmee apparaatdubbeltaken worden verwerkt. Zie Voorbeeld van apparaatdubbel 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 apparaatdubbels.

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

Apparaattoepassingen kunnen gerapporteerde eigenschappen van dubbels lezen en schrijven en op de hoogte worden gesteld van wijzigingen in gewenste dubbeleigenschappen die zijn ingesteld door een back-endtoepassing of IoT Hub.

De IoTHubDeviceClient-klasse bevat methoden die kunnen worden gebruikt voor het werken met apparaatdubbels.

In deze sectie wordt beschreven hoe u apparaattoepassingscode maakt die:

  • Hiermee haalt u een apparaatdubbel op en bekijkt u gerapporteerde eigenschappen
  • Gerapporteerde eigenschappen van apparaatdubbels

Instructie voor apparaatimport

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

from azure.iot.device import IoTHubDeviceClient

Een apparaat verbinden met IoT Hub

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

  • Gedeelde toegangssleutel
  • X.509-certificaat

Belangrijk

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

Een apparaat verbinden met IoT Hub:

  1. Roep create_from_connection_string aan om het 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. 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 apparaatdubbel ophalen en gerapporteerde eigenschappen onderzoeken

U kunt apparaatdubbelgegevens ophalen en onderzoeken, inclusief tags en eigenschappen. De opgehaalde informatie van de apparaatdubbel komt overeen met JSON-geformatteerde gegevens van apparaatdubbels die u voor een apparaat in Azure Portal kunt bekijken.

Roep get_twin aan om de apparaatdubbel op te halen uit de Azure IoT Hub-service. De dubbele informatie wordt in een variabele geplaatst die kan worden afgedrukt of onderzocht.

In dit voorbeeld wordt de apparaatdubbel opgehaald en wordt de print opdracht gebruikt om de apparaatdubbel in JSON-indeling weer te geven.

# get the twin
twin = await device_client.get_twin()
print("Twin document:")
print("{}".format(twin))

Gerapporteerde eigenschappen van apparaatdubbels

U kunt een patch toepassen om gerapporteerde eigenschappen van het apparaat bij te werken in JSON-indeling.

Een patch toepassen om gerapporteerde eigenschappen bij te werken:

  1. Wijs een gerapporteerde JSON-patch voor eigenschappen toe aan een variabele.
  2. Roep patch_twin_reported_properties aan om de JSON-patch toe te passen op gerapporteerde eigenschappen. Dit is een synchrone aanroep, wat betekent dat deze functie pas wordt geretourneerd als de patch naar de service wordt verzonden en bevestigd.

Als patch_twin_reported_properties er een fout wordt geretourneerd, wordt met deze functie de bijbehorende fout gegenereerd.

# create the reported properties patch
reported_properties = {"temperature": random.randint(320, 800) / 10}
print("Setting reported temperature to {}".format(reported_properties["temperature"]))
# update the reported properties and wait for the result
await device_client.patch_twin_reported_properties(reported_properties)

U kunt deze methoden ook aanroepen om apparaatdubbels bij te werken:

  • Roep replace_twin aan om apparaatdubbeltags en gewenste eigenschappen te vervangen.
  • Roep update_twin aan om apparaatdubbeltags en gewenste eigenschappen bij te werken.

Patchhandler voor binnenkomende gewenste eigenschappen

Roep on_twin_desired_properties_patch_received aan om een handler-functie of coroutine te maken die wordt aangeroepen wanneer een patch met gewenste eigenschappen van een dubbel wordt ontvangen. De handler heeft één argument, de dubbelpatch in de vorm van een JSON-woordenlijstobject.

In dit voorbeeld wordt een patchhandler met gewenste eigenschappen ingesteld met de naam twin_patch_handler.

Voorbeeld:

try:
    # Set handlers on the client
    device_client.on_twin_desired_properties_patch_received = twin_patch_handler
except:
    # Clean up in the event of failure
    client.shutdown()

De twin_patch_handler gewenste eigenschappenupdates van JSON worden ontvangen en afgedrukt.

    # Define behavior for receiving twin desired property patches
    def twin_patch_handler(twin_patch):
        print("Twin patch received:")
        print(twin_patch)

Voorbeelden van SDK-apparaten

De Azure IoT SDK voor Python bevat de volgende voorbeelden:

  • get_twin : maak verbinding met een apparaat en haal dubbele gegevens op.
  • update_twin_reported_properties - Gerapporteerde eigenschappen van dubbel bijwerken.
  • receive_twin_desired_properties : gewenste eigenschappen ontvangen en bijwerken.

Een back-endtoepassing maken

Een back-endtoepassing maakt verbinding met een apparaat via IoT Hub en kan gerapporteerde en gewenste eigenschappen van het apparaat lezen, gewenste eigenschappen schrijven en apparaatquery's uitvoeren.

In deze sectie wordt beschreven hoe u een back-endtoepassing maakt voor:

  • Dubbeltags en gewenste eigenschappen bijwerken
  • Query's uitvoeren op apparaten met behulp van filters op de tags en eigenschappen

De IoTHubRegistryManager-klasse bevat alle methoden die nodig zijn om een back-endtoepassing te maken om te communiceren met apparaatdubbels van de service.

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. Uw toepassing heeft de serviceverbindingsmachtiging nodig om de gewenste eigenschappen van een apparaatdubbel te wijzigen en er is een leesmachtiging voor het register nodig om een query uit te voeren op het identiteitsregister. Er is geen standaardbeleid voor gedeelde toegang dat alleen deze twee machtigingen bevat, dus u moet er een maken als er nog geen beleid bestaat. Geef dit beleid voor gedeelde toegang op verbindingsreeks als parameter aan fromConnectionString. Zie Toegang tot IoT Hub beheren met handtekeningen voor gedeelde toegang voor meer informatie over beleid voor gedeelde toegang.

Voorbeeld:

import sys
from time import sleep
from azure.iot.hub import IoTHubRegistryManager
from azure.iot.hub.models import Twin, TwinProperties, QuerySpecification, QueryResult

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

Dubbeltags en gewenste eigenschappen bijwerken

U kunt zowel tags voor apparaatdubbels als gewenste eigenschappen van een back-endtoepassing tegelijkertijd bijwerken met behulp van update_twin.

  1. Roep get_twin aan om de huidige versie van de apparaatdubbel op te halen
  2. Gebruik de klasse Twin om tags en eigenschappen toe te voegen in JSON-indeling.
  3. Aanroep update_twin om de patch toe te passen op de apparaatdubbel. U kunt ook replace_twin gebruiken om de gewenste eigenschappen en tags voor een apparaatdubbel te vervangen.

In dit voorbeeld worden gegevens region bijgewerkt en plant gelabeld en wordt een power_level gewenste eigenschap ingesteld op 1.

new_tags = {
        'location' : {
            'region' : 'US',
            'plant' : 'Redmond43'
        }
    }

DEVICE_ID = "[Device Id]"
twin = iothub_registry_manager.get_twin(DEVICE_ID)
twin_patch = Twin(tags=new_tags, properties= TwinProperties(desired={'power_level' : 1}))
twin = iothub_registry_manager.update_twin(DEVICE_ID, twin_patch, twin.etag)

Een apparaatdubbelquery maken

U kunt gegevens van apparaatdubbels opvragen met behulp van apparaatdubbelquery's. Apparaatdubbelquery's zijn SQL-achtige query's die een resultatenset met apparaatdubbels retourneren.

Een apparaatdubbelquery gebruiken:

  1. Gebruik een QuerySpecification-object om een SQL-achtige queryaanvraag te definiëren.

  2. Gebruik query_iot_hub om query's uit te voeren op een IoTHub en apparaatdubbelgegevens op te halen met behulp van de SQL-achtige queryspecificatie.

In dit voorbeeld worden twee query's uitgevoerd. De eerste selecteert alleen de apparaatdubbels van apparaten in de Redmond43 fabriek en de tweede verfijnt de query om alleen de apparaten te selecteren die ook zijn verbonden via een mobiel netwerk. Resultaten worden na elke query afgedrukt.

query_spec = QuerySpecification(query="SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'")
query_result = iothub_registry_manager.query_iot_hub(query_spec, None, 100)
print("Devices in Redmond43 plant: {}".format(', '.join([twin.device_id for twin in query_result.items])))

print()

query_spec = QuerySpecification(query="SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' AND properties.reported.connectivity = 'cellular'")
query_result = iothub_registry_manager.query_iot_hub(query_spec, None, 100)
print("Devices in Redmond43 plant using cellular network: {}".format(', '.join([twin.device_id for twin in query_result.items])))

print()

Voorbeeld van SDK-service

De Azure IoT SDK voor Python biedt een werkend voorbeeld van een service-app waarmee apparaatdubbeltaken worden verwerkt. Zie Het voorbeeld van registerbeheerquery's 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 toepassingscode voor apparaat- en back-endservice te maken voor apparaatdubbels.

Een apparaattoepassing maken

Apparaattoepassingen kunnen gerapporteerde eigenschappen van dubbels lezen en schrijven en op de hoogte worden gesteld van wijzigingen in gewenste dubbeleigenschappen die zijn ingesteld door een back-endtoepassing of IoT Hub.

In deze sectie wordt beschreven hoe u het pakket azure-iot-device gebruikt in de Azure IoT SDK voor Node.js om een apparaattoepassing te maken voor:

  • Een apparaatdubbel ophalen en gerapporteerde eigenschappen onderzoeken
  • Gerapporteerde eigenschappen van apparaatdubbel bijwerken
  • Melding ontvangen van wijzigingen in de gewenste eigenschap

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.

Device SDK-pakket installeren

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

Het pakket azure-iot-device bevat objecten die interface hebben met IoT-apparaten. De klasse Twin bevat dubbelspecifieke objecten. In deze sectie wordt klassecode beschreven Client die wordt gebruikt voor het lezen en schrijven van apparaatdubbelgegevens.

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 Mqtt protocol geïnstalleerd:

npm install azure-iot-device-mqtt --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 clientmodule maken

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

Voorbeeld:

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

Een protocolmodule maken

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

In dit voorbeeld wordt het MQTT-protocol toegewezen:

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

Het apparaat verbindingsreeks en transportprotocol toevoegen

Aanroepen vanuitConnectionString om verbindingsparameters voor apparaten op te geven:

  • connStr: een verbindingsreeks die machtigingen voor apparaatverbinding inkapselt voor een IoT-hub. De verbindingsreeks bevat hostnaam, apparaat-id en gedeelde toegangssleutel in deze indeling: "HostName=<iothub_host_name>; DeviceId=<device_id>; SharedAccessKey=<device_key>".
  • transportCtor - Het transportprotocol.

In dit voorbeeld wordt het Mqtt transportprotocol gebruikt:

const deviceConnectionString = "{IoT hub device connection string}"
const Protocol = require('azure-iot-device-mqtt').Mqtt;
let client = Client.fromConnectionString(deviceConnectionString, Protocol);

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 uit te voeren.

Voorbeeld:

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

Een apparaatdubbel ophalen en gerapporteerde eigenschappen onderzoeken

Roep getTwin aan om de huidige apparaatdubbelgegevens op te halen in een Twin-object .

Voorbeeld:

client.getTwin(function(err, twin))
if (err)
    console.error('could not get twin');

Gerapporteerde eigenschappen van apparaatdubbel bijwerken

Gebruik update om gerapporteerde eigenschappen van het apparaat bij te werken. Neem een patch met JSON-indeling op als de eerste parameter en de callback-methode voor de uitvoeringsstatus van de functie als de tweede parameter voor de methode.

In dit voorbeeld wordt een patch voor een apparaatdubbel met JSON-indeling opgeslagen in de patch variabele. De patch bevat een updatewaarde voor apparaatdubbels connectivity van cellular. De patch- en fouthandler worden doorgegeven aan de update methode. Als er een fout optreedt, wordt er een consolefoutbericht weergegeven.

var patch = {
    connectivity: {
        type: 'cellular'
    }
}
twin.properties.reported.update(patch, function(err)
  {
    if (err)
      {
        console.error('could not update twin');
      } 
    else
      {
        console.log('twin state reported');
        process.exit();
      }
  });

Melding ontvangen van wijzigingen in de gewenste eigenschap

Maak een gebeurtenislistener voor het bijwerken van gewenste eigenschappen die wordt uitgevoerd wanneer een gewenste eigenschap op het apparaat wordt gewijzigd door de naam van de callback-handlermethode door te geven aan twin.on.

De gewenste eigenschaps-gebeurtenislistener kan een van de volgende vormen aannemen:

  • Alle patches ontvangen met één gebeurtenis-handler
  • Een gebeurtenis ontvangen als er iets verandert onder een groep eigenschappen
  • Een gebeurtenis ontvangen voor een wijziging van één eigenschap

Alle patches ontvangen met één gebeurtenis-handler

U kunt een listener maken om elke gewenste eigenschapswijziging te ontvangen.

Met deze voorbeeldcode worden alle eigenschappen uitgevoerd die van de service worden ontvangen.

twin.on('properties.desired', function (delta) {
    console.log('new desired properties received:');
    console.log(JSON.stringify(delta));
});

Een gebeurtenis ontvangen als er iets verandert onder een groep eigenschappen

U kunt een listener maken om een gebeurtenis te ontvangen als er iets onder een eigenschapsgroep verandert.

Voorbeeld:

  1. De minTemperature eigenschappen maxTemperature bevinden zich onder een eigenschapsgroep met de naam properties.desired.climate changes.

  2. Een back-endservicetoepassing past deze patch toe op het bijwerken minTemperature en maxTemperature de gewenste eigenschappen:

    const twinPatch1 = {
properties: {
   desired: {
    climate: { minTemperature: 68, maxTemperature: 76, },
    },
  },
 };

  3. Met deze code stelt u een gewenste eigenschapswijzigingslistener in die wordt geactiveerd voor wijzigingen binnen de properties.desired.climate eigenschappengroepering. Als er een gewenste eigenschapswijziging binnen deze groep is, worden berichten over minimale en maximale temperatuurwijziging weergegeven in de console:

    twin.on('properties.desired.climate', function (delta) {
    if (delta.minTemperature || delta.maxTemperature) {
        console.log('updating desired temp:');
        console.log('min temp = ' + twin.properties.desired.climate.minTemperature);
        console.log('max temp = ' + twin.properties.desired.climate.maxTemperature);
    }
});

Een gebeurtenis ontvangen voor een wijziging van één eigenschap

U kunt een listener instellen voor een wijziging van één eigenschap. In dit voorbeeld wordt de code voor deze gebeurtenis alleen uitgevoerd als de fanOn booleaanse waarde deel uitmaakt van de patch. De code voert de nieuwe gewenste fanOn status uit wanneer de service deze bijwerken.

  1. Een back-endtoepassing past deze gewenste eigenschapspatch toe:

     const twinPatch2 = {
  properties: {
    desired: {
      climate: {
        hvac: {
          systemControl: { fanOn: true, },
        },
      },
    },
  },
};

  2. De listener wordt alleen geactiveerd wanneer de fanOn eigenschap wordt gewijzigd:

     twin.on('properties.desired.climate.hvac.systemControl', function (fanOn) {
     console.log('setting fan state to ' + fanOn);
  });

Voorbeelden van Device SDK

De Azure IoT SDK voor Node.js bevat twee voorbeelden van apparaatdubbels:

Een back-endtoepassing maken

Een back-endtoepassing maakt verbinding met een apparaat via IoT Hub en kan gerapporteerde en gewenste eigenschappen van het apparaat lezen, gewenste eigenschappen schrijven en apparaatquery's uitvoeren.

In deze sectie wordt beschreven hoe u een back-endtoepassing maakt die:

  • Een apparaatdubbel ophalen en bijwerken
  • Hiermee maakt u een apparaatdubbelquery

Service SDK-pakket installeren

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

npm install azure-iothub --save

De registerklasse bevat alle methoden die nodig zijn om te communiceren met apparaatdubbels vanuit een back-endtoepassing.

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. Uw toepassing heeft de serviceverbindingsmachtiging nodig om de gewenste eigenschappen van een apparaatdubbel te wijzigen en er is een leesmachtiging voor het register nodig om een query uit te voeren op het identiteitsregister. Er is geen standaardbeleid voor gedeelde toegang dat alleen deze twee machtigingen bevat, dus u moet er een maken als er nog geen beleid bestaat. Geef dit beleid voor gedeelde toegang op verbindingsreeks als parameter aan fromConnectionString. Zie Toegang tot IoT Hub beheren met handtekeningen voor gedeelde toegang voor meer informatie over beleid voor gedeelde toegang.

'use strict';
var iothub = require('azure-iothub');
var connectionString = '{Shared access policy connection string}';
var registry = iothub.Registry.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 apparaatdubbel ophalen en bijwerken

U kunt een patch maken die tag- en gewenste eigenschapsupdates voor een apparaatdubbel bevat.

Een apparaatdubbel bijwerken:

  1. Roep getTwin aan om het apparaatdubbelobject op te halen.
  • Maak een patch op die de update van de apparaatdubbel bevat. De patch is ingedeeld in JSON, zoals beschreven in de klasse Twin. Een back-endservicepatch kan tag- en gewenste eigenschapsupdates bevatten. Zie Tags en eigenschappenindeling voor meer informatie over patchindeling.
  1. Roep update aan om de apparaatdubbel bij te werken met de patch.

In dit voorbeeld wordt de apparaatdubbel opgehaald voor myDeviceIden wordt er een patch toegepast op de tweelingen die location tag-update van region: 'US', plant: 'Redmond43'bevat.

     registry.getTwin('myDeviceId', function(err, twin){
         if (err) {
             console.error(err.constructor.name + ': ' + err.message);
         } else {
             var patch = {
                 tags: {
                     location: {
                         region: 'US',
                         plant: 'Redmond43'
                   }
                 }
             };

             twin.update(patch, function(err) {
               if (err) {
                 console.error('Could not update twin: ' + err.constructor.name + ': ' + err.message);
               } else {
                 console.log(twin.deviceId + ' twin updated successfully');
                 queryTwins();
               }
             });
         }
     });

Een apparaatdubbelquery maken

U kunt SQL-achtige apparaatquery's maken om informatie van apparaatdubbels te verzamelen.

Gebruik createQuery om een query te maken die kan worden uitgevoerd op een IoT Hub-exemplaar om informatie over apparaten of taken te vinden.

createQuery bevat twee parameters:

  • sqlQuery : de query die is geschreven als een SQL-tekenreeks.
  • pageSize - Het gewenste aantal resultaten per pagina (optioneel. standaard: 1000, max: 10000).

Als de parameter pageSize is opgegeven, bevat het queryobject een hasMoreResults booleaanse eigenschap die u kunt controleren en gebruiken nextAsTwin om de volgende dubbelresultatenpagina zo vaak als nodig op te halen om alle resultaten op te halen. Een methode die wordt aangeroepen next , is beschikbaar voor resultaten die geen apparaatdubbels zijn, bijvoorbeeld de resultaten van aggregatiequery's.

Deze voorbeeldquery selecteert alleen de apparaatdubbels van apparaten die zich in de Redmond43 fabriek bevinden.

var queryTwins = function() {
var query = registry.createQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'", 100);
query.nextAsTwin(function(err, results) {
    if (err) {
        console.error('Failed to fetch the results: ' + err.message);
    } else {
        console.log("Devices in Redmond43: " + results.map(function(twin) {return twin.deviceId}).join(','));
    }
});

Deze voorbeeldquery verfijnt de eerste query om alleen de apparaten te selecteren die ook zijn verbonden via een mobiel netwerk.

query = registry.createQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' AND properties.reported.connectivity.type = 'cellular'", 100);
query.nextAsTwin(function(err, results) {
    if (err) {
        console.error('Failed to fetch the results: ' + err.message);
    } else {
        console.log("Devices in Redmond43 using cellular network: " + results.map(function(twin) {return twin.deviceId}).join(','));
    }
});
};

Voorbeeld van service-SDK

De Azure IoT SDK voor Node.js biedt een werkend voorbeeld van een service-app waarmee taken van apparaatdubbels worden verwerkt. Zie Device Twin Backend Service voor meer informatie: dit project wordt gebruikt voor het verzenden van patchupdates voor apparaatdubbels voor een specifiek apparaat.