Kom igång med enhetsdubletter

• Requires Visual Studio

Overview

Den här artikeln beskriver hur man använder Azure IoT SDK för .NET för att skapa programkod för enheter och backend-tjänster för enhetstvillingar.

Create a device application

Enhetsapplikationer kan läsa och skriva tvillingrapporterade egenskaper och bli informerade om önskade ändringar i tvillingegenskaper som har ställts in av en backend-applikation eller IoT Hub.

Det här avsnittet beskriver hur du använder enhetsapplikationskoden för att:

• Retrieve a device twin and examine reported properties
• Update reported device twin properties
• Skapa en hanterare för återkoppling vid uppdatering av önskad egenskap

Krävd enhet NuGet package

Klientapplikationer för enheter skrivna i C# kräver paketet Microsoft.Azure.Devices.Client NuGet.

Add this using statement to use the device library.

using Microsoft.Azure.Devices.Client;

Connect a device to IoT Hub

En enhetsapp kan autentisera sig med IoT Hub med följande metoder:

• Delad åtkomstnyckel
• X.509 certifikat

Autentisera med en delad åtkomstnyckel

DeviceClient-klassen tillhandahåller alla metoder som behövs för att interagera med enhetstvillingar från enheten.

Anslut till enheten med metoden CreateFromConnectionString tillsammans med enhetens anslutningssträng och anslutningstransportprotokoll.

Parametern för CreateFromConnectionStringTransportType transportprotokoll stöder följande transportprotokoll:

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

Http1-protokollet stöds inte för uppdateringar av enhetstvillingar.

Exemplet ansluter till en enhet genom att använda Mqtt-transportprotokollet.

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

Autentisera med hjälp av ett X.509-certifikat

För att ansluta en enhet till IoT Hub med ett X.509-certifikat:

1. Använd DeviceAuthenticationWithX509Certificate för att skapa ett objekt som innehåller information om enhet och certifikat. DeviceAuthenticationWithX509Certificate skickas som den andra parametern till DeviceClient.Create (steg 2).

2. Använd DeviceClient.Create för att ansluta enheten till IoT Hub med hjälp av ett X.509-certifikat.

I det här exemplet fylls enhets- och certifikatinformation i objektet authDeviceAuthenticationWithX509Certificate som skickas till DeviceClient.Create.

Detta exempel visar certifikatets inmatningsparametervärden som lokala variabler för tydlighetens skull. I ett produktionssystem bör känsliga inmatningsparametrar lagras i miljövariabler eller på en annan mer säker lagringsplats. Använd till exempel Environment.GetEnvironmentVariable("HOSTNAME") för att läsa miljövariabeln för värdnamn.

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

För mer information om certifikatautentisering, se:

• Autentisera identiteter med X.509-certifikat
• Handledning: Skapa och ladda upp certifikat för testning

Kodexempel

För exempel på fungerande enhetsautentisering med X.509-certifikat, se:

• Anslut med X.509-certifikat
• DeviceClientX509AuthenticationE2ETests
• Guidad projekt - Provisionera IoT-enheter säkert och i stor skala med IoT Hub Device Provisioning Service

Hämta en enhetstvilling och granska egenskaperna

Anropa GetTwinAsync för att hämta de aktuella egenskaperna för enhetstvillingen. Det finns många Twin objekt egenskaper som du kan använda för att komma åt specifika områden av Twin JSON-data inklusive Properties, Status, Tags, och Version.

Det här exemplet hämtar enhetstvillingens egenskaper och skriver ut tvillingvärdena i JSON-format.

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

Uppdatera rapporterade enhetstvillingegenskaper

För att uppdatera en rapporterad egenskap hos en tvilling:

1. Skapa ett TwinCollection-objekt för rapporterad egenskapsuppdatering
2. Uppdatera en eller flera rapporterade egenskaper inom TwinCollection-objektet
3. Använd UpdateReportedPropertiesAsync för att överföra ändringar av rapporterade egenskaper till IoT-hubbtjänsten.

For example:

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

Skapa en återuppringningshanterare för uppdatering av önskade egenskaper

Skapa en önskad egenskapsuppdaterings-callback-handler som exekveras när en önskad egenskap ändras i enhetstvillingen genom att överföra callback-handler-metodens namn till SetDesiredPropertyUpdateCallbackAsync.

Till exempel konfigurerar det här anropet systemet att meddela en metod som heterOnDesiredPropertyChangedAsync när en önskad egenskap ändras.

await _deviceClient.SetDesiredPropertyUpdateCallbackAsync(OnDesiredPropertyChangedAsync, null);

De dubbla egenskaperna skickas till återanropsmetoden som en TwinCollection och kan undersökas som KeyValuePair strukturer.

Detta exempel tar emot de önskade uppdateringarna av egenskaper som en TwinCollection, och går sedan igenom och skriver ut uppdateringarna av KeyValuePair-kollektionen. Efter att ha loopat genom KeyValuePair-samlingen, anropar koden UpdateReportedPropertiesAsync för att uppdatera DateTimeLastDesiredPropertyChangeReceived-egenskapen och hålla senaste uppdateringstid aktuell.

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

SDK exempelethet

The Azure IoT SDK for .NET provides a working sample of a device app that handles device twin tasks. För mer information, se TwinSample.

Skapa en bakgrundsapplikation

A backend application connects to a device through IoT Hub and can read device reported and desired properties, write device desired properties, and run device queries.

This section describes how to create backend application code to:

• Läs och uppdatera enhetsdubbleringsfält
• Skapa en enhetstvillingfråga

RegistryManager-klassen exponerar alla metoder som krävs för att skapa en backend-applikation för att interagera med enhetstvillingar från tjänsten.

Lägg till tjänst NuGet Package

Backend service applications require the Microsoft.Azure.Devices NuGet package.

Connect to IoT hub

Du kan ansluta en backend-tjänst till IoT Hub med hjälp av följande metoder:

• Policy för delad åtkomst
• Microsoft Entra

Anslut med hjälp av en delad åtkomstpolicy

Anslut en backend-applikation till en enhet med hjälp av CreateFromConnectionString. Din applikation behöver service connect-behörighet för att ändra önskade egenskaper hos en enhetstwin, och den behöver registry read-behörighet för att fråga identitetsregistret. Det finns ingen standardpolicy för delad åtkomst som endast innehåller dessa två tillstånd, så du behöver skapa en om en sådan inte redan finns. Supply this shared access policy connection string as a parameter to fromConnectionString. För mer information om policyer för delad åtkomst, se Kontrollera åtkomst till IoT Hub med delade åtkomstsignaturer.

using Microsoft.Azure.Devices;
static RegistryManager registryManager;
static string connectionString = "{Shared access policy connection string}";
registryManager = RegistryManager.CreateFromConnectionString(connectionString);

Connect using Microsoft Entra

A backend app that uses Microsoft Entra must successfully authenticate and obtain a security token credential before connecting to IoT Hub. Denna token skickas till en IoT Hub-anslutningsmetod. För allmän information om hur du konfigurerar och använder Microsoft Entra för IoT Hub, se Styr åtkomst till IoT Hub med Microsoft Entra ID.

Konfigurera Microsoft Entra-app

You must set up a Microsoft Entra app that is configured for your preferred authentication credential. The app contains parameters such as client secret that are used by the backend application to authenticate. The available app authentication configurations are:

• Klienthemlighet
• Certifikat
• Federerad identitetsuppgift

Microsoft Entra apps may require specific role permissions depending on operations being performed. Till exempel krävs IoT Hub Twin Contributor för att möjliggöra läs- och skrivåtkomst till en IoT Hub-enhet och modultvillingar. För mer information, se Hantera åtkomst till IoT Hub genom att använda Azure RBAC-rolltilldelning.

För mer information om hur du konfigurerar en Microsoft Entra-app, se Snabbstart: Registrera en applikation med Microsoft identitetsplattform.

Autentisera med DefaultAzureCredential

The easiest way to use Microsoft Entra to authenticate a backend application is to use DefaultAzureCredential, but it's recommended to use a different method in a production environment including a specific TokenCredential or pared-down ChainedTokenCredential. For simplicity, this section describes authentication using DefaultAzureCredential and Client secret. För mer information om för- och nackdelarna med att använda DefaultAzureCredential, se Användningsvägledning för DefaultAzureCredential.

DefaultAzureCredential stöder olika autentiseringsmekanismer och bestämmer den lämpliga typen av referenser baserat på den miljö den körs i. Den försöker använda flera olika typer av autentiseringsuppgifter i en ordning tills den hittar en fungerande autentisering.

Microsoft Entra requires these NuGet packages and corresponding using statements:

• Azure.Core
• Azure.Identity

using Azure.Core;
using Azure.Identity;

I det här exemplet läggs Microsoft Entra appregistreringsklientens lösenord, klient-ID och hyresgäst-ID till miljövariabler. Dessa miljövariabler används av DefaultAzureCredential för att autentisera applikationen. Resultatet av en lyckad Microsoft Entra-autentisering är en säkerhetstokenuppgift som vidarebefordras till en IoT Hub-anslutningsmetod.

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

Den resulterande TokenCredential kan sedan skickas till en metod för att ansluta till IoT Hub för alla SDK-klienter som accepterar Microsoft Entra-dataautentisering.

• JobClient
• RegistryManager
• DigitalTwinClient
• ServiceClient

I det här exemplet skickas TokenCredential till ServiceClient.Create för att skapa ett ServiceClient-anslutningsobjekt.

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

I det här exemplet skickas TokenCredential till RegistryManager.Create för att skapa ett RegistryManager-objekt.

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

Code sample

För ett arbetsprov av Microsoft Entra-tjänstens autentisering, se Exempel på rollbaserad autentisering.

Läs och uppdatera enhetens dubbelgångar-fält

Du kan hämta aktuella fält för enhetstvillingar till ett Twin-objekt genom att anropa GetTwinAsync.

Klassen Twin inkluderar egenskaper som motsvarar varje sektion av en enhetstvilling. Använd egenskaperna för Twin-klassen för att visa och uppdatera fälten för enhetstvilling. Du kan använda Twin-objektets egenskaper för att uppdatera flera tvillingfält innan du skriver uppdateringarna till enheten med hjälp av UpdateTwinAsync.

Efter att ha gjort uppdateringar av tvåfältet, anropa UpdateTwinAsync för att skriva Twin objektfältuppdateringar tillbaka till en enhet. Använd try och catch logik kombinerat med en felhanterare för att fånga felaktigt formaterade patchfel från UpdateTwinAsync.

Läs och uppdatera enhetsdubbelmärken

Använd Tags-egenskapen för enhetstvilling för att läsa och skriva information om enhetstaggar.

Uppdatera taggar med ett tvillingobjekt

Detta exempel skapar en location tagg patch, tilldelar den till Twin objektet med hjälp av egenskapen Tags, och applicerar sedan patchen med 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);
}

Update tags using a JSON string

Du kan skapa och tillämpa en JSON-formaterad uppdateringspatch för enheter med tvillinginformation. IoT Hub analyserar och tillämpar patchen om den är korrekt formaterad.

Det här exemplet anropar GetTwinAsync för att hämta aktuella fält i enhetsdubbel till ett Twin objekt, skapar en JSON-formaterad tag patch med information om region och fabriksläge, och anropar sedan UpdateTwinAsync för att tillämpa patchen för att uppdatera enhetsdubbeln. Ett felmeddelande visas om UpdateTwinAsync misslyckades.

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

Visa och uppdatera tvillingens önskade egenskaper

Use the device twin TwinProperties.Desired property to read and write device desired property information. Uppdatera tvillingens Desired egenskaper med hjälp av en JSON-formaterad patch.

This example calls GetTwinAsync to retrieve the current device twin fields into a Twin object, updates the twin speed desired property, and then calls UpdateTwinAsync to apply the Twin object to update the device twin.

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

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

Andra metoder för dubbel uppdatering

Du kan också tillämpa tvillinguppdateringar med hjälp av dessa SDK-metoder:

• Call ReplaceTwinAsync to replace the entire device twin.
• Anropa UpdateTwins2Async för att uppdatera en lista med tvillingar som tidigare skapats inom systemet.

Skapa en enhetsdubbelfråga

Den här avsnittet demonstrerar två förfrågningar om enhetsdubbel. Enhetsdubbel-frågor är SQL-liknande frågor som returnerar en resultatuppsättning av enhetsdubblers.

To create a device twin query, call CreateQuery to submit a twins SQL query and obtain an IQuery Interface. You can optionally call CreateQuery with a second parameter to specify a maximum number of items per page.

Next call GetNextAsTwinAsync or GetNextAsJsonAsync method as many times as needed to retrieve all twin results.

• GetNextAsTwinAsync för att hämta nästa paginerade resultat som Twin-objekt.
• GetNextAsJsonAsync för att hämta nästa paginerade resultat som JSON-strängar.

The IQuery interface includes a HasMoreResults boolean property that you can use to check if there are more twin results to fetch.

Den här exempelfrågan väljer endast enheternas tvillingar för enheter som finns i Redmond43-anläggningen.

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

Denna exempel fråga förfinar den första frågan för att välja endast de enheter som också är anslutna via ett mobilnätverk.

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

SDK-tjänstexempel

Azure IoT SDK för .NET tillhandahåller ett fungerande exempel på en tjänsteapp som hanterar uppgifter för enhetstvillingar. For more information, see Registry Manager Sample.

• Requires Java SE Development Kit 8. Se till att du väljer Java 8 under Långtidsstöd för att navigera till nedladdningar för JDK 8.

Overview

Den här artikeln beskriver hur man använder Azure IoT SDK för Java för att skapa kod för enhets- och backendapplikationer för enhetstvillingar.

Skapa en enhetsapplikation

Enhetsapplikationer kan läsa och skriva rapporterade egenskaper för tvillingar, och bli informerade om önskade förändringar av tvillingegenskaper som ställs in av en back-end applikation eller IoT Hub.

Denna avsnitt beskriver hur man skapar enhetsapplikationskod för att:

• Retrieve and view a device twin
• Uppdatera rapporterade egenskaper för enhetstvillingar
• Prenumerera på önskade ändringar av egenskaper

Klassen DeviceClient tillhandahåller alla metoder du behöver för att interagera med device twins från enheten.

Enhetens importuttryck

Använd följande enhetsimportsatser för att få åtkomst till Azure IoT SDK för Java.

import com.microsoft.azure.sdk.iot.device.*;
import com.microsoft.azure.sdk.iot.device.DeviceTwin.*;

Anslut en enhet till IoT Hub

A device app can authenticate with IoT Hub using the following methods:

• Delad åtkomstnyckel
• X.509-certifikat

Auktorisera med en delad åtkomstnyckel

För att ansluta en enhet till IoT Hub:

1. Use IotHubClientProtocol to choose a transport protocol. For example:

   IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;
   

2. Använd DeviceClient konstruktören för att lägga till enhetens primära anslutningssträng och protokoll.

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

3. Use open to connect the device to IoT hub. If the client is already open, the method does nothing.

   client.open(true);
   

Auktorisera med ett X.509-certifikat

För att ansluta en enhet till IoT-hubben med ett X.509-certifikat:

1. Build the SSLContext object using buildSSLContext.
2. Lägg till SSLContext informationen till ett ClientOptions-objekt.
3. Ring DeviceClient med hjälp av ClientOptions informationen för att skapa en anslutning från enheten till IoT-hubben.

Detta exempel visar certifikatets indata-parametervärden som lokala variabler för tydlighetens skull. I ett produktionssystem bör du lagra känsliga inmatningsparametrar i miljövariabler eller på en annan mer säker lagringsplats. For example, use Environment.GetEnvironmentVariable("PUBLICKEY") to read a public key certificate string environment variable.

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

För mer information om certifikatautentisering, se:

• Autentisera identiteter med X.509-certifikat
• Handledning: Skapa och ladda upp certifikat för testning

Kodexempel

För exempel på hur man använder X.509-certifikatautentisering för enheter, se:

• Skicka-motta x509-exempel
• Send event x509

Hämta och visa en enhetsdubblering

Efter att ha öppnat klientanslutningen, kalla getTwin för att hämta de aktuella tvillingegenskaperna till ett Twin-objekt.

For example:

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

Uppdatera rapporterade egenskaper för enhetstvilling

After retrieving the current twin, you can begin making reported property updates. Du kan också göra uppdateringar av rapporterade egenskaper utan att hämta den aktuella tvillingen så länge du har rätt version av de rapporterade egenskaperna. Om du skickar rapporterade egenskaper och får ett felmeddelande "förutsättning misslyckades", är versionen av dina rapporterade egenskaper inaktuell. I så fall, hämta den senaste versionen genom att ringa getTwin igen.

To update reported properties:

1. Anropa getReportedProperties för att hämta de rapporterade egenskaperna i en TwinCollection-objekt.

2. Använd put för att uppdatera en rapporterad egenskap inom TwinCollection-objektet. Call put for each reported property update.

3. Använd updateReportedProperties för att tillämpa gruppen av rapporterade egenskaper som uppdaterades med hjälp av put-metoden.

For example:

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

Prenumerera på önskade fastighetsändringar

Anropa subscribeToDesiredProperties för att prenumerera på ändringar av önskade egenskaper. Denna klient mottar en återuppringning med ett Twin-objekt varje gång en önskad egenskap uppdateras. Den återuppringning innehåller antingen hela uppsättningen av önskade egenskaper eller endast den uppdaterade önskade egenskapen, beroende på hur den önskade egenskapen ändrades.

This example subscribes to desired property changes. Eventuella önskade ändringar av egenskaper skickas till en hanterare med namnet DesiredPropertiesUpdatedHandler.

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

In this example, the DesiredPropertiesUpdatedHandler desired property change callback handler calls getDesiredProperties to retrieve the property changes, then prints the updated twin properties.

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

SDK-enhet provexemplar

Azure IoT SDK för Java innehåller ett fungerande exempel för att testa de enhetsappars-koncept som beskrivs i denna artikel. För mer information, se Device Twin Sample.

Skapa en backend-applikation

Den här sektionen beskriver hur man skapar en backend-applikation som:

• Uppdaterar enhetstvinntaggar
• Queries devices using filters on the tags and properties

Klassen ServiceClientDeviceTwin innehåller metoder som tjänster kan använda för att få tillgång till enhetsvinningar.

Tjänsteimportsatser

Använd följande tjänsteimportuttryck för att komma åt Azure IoT SDK för Java.

import com.microsoft.azure.sdk.iot.service.devicetwin.*;
import com.microsoft.azure.sdk.iot.service.exceptions.IotHubException;

Connect to the IoT Hub

You can connect a backend service to IoT Hub using the following methods:

• Delad åtkomstpolicy
• Microsoft Entra

Anslut med hjälp av en delad åtkomstpolicy

Använd en DeviceTwin-konstruktör för att skapa anslutningen till IoT-navet. The DeviceTwin object handles the communication with your IoT hub.

Din applikation behöver service connect-behörighet för att modifiera önskade egenskaper hos en enhetstvilling, och den behöver registry read-behörighet för att söka i identitetsregistret. Det finns ingen standarddelad åtkomstpolicy som endast innehåller dessa två behörigheter, så du måste skapa en om en sådan inte redan finns. Ange denna anslutningssträng för delad åtkomstpolicy som en parameter till fromConnectionString. För mer information om delade åtkomstpolicyer, se Kontrollera åtkomst till IoT Hub med delade åtkomstsignaturer.

Objektet DeviceTwinDevice representerar enhetstvillingen med dess egenskaper och taggar.

For example:

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

Anslut med Microsoft Entra

En backend-app som använder Microsoft Entra måste autentisera sig framgångsrikt och erhålla en säkerhetstoken-uppgift innan den ansluter till IoT Hub. Denna token skickas till en IoT Hub-anslutningsmetod. For general information about setting up and using Microsoft Entra for IoT Hub, see Control access to IoT Hub by using Microsoft Entra ID.

For an overview of Java SDK authentication, see Azure authentication with Java and Azure Identity.

För enkelhetens skull fokuserar detta avsnitt på att beskriva autentisering med hjälp av klientens hemlighet.

Konfigurera Microsoft Entra-app

Du måste konfigurera en Microsoft Entra-app som är inställd på dina föredragna autentiseringsuppgifter. Appen innehåller parametrar, såsom klienthemlighet, som används av bakgrundsapplikationen för autentisering. The available app authentication configurations are:

• Client secret
• Certifikat
• Federated identity credential

Microsoft Entra apps may require specific role permissions depending on operations being performed. Exempelvis krävs IoT Hub Twin Contributor för att möjliggöra läs- och skrivåtkomst till en IoT Hub-enhet och modulpar. För mer information, se Manage access to IoT Hub by using Azure RBAC role assignment.

For more information about setting up a Microsoft Entra app, see Quickstart: Register an application with the Microsoft identity platform.

Autentisera med hjälp av DefaultAzureCredential

The easiest way to use Microsoft Entra to authenticate a backend application is to use DefaultAzureCredential, but it's recommended to use a different method in a production environment including a specific TokenCredential or pared-down ChainedTokenCredential. För mer information om för- och nackdelar med att använda DefaultAzureCredential, se Credential chains in the Azure Identity client library for Java.

DefaultAzureCredential stöder olika autentiseringsmekanismer och bestämmer den lämpliga typer av autentiseringsuppgifter baserat på miljön där den körs. Den försöker använda flera typer av autentiseringsuppgifter i en viss ordning tills den hittar en fungerande autentiseringsuppgift.

Du kan autentisera Microsoft Entra appreferenser med hjälp av DefaultAzureCredentialBuilder. Spara anslutningsparametrar som klienthemlighet, tenantID, klientID och klienthemlighetsvärden som miljövariabler. När TokenCredential har skapats, skicka det till ServiceClient eller annan byggare som 'credential'-parametern.

I detta exempel försöker DefaultAzureCredentialBuilder autentisera en anslutning från listan som beskrivs i DefaultAzureCredential. Resultatet av en lyckad Microsoft Entra-autentisering är en säkerhetstoken-referens som överförs till en konstruktor som exempelvis ServiceClient.

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

Autentisera med ClientSecretCredentialBuilder

Du kan använda ClientSecretCredentialBuilder för att skapa en autentisering med hjälp av klientens hemlig information. Om lyckad, returnerar denna metod en TokenCredential som kan skickas vidare till ServiceClient eller andra byggare som 'credential'-parametern.

I det här exemplet har Microsoft Entra appregistrering klienthemlighet, klient-ID och hyresgäst-ID-värden lagts till i miljövariabler. Dessa miljövariabler används av ClientSecretCredentialBuilder för att bygga upp referensen.

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

Andra autentiseringsklasser

Java SDK:n inkluderar också dessa klasser som autentiserar en backend-app med Microsoft Entra.

• AuthorizationCodeCredential
• AzureCliCredential
• AzureDeveloperCliCredential
• AzurePipelinesCredential
• ChainedTokenCredential
• ClientAssertionCredential
• ClientCertificateCredential
• DeviceCodeCredential
• EnvironmentCredential
• InteractiveBrowserCredential
• ManagedIdentityCredential
• OnBehalfOfCredential

Kodexempel

För fungerande exempel på autentisering för Microsoft Entra-tjänsten, se Exempel på rollbaserad autentisering.

Uppdatera fält i enhetstvillingen

För att uppdatera enhetens tvillingfält:

1. Use getTwin to retrieve the current device twin fields

   Det här exemplet hämtar och skriver ut fälten för enhetstvilling:

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

2. Använd ett HashSet objekt för att add en grupp av dubbla taggpar

3. Använd setTags för att lägga till en grupp taggpar från ett tags objekt till ett DeviceTwinDevice objekt.

4. Använd updateTwin för att uppdatera tvillingen i IoT-hubben

   Detta exempel uppdaterar region- och anläggnings-tagen för enhetens tvilling:

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

Create a device twin query

Detta avsnitt demonstrerar två enhetstvillingförfrågningar. Enhetstvillingfrågor är SQL-liknande frågor som returnerar en resultatuppsättning av enhetstvillingar.

Klassen Query innehåller metoder som kan användas för att skapa SQL-liknande frågor till IoT Hub för tvillingar, jobb, enhetsjobb eller rådata.

För att skapa en enhetsfråga:

1. Use createSqlQuery to build the twins SQL query

2. Use queryTwin to execute the query

3. Använd hasNextDeviceTwin för att kontrollera om det finns en annan enhetstwin i resultatuppsättningen.

4. Använd getNextDeviceTwin för att hämta nästa enhetsdubblett från resultatuppsättningen

Följande exempelqueries returnerar maximalt 100 enheter.

Denna exempel förfrågan väljer endast enhetens tvillingar för enheter som är placerade i anläggningen Redmond43.

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

This example query refines the first query to select only the devices that are also connected through a cellular network.

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

SDK service sample

Azure IoT SDK för Java erbjuder ett fungerande exempel på en tjänsteapp som hanterar uppgifter kring enhetstvillingar. For more information, see Device Twin Sample.

• Python SDK - Python version 3.7 eller senare rekommenderas. Se till att använda 32-bitars eller 64-bitars installation som krävs av din konfiguration. När du uppmanas under installationen, se till att lägga till Python till din plattformsspecifika miljövariabel.

Overview

Den här artikeln beskriver hur man använder Azure IoT SDK för Python för att skapa kod för enhets- och backend-tjänster för enhetstvillingar.

Installera paket

azure-iot-device-biblioteket måste vara installerat för att skapa enhetsapplikationer.

pip install azure-iot-device

azure-iot-hub-biblioteket måste vara installerat för att skapa tjänsteapplikationer i backend.

pip install azure-iot-hub

Skapa en applikation för enhet

** "S apparaten-tillämpningar kan läsa och skriva rapporterade egenskaper hos tvillingar och bli meddelade om önskade ändringar av tvilling-egenskaper som anges av en backend-applikation eller IoT-hubb."

Klassen IoTHubDeviceClient innehåller metoder som kan användas för att arbeta med enhetstwins.

Den här sektionen beskriver hur man skapar programkod för enheten som:

• Hämtar en enhetsdubblering och undersöker rapporterade egenskaper
• Patcha rapporterade egenskaper för enhetstvilling

Importförklaring för enhet

Lägg till den här koden för att importera IoTHubDeviceClient-funktionerna från azure.iot.device SDK.

from azure.iot.device import IoTHubDeviceClient

Anslut en enhet till IoT Hub

En enhetsapp kan autentisera med IoT Hub med hjälp av följande metoder:

• Delad åtkomstnyckel
• X.509-certifikat

Authenticate using a shared access key

För att ansluta en enhet till IoT Hub:

1. Anropa create_from_connection_string för att lägga till enhetens primära anslutningssträng.
2. Anropa connect för att ansluta enhetsklienten.

For example:

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

Autentisera med ett X.509-certifikat

För att ansluta en enhet till IoT Hub med ett X.509-certifikat:

1. Använd create_from_x509_certificate för att lägga till X.509-certifikatparametrarna
2. Anropa connect för att ansluta enhetsklienten

This example shows certificate input parameter values as local variables for clarity. I ett produktionssystem, lagra känsliga inmatningsparametrar i miljövariabler eller någon annan säkrare lagringsplats. For example, use os.getenv("HOSTNAME") to read the host name environment variable.

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

For more information about certificate authentication, see:

• Autentisera identiteter med X.509-certifikat
• Handledning: Skapa och ladda upp certifikat för testning

Kodexempel

För fungerande exempel på enhetsautentisering med X.509-certifikat, se de exempel vars filnamn slutar på x509 under Async hub-scenarier.

Hämta en enhetstvilling och undersök rapporterade egenskaper

Du kan hämta och granska information om enhetstvillingar, inklusive etiketter och egenskaper. The device twin information retrieved matches device twin JSON-formatted data that you can view for a device in the Azure portal.

Använd get_twin för att hämta enhetstvillingen från Azure IoT Hub-tjänsten. Tvillinginformationen placeras i en variabel som kan skrivas ut eller undersökas.

This example retrieves the device twin and uses the print command to view the device twin in JSON format.

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

Patch reported device twin properties

Du kan använda en patch för att uppdatera enhetsrapporterade egenskaper i JSON-format.

För att tillämpa en patch för att uppdatera rapporterade egenskaper:

1. Tilldela en JSON-patch för en rapporterad egenskap till en variabel.
2. Call patch_twin_reported_properties to apply the JSON patch to reported properties. This is a synchronous call, meaning that this function does not return until the patch is sent to the service and acknowledged.

If patch_twin_reported_properties returns an error, this function raises the corresponding error.

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

Du kan också anropa dessa metoder för att uppdatera enhetstvillingar:

• Call replace_twin to replace device twin tags and desired properties.
• Call update_twin to update device twin tags and desired properties.

Incoming desired properties patch handler

Call on_twin_desired_properties_patch_received to create a handler function or coroutine that is called when a twin desired properties patch is received. The handler takes one argument, which is the twin patch in the form of a JSON dictionary object.

Denna exempelkonfiguration upprättar en önskade egenskapers patch-hanterare med namnet twin_patch_handler.

For example:

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

twin_patch_handler tar emot och skriver ut uppdateringar av JSON-önskade egenskaper.

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

SDK-enhetsexempel

Python SDK för Azure IoT inkluderar följande exempel:

• get_twin - Anslut till en enhet och hämta tvillinginformation.
• update_twin_reported_properties - Uppdatera tvillingens rapporterade egenskaper.
• receive_twin_desired_properties - Ta emot och uppdatera önskade egenskaper.

Skapa en backend-applikation

En backend-applikation ansluter till en enhet genom IoT Hub och kan läsa enhetens rapporterade och önskade egenskaper, skriva enhetens önskade egenskaper och köra enhetsfrågor.

Detta avsnitt beskriver hur man skapar en backend-applikation för att:

• Uppdatera tvillingtaggar och önskade egenskaper
• Frågar enheter med användning av filter på taggarna och egenskaperna

IoTHubRegistryManager-klassen exponerar alla metoder som krävs för att skapa en backend-applikation för att interagera med enhetstvillingar från tjänsten.

Anslut till IoT hub

Du kan ansluta en backend-tjänst till IoT Hub med hjälp av följande metoder:

• Policy för delad åtkomst
• Microsoft Entra

Anslut med en delad åtkomstpolicy

Anslut till IoT-navet med from_connection_string. Din applikation behöver behörigheten service connect för att ändra önskade egenskaper hos en enhetstvilling, och den behöver registerläsning för att fråga identitetsregistret. There is no default shared access policy that contains only these two permissions, so you need to create one if a one does not already exist. Ange den här anslutningssträngen för delad åtkomstpolicy som en parameter till fromConnectionString. För mer information om delade åtkomstpolicys, se Kontrollera åtkomst till IoT Hub med delade åtkomstsignaturer.

For example:

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)

Anslut med Microsoft Entra

En backend-app som använder Microsoft Entra måste autentisera sig framgångsrikt och erhålla en säkerhetstokenuppgift innan den ansluter till IoT Hub. Denna token skickas till en IoT Hubs anslutningsmetod. För generell information om hur man konfigurerar och använder Microsoft Entra för IoT Hub, se Kontrollera åtkomst till IoT Hub med Microsoft Entra ID.

För en översikt över autentisering av Python SDK, se Autentisera Python-appar till Azure-tjänster med hjälp av Azure SDK för Python

Konfigurera Microsoft Entra-app

Du måste konfigurera en Microsoft Entra-app som är inställd för din föredragna autentiseringsmetod. Appen innehåller parametrar som klienthemlighet som används av backend-applikationen för autentisering. De tillgängliga konfigurationerna för appautentisering är:

• Klienthemlighet
• Certifikat
• Federerad identitetsuppgift

Microsoft Entra-appar kan kräva specifika rollbehörigheter beroende på vilka operationer som utförs. For example, IoT Hub Twin Contributor is required to enable read and write access to a IoT Hub device and module twins. För mer information, se Manage access to IoT Hub by using Azure RBAC role assignment.

För mer information om hur du konfigurerar en Microsoft Entra-app, se Snabbstart: Registrera en applikation med Microsofts identitetsplattform.

Autentisera med DefaultAzureCredential

The easiest way to use Microsoft Entra to authenticate a backend application is to use DefaultAzureCredential, but it's recommended to use a different method in a production environment including a specific TokenCredential or pared-down ChainedTokenCredential. For simplicity, this section describes authentication using DefaultAzureCredential and Client secret. For more information about the pros and cons of using DefaultAzureCredential, see Credential chains in the Azure Identity client library for Python.

DefaultAzureCredential supports different authentication mechanisms and determines the appropriate credential type based on the environment it's executing in. It attempts to use multiple credential types in an order until it finds a working credential.

Microsoft Entra requires this import package and corresponding import statement:

pip install azure-identity

from azure.identity import DefaultAzureCredential

In this example, Microsoft Entra app registration client secret, client ID, and tenant ID have been added to environment variables. These environment variables are used by DefaultAzureCredential to authenticate the application. The result of a successful Microsoft Entra authentication is a security token credential that is passed to an IoT Hub connection method.

from azure.identity import DefaultAzureCredential
credential = DefaultAzureCredential()

The resulting AccessToken can then be passed to from_token_credential to connect to IoT Hub for any SDK client that accepts Microsoft Entra credentials:

• IoTHubRegistryManager to create a service connection to IoT Hub using an Entra token credential.
• IoTHubJobManager
• DigitalTwinClient
• IoTHubHttpRuntimeManager
• IoTHubConfigurationManager

from_token_credential requires two parameters:

• Azure-tjänstens URL - Azure-tjänstens URL ska ha formatet {Your Entra domain URL}.azure-devices.net utan prefixet https://. For example, MyAzureDomain.azure-devices.net.
• The Azure credential token

I det här exemplet erhålls Azure-uppgifterna med hjälp av DefaultAzureCredential. Azure-tjänstens URL och autentiseringsuppgifter tillhandahålls sedan till IoTHubRegistryManager.from_token_credential för att skapa anslutningen till IoT Hub.

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)

Kodexempel

För fungerande exempel på autentisering med Microsoft Entra-tjänsten, se Microsoft Authentication Library (MSAL) för Python.

Update twin tags and desired properties

You can update both device twin tags and desired properties from a backend application at the same time using update_twin.

1. Anropa get_twin för att få den aktuella versionen av enhetstvillingen
2. Använd klassen Twin för att lägga till taggar och egenskaper i JSON-format.
3. Ring update_twin för att tillämpa uppdateringen på enhetstvillingen. You can also use replace_twin to replace desired properties and tags for a device twin.

Detta exempel uppdaterar region- och plant-tagginformation och ställer in en önskad egenskap på 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)

Skapa en sökning för enhetstvilling

Du kan fråga enhetstvillinginformation med hjälp av enhetstvillingfrågor. Enhetsdubbelförfrågningar är SQL-liknande förfrågningar som returnerar en resultatmängd av enhetsdubbler.

För att använda en enhetstvillingfråga:

1. Använd ett QuerySpecification-objekt för att definiera en SQL-liknande frågeförfrågan.

2. Använd query_iot_hub för att fråga en IoTHub och hämta information om enhetsdubbel med hjälp av SQL-liknande frågespecifikation.

Det här exemplet kör två frågor. Den första väljer endast enhetstvillingar av enheter som är placerade i Redmond43-anläggningen, och den andra förfinar frågan för att välja endast de enheter som också är anslutna via ett mobilnätverk. Resultat skrivs ut efter varje fråga.

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

Exempel på SDK-tjänst

Azure IoT SDK för Python innehåller ett fungerande exempel på en tjänsteapp som hanterar uppgifter för device twin. För mer information, se Registry Manager Query Sample.

• Kräver Node.js version 10.0.x eller senare

Overview

Den här artikeln beskriver hur du använder Azure IoT SDK för Node.js för att skapa applikationskod för enheter och backend-tjänster för enhetstvillingar.

Skapa en enhetsapplikation

Enhetsapplikationer kan läsa och skriva tvillingrapporterade egenskaper och bli informerade om önskade förändringar i tvillingegenskaper som sätts av en backend-applikation eller IoT Hub.

Denna avsnitt beskriver hur du använder paketet azure-iot-device i Azure IoT SDK för Node.js för att skapa en enhetsapplikation till:

• Hämta en enhetstvilling och granska rapporterade egenskaper
• Update reported device twin properties
• Få meddelande om önskade ändringar av fastighetsdetaljer

Installera enhets-SDK-paket

Run this command to install the azure-iot-device device SDK on your development machine:

npm install azure-iot-device --save

Connect a device to IoT Hub

En enhetsapp kan autentisera med IoT Hub med hjälp av följande metoder:

• X.509-certifikat
• Delad åtkomstnyckel

Autenticera med ett X.509-certifikat

X.509-certifikatet är kopplat till anslutningstransporten för enhet-till-IoT-hubb.

För att konfigurera en anslutning mellan en enhet och IoT Hub med ett X.509-certifikat:

1. Anropa fromConnectionString för att lägga till enhets- eller identitetsmodulens anslutningssträng och transporttyp till Client-objektet. Lägg till x509=true i anslutningssträngen för att indikera att ett certifikat läggs till i DeviceClientOptions. For example:

   • En enhet anslutningssträng:

     HostName=xxxxx.azure-devices.net;DeviceId=Device-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true

   • En identitetsmodul anslutningssträng:

     HostName=xxxxx.azure-devices.net;DeviceId=Device-1;ModuleId=Module-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true

2. Konfigurera en JSON-variabel med certifikatdetaljer och skicka den till DeviceClientOptions.

3. Anropa setOptions för att lägga till ett X.509-certifikat och nyckel (och eventuellt, lösenord) till klienttransporten.

4. Anropa öppna för att öppna anslutningen från enheten till IoT Hub.

Detta exempel visar certifikatkonfigurationsinformation inom en JSON-variabel. Certifieringskonfigurationen clientOptions skickas till setOptions, och anslutningen öppnas med hjälp av 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);

För mer information om certifikatautentisering, se:

• Verifiera identiteter med X.509-certifikat
• Skapa och ladda upp certifikat för testning

Kodexempel

För ett fungerande exempel på autentisering med X.509-certifikat för enhet, se Simple sample device X.509.

Autentisera med en delad åtkomstnyckel

Paketet azure-iot-device innehåller objekt som interagerar med IoT-enheter. Twin-klassen inkluderar tvåspecifika objekt. Den här sektionen beskriver Client klasskod som används för att läsa och skriva data för enhetsdubblering.

Välj en transportprotokoll

The Client object supports these protocols:

• Amqp
• Http - När du använder Http kontrollerar Client-instansen meddelanden från IoT Hub sällan (minst var 25:e minut).
• Mqtt
• MqttWs
• AmqpWs

Installera nödvändiga transportprotokoll på din utvecklingsmaskin.

Till exempel installerar det här kommandot Mqtt-protokollet:

npm install azure-iot-device-mqtt --save

För mer information om skillnaderna mellan stöd för MQTT, AMQP och HTTPS, se Vägledning för kommunikation från moln till enhet och Välj ett kommunikationsprotokoll.

Skapa en klientmodul

Skapa en Client modul med det installerade paketet.

For example:

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

Skapa en protokollmodul

Skapa en Protocol modul med hjälp av ett installerat transportpaket.

This example assigns the MQTT protocol:

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

Lägg till enhetsanslutningssträngen och transportprotokollet

Anropa fromConnectionString för att tillhandahålla enhetsanslutningsparametrar:

• connStr - En anslutningssträng som kapslar in "enhet ansluta"-behörigheter för en IoT-hubb. Anslutningssträngen innehåller värdnamn, enhets-ID och delad åtkomstnyckel i detta format: "HostName=<iothub_host_name>;DeviceId=<device_id>;SharedAccessKey=<device_key>".
• transportCtor - The transport protocol.

Det här exemplet använder Mqtt transportprotokoll:

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

Öppna anslutningen till IoT Hub

Använd open-metoden för att öppna en anslutning mellan en IoT-enhet och IoT Hub. Använd .catch(err) för att fånga ett fel och exekvera hanteringskod.

For example:

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

Hämta en enhetstvilling och undersök rapporterade egenskaper

Call getTwin to retrieve current device twin information into a Twin object.

For example:

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

Uppdatera rapporterade enhetsdubbla egenskaper

Använd update för att uppdatera enhetens rapporterade egenskaper. Include a JSON-formatted patch as the first parameter and function execution status callback method as the second parameter to the method.

I det här exemplet lagras en JSON-formaterad enhetstvillingändring i patch-variabeln. Patchen innehåller ett enhetsdubbel connectivity uppdateringsvärde av cellular. The patch and error handler are passed to the update method. Om det uppstår ett fel visas ett felmeddelande i konsolen.

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

Receive notice of desired property changes

Skapa en händelselyssnare för uppdatering av önskade egenskaper som körs när en önskad egenskap ändras i enheten genom att skicka namnet på återkallningsmetoden till twin.on.

The desired property event listener can take one of the following forms:

• Receive all patches with a single event handler
• Få en händelse om något ändras i en egenskapsgrupp.
• Ta emot en händelse för en enskild ändring av egenskap

Ta emot alla patchar med en enda händelsehanterare

Du kan skapa en lyssnare för att ta emot ändringar i valfri egenskap.

Detta kodexempel skrivs ut alla egenskaper som tas emot från tjänsten.

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

Ta emot en händelse om något ändras under en egenskapsgruppering.

You can create a listener to receive an event if anything under a property grouping changes.

For example:

1. Egenskaperna minTemperature och maxTemperature finns under en egenskapsgruppering som heter properties.desired.climate changes.

2. A backend service application applies this patch to update minTemperature and maxTemperature desired properties:

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

3. This code sets up a desired properties change event listener that triggers for any changes within the properties.desired.climate property grouping. Om det finns en önskad egenskapsändring inom denna grupp, meddelanden om förändring av minimi- och maximitemperatur som visas på konsolen.

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

Ta emot en händelse för en enskild egendomsändring

Du kan konfigurera en lyssnare för en enskild egendomsändring. In this example, the code for this event is executed only if the fanOn boolean value is part of the patch. The code outputs the new desired fanOn state whenever the service updates it.

1. En backend-applikation tillämpar denna önskade egenskapspatch:

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

2. Lyssnaren utlöses endast när fanOn-egenskapen ändras.

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

Enhet SDK-exempel

Azure IoT SDK för Node.js innehåller två exempel på enhetsdubblering:

• Enkel exempel-enhetstvilling

• Enkel exempelenhetstvilling med SAS

Skapa en backendapplikation

Ett backend-program ansluter till en enhet via IoT Hub och kan läsa enhetens rapporterade och önskade egenskaper, skriva enhetens önskade egenskaper och köra enhetsfrågor.

Den här sektionen beskriver hur man skapar en backend-applikation som:

• Hämtar och uppdaterar en enhetstvilling
• Skapar en enhetstvillingförfrågan

Installera tjänste-SDK-paketet

Kör det här kommandot för att installera azure-iothub på din utvecklingsdator:

npm install azure-iothub --save

Registret-klassen exponerar alla metoder som krävs för att interagera med enhetstvillingar från en backend-applikation.

Anslut till IoT-hubb

Du kan ansluta en backendtjänst till IoT Hub med följande metoder:

• Policy för delad åtkomst
• Microsoft Entra

Anslut med en delad åtkomstpolicy

Använd fromConnectionString för att ansluta till IoT-huben. Din applikation behöver behörigheten service connect för att ändra önskade egenskaper hos en enhetstvilling, och den behöver behörigheten registry read för att söka i identitetsregistret. Det finns ingen standarddelningsåtkomstpolicy som endast innehåller dessa två behörigheter, så du måste skapa en om en sådan inte redan finns. Supply this shared access policy connection string as a parameter to fromConnectionString. För mer information om delade åtkomstpolicyer, se Control access to IoT Hub with shared access signatures.

'use strict';
var iothub = require('azure-iothub');
var connectionString = '{Shared access policy connection string}';
var registry = iothub.Registry.fromConnectionString(connectionString);

Anslut med Microsoft Entra

En backend-app som använder Microsoft Entra måste lyckas autentisera sig och erhålla ett säkerhetstokensbehörighetsuppgift innan den ansluter till IoT Hub. Denna token skickas till en anslutningsmetod för IoT Hub. För generell information om hur du ställer in och använder Microsoft Entra för IoT Hub, se Kontrollera åtkomst till IoT Hub med hjälp av Microsoft Entra ID.

För en översikt över autentisering med Node.js SDK, se:

• Kom igång med användarautentisering på Azure
• Azure Identity client library for JavaScript

Konfigurera Microsoft Entra-appen

Du måste ställa in en Microsoft Entra-app som är konfigurerad för din föredragna autentiseringsuppgift. Applikationen innehåller parametrar som klienthemlighet som används av bakgrundsapplikationen för autentisering. The available app authentication configurations are:

• Klienthemlighet
• Certifikat
• Federated identity credential

Microsoft Entra-appar kan kräva specifika rollbehörigheter beroende på vilka operationer som utförs. Till exempel krävs IoT Hub Twin Contributor för att aktivera läs- och skrivåtkomst till en IoT Hubs enhets- och modulspegel. For more information, see Manage access to IoT Hub by using Azure RBAC role assignment.

For more information about setting up a Microsoft Entra app, see Quickstart: Register an application with the Microsoft identity platform.

Authenticate using DefaultAzureCredential

Det enklaste sättet att använda Microsoft Entra för att autentisera en backendapplikation är att använda DefaultAzureCredential, men det rekommenderas att använda en annan metod i en produktionsmiljö, inklusive en specifik TokenCredential eller en nedskalad version av ChainedTokenCredential. For simplicity, this section describes authentication using DefaultAzureCredential and Client secret. För mer information om för- och nackdelarna med att använda DefaultAzureCredential, se Credential chains i Azure Identity-klientbiblioteket för JavaScript

DefaultAzureCredential stöder olika autentiseringsmekanismer och bestämmer den lämpliga autentiseringstypen baserat på den miljö där det körs. It attempts to use multiple credential types in an order until it finds a working credential.

Microsoft Entra kräver det här paketet.

npm install --save @azure/identity

I det här exemplet har klienthemlighet, klient-ID och hyresgäst-ID från Microsoft Entra-appregistrering lagts till i miljövariabler. Dessa miljövariabler används av DefaultAzureCredential för att autentisera applikationen. Resultatet av en lyckad Microsoft Entra-autentisering är en säkerhetstokenuppgift som skickas till en IoT Hub-anslutningsmetod.

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

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

The resulting credential token can then be passed to fromTokenCredential to connect to IoT Hub for any SDK client that accepts Microsoft Entra credentials:

• Registry
• Client
• JobClient

fromTokenCredential kräver två parametrar:

• The Azure service URL - The Azure service URL should be in the format {Your Entra domain URL}.azure-devices.net without a https:// prefix. For example, MyAzureDomain.azure-devices.net.
• The Azure credential token

I det här exemplet hämtas Azure-autentiseringsuppgiften med hjälp av DefaultAzureCredential. Azure-domänens URL och referens uppges sedan till Registry.fromTokenCredential för att skapa anslutningen till IoT Hub.

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

Kodexempel

För fungerande exempel på autentiseringstjänsten i Microsoft Entra, se Azure identity examples.

Hämta och uppdatera enhetstvilling

Du kan skapa en patch som innehåller uppdateringar av taggar och önskade egenskaper för en enhetstvilling.

För att uppdatera en enhetstvilling:

1. Anropa getTwin för att hämta enheten twin-objektet.

• Formatera en patch som innehåller uppdateringen av enhetsdubbla. Patchen är formaterad i JSON som beskrivet i Twin-klassen. En backend-tjänstpatch kan innehålla uppdateringar av taggar och önskade egenskaper. För mer information om patch-format, se Tags och egenskapsformat.

1. Anropa update för att uppdatera enhetstvillingen med patchen.

I det här exemplet hämtas enhetstvillingen för myDeviceId, sedan appliceras en patch på tvillingarna som innehåller location tagguppdateringen av region: 'US', plant: 'Redmond43'.

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

Skapa en fråga om enhetsinformation

Du kan skapa SQL-liknande enhetsfrågor för att samla in information från enhetstvillingar.

Använd createQuery för att skapa en fråga som kan köras på en IoT-navinstans för att hitta information om enheter eller jobb.

createQuery innehåller två parametrar.

• sqlQuery - Frågan skriven som en SQL-sträng.
• pageSize - The desired number of results per page (optional. default: 1000, max: 10000).

If the pageSize parameter is specified, the query object contains a hasMoreResults boolean property that you can check and use the nextAsTwin method to get the next twin results page as many times as needed to retrieve all results. En metod som kallas next är tillgänglig för resultat som inte är enhetstvillingar, till exempel resultaten av aggregeringsfrågor.

Det här exempelfrågan väljer endast enhetsdubletterna för enheter som finns i Redmond43 anläggningen.

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

This example query refines the first query to select only the devices that are also connected through cellular network.

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

Service SDK sample

Azure IoT SDK för Node.js erbjuder ett fungerande exempel på en tjänsteapp som hanterar uppgifter för enhetstvillingar. For more information, see Device Twin Backend Service - This project is used to send device twin patch updates for a specific device.