Kom igång med IoT Hub-modulidentiteter och modulidentitetstvillingar

Artikel
01/03/2025

Modulidentiteter och modulidentitetstvillingar liknar Enhetsidentiteter och enhetstvillingar i Azure IoT Hub, men ger finare kornighet. Även om Azure IoT Hub-enhetsidentiteter och enhetstvillingar gör det möjligt för serverdelsprogrammet att konfigurera en enhet och ge insyn i enhetens villkor, ger en modulidentitets- och modulidentitetstvilling dessa funktioner för enskilda komponenter på en enhet. På kompatibla enheter med flera komponenter, till exempel operativsystemenheter eller enheter med inbyggd programvara, tillåter modulidentiteter och modulidentitetstvillingar isolerad konfiguration och villkor för varje komponent. Mer information finns i Förstå Azure IoT Hub-modultvillingar.

Kommentar

De funktioner som beskrivs i den här artikeln är endast tillgängliga på standardnivån för IoT Hub. Mer information om de grundläggande och standard-/kostnadsfria IoT Hub-nivåerna finns i Välj rätt IoT Hub-nivå för din lösning.

Den här artikeln visar hur du utvecklar två typer av program:

Enhetsappar som visar och uppdaterar modulidentitetstvillingen rapporterade egenskaper och hanterar begäranden om att uppdatera önskade egenskaper.
Tjänstappar som kan läsa och ange önskade egenskaper för modulidentitet.

Kommentar

Den här artikeln är avsedd att komplettera Azure IoT SDK-exempel som refereras inifrån den här artikeln. Du kan använda SDK-verktyg för att skapa både enhets- och serverdelsprogram.

Förutsättningar

En IoT Hub
En IoT Hub-enhet
En enhetsmodulidentitet för IoT Hub
Om ditt program använder MQTT-protokollet kontrollerar du att port 8883 är öppen i brandväggen. MQTT-protokollet kommunicerar via port 8883. Den här porten kan blockeras i vissa företags- och utbildningsnätverksmiljöer. Mer information och sätt att kringgå det här problemet finns i Ansluta till IoT Hub (MQTT).

Kräver Visual Studio

Översikt

Den här artikeln beskriver hur du använder Azure IoT SDK för .NET för att skapa programkod för enhet och serverdelstjänst för modulidentitetstvillingar.

Skapa ett enhetsprogram

I det här avsnittet beskrivs hur du använder enhetsprogramkod för att:

Hämta en modulidentitetstvilling och granska rapporterade egenskaper
Uppdatera egenskaper för rapporterad modulidentitetstvilling
Skapa en modul för önskad egenskapsuppdateringsanropshanterare

Viktigt!

Den här artikeln innehåller steg för att ansluta en enhet med en signatur för delad åtkomst, även kallad symmetrisk nyckelautentisering. Den här autentiseringsmetoden är praktisk för testning och utvärdering, men att autentisera en enhet med X.509-certifikat är en säkrare metod. Mer information finns i Metodtips > för säkerhet Anslutningssäkerhet.

Obligatoriskt NuGet-paket för enhet

Enhetsklientprogram som skrivits i C# kräver NuGet-paketet Microsoft.Azure.Devices.Client .

Lägg till dessa using instruktioner för att använda enhetsbiblioteket.

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

Ansluta till en enhet

Klassen ModuleClient exponerar alla metoder som krävs för att interagera med modulidentitetstvillingar från enheten.

Anslut till enheten med metoden CreateFromConnectionString med modulidentiteten anslutningssträng.

Anrop CreateFromConnectionString utan en transportparameter ansluter med amqp-standardtransporten.

Det här exemplet ansluter till enheten med amqp-standardtransporten.

static string ModuleConnectionString = "{Device module identity connection string}";
private static ModuleClient _moduleClient = null;

_moduleClient = ModuleClient.CreateFromConnectionString(ModuleConnectionString, null);

Kommentar

C#/.NET stöder inte anslutning av en enhetsapp till en IoT Hub-modulidentitetstvilling med hjälp av ett certifikat.

Hämta en modulidentitetstvilling och granska egenskaper

Anropa GetTwinAsync för att hämta de aktuella egenskaperna för modulidentitetstvillingen till ett Tvillingobjekt .

Det här exemplet hämtar och visar egenskaper för modulidentitetstvillingar i JSON-format.

Console.WriteLine("Retrieving twin...");
Twin twin = await _moduleClient.GetTwinAsync();
Console.WriteLine("\tModule identity twin value received:");
Console.WriteLine(JsonConvert.SerializeObject(twin.Properties));

Uppdatera rapporterade egenskaper för modulidentitetstvilling

Så här uppdaterar du en tvillingrapporterad egenskap:

Skapa ett TwinCollection-objekt för den rapporterade egenskapsuppdateringen
Uppdatera en eller flera rapporterade egenskaper i TwinCollection objektet
Använd UpdateReportedPropertiesAsync för att skicka rapporterade egenskapsändringar till IoT Hub-tjänsten

Till exempel:

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

Skapa en önskad egenskapsuppdateringsanropshanterare

Skicka motringningshanterarens metodnamn till SetDesiredPropertyUpdateCallbackAsync för att skapa en önskad egenskapsuppdateringsanropshanterare som körs när en önskad egenskap ändras i modulidentitetstvillingen.

Det här anropet konfigurerar till exempel systemet för att meddela en metod med namnet OnDesiredPropertyChangedAsync när en önskad modulegenskap ändras.

await _moduleClient.SetDesiredPropertyUpdateCallbackAsync(OnDesiredPropertyChangedAsync, null);

Egenskaperna för modulidentitetstvilling skickas till motringningsmetoden som en TwinCollection och kan undersökas som KeyValuePair strukturer.

Det här exemplet tar emot önskade egenskapsuppdateringar som en TwinCollectionoch loopar sedan igenom och skriver ut samlingsuppdateringarna KeyValuePair . När du har loopat igenom KeyValuePair samlingen anropas UpdateReportedPropertiesAsync koden för att uppdatera den DateTimeLastDesiredPropertyChangeReceived rapporterade egenskapen för att hålla den senaste uppdaterade tiden uppdaterad.

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 _moduleClient.UpdateReportedPropertiesAsync(reportedProperties);
}

Exempel på SDK-modul

Azure IoT SDK för .NET innehåller arbetsexempel på enhetsappar som hanterar modulidentitetstvillinguppgifter. Mer information finns i:

Skapa ett serverdelsprogram

I det här avsnittet beskrivs hur du läser och uppdaterar modulidentitetsfält.

Klassen RegistryManager exponerar alla metoder som krävs för att skapa ett serverdelsprogram för att interagera med modulidentitetstvillingar från tjänsten.

Obligatoriskt NuGet-tjänstpaket

Serverdelstjänstprogram kräver NuGet-paketet Microsoft.Azure.Devices .

Lägg till dessa using instruktioner för att använda tjänstbiblioteket.

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

Ansluta till IoT Hub

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

Princip för delad åtkomst
Microsoft Entra

Viktigt!

Den här artikeln innehåller steg för att ansluta till en tjänst med hjälp av en signatur för delad åtkomst. Den här autentiseringsmetoden är praktisk för testning och utvärdering, men autentisering till en tjänst med Microsoft Entra-ID eller hanterade identiteter är en säkrare metod. Mer information finns i Metodtips för > säkerhet Molnsäkerhet.

Ansluta med en princip för delad åtkomst

Anslut ett serverdelsprogram till IoT Hub med CreateFromConnectionString.

Metoden UpdateModuleAsync som används i det här avsnittet kräver behörigheten för principen för delad åtkomst i Service Connect för att lägga till önskade egenskaper i en modul. Som parameter till CreateFromConnectionStringanger du en princip för delad åtkomst anslutningssträng som innehåller Service Connect-behörighet. Mer information om principer för delad åtkomst finns i Kontrollera åtkomst till IoT Hub med signaturer för delad åtkomst.

Till exempel:

static RegistryManager registryManager;
static string connectionString = "{IoT hub shared access policy connection string}";
registryManager = RegistryManager.CreateFromConnectionString(connectionString);

Ansluta med Microsoft Entra

En serverdelsapp som använder Microsoft Entra måste autentisera och hämta en autentiseringsuppgift för säkerhetstoken innan den ansluter till IoT Hub. Den här token skickas till en IoT Hub-anslutningsmetod. Allmän information om hur du konfigurerar och använder Microsoft Entra för IoT Hub finns i Kontrollera åtkomst till IoT Hub med hjälp av Microsoft Entra-ID.

Konfigurera Microsoft Entra-app

Du måste konfigurera en Microsoft Entra-app som är konfigurerad för dina önskade autentiseringsautentiseringsuppgifter. Appen innehåller parametrar som klienthemlighet som används av serverdelsprogrammet för att autentisera. De tillgängliga appautentiseringskonfigurationerna är:

Klienthemlighet
Certifikat
Federerade identitetsautentiseringsuppgifter

Microsoft Entra-appar kan kräva specifika rollbehörigheter beroende på åtgärder som utförs. Till exempel krävs IoT Hub Twin-deltagare för att aktivera läs- och skrivåtkomst till en IoT Hub-enhet och modultvillingar. Mer information finns i Hantera åtkomst till IoT Hub med hjälp av Rolltilldelning i Azure RBAC.

Mer information om hur du konfigurerar en Microsoft Entra-app finns i Snabbstart: Registrera ett program med Microsofts identitetsplattform.

Autentisera med defaultAzureCredential

Det enklaste sättet att använda Microsoft Entra för att autentisera ett serverdelsprogram är att använda DefaultAzureCredential, men vi rekommenderar att du använder en annan metod i en produktionsmiljö, inklusive en specifik TokenCredential eller avskalad ChainedTokenCredential. För enkelhetens skull beskriver det här avsnittet autentisering med hjälp av DefaultAzureCredential och klienthemlighet. Mer information om fördelar och nackdelar med att använda finns DefaultAzureCredentiali Användningsvägledning för DefaultAzureCredential.

DefaultAzureCredential stöder olika autentiseringsmekanismer och avgör lämplig typ av autentiseringsuppgifter baserat på den miljö som körs i. Den försöker använda flera typer av autentiseringsuppgifter i en ordning tills den hittar en fungerande autentiseringsuppgift.

Microsoft Entra kräver dessa NuGet-paket och motsvarande using instruktioner:

Azure.Core
Azure.Identity

using Azure.Core;
using Azure.Identity;

I det här exemplet läggs Microsoft Entra-appregistreringsklienthemlighet, klient-ID och klient-ID till i miljövariabler. Dessa miljövariabler används av DefaultAzureCredential för att autentisera programmet. Resultatet av en lyckad Microsoft Entra-autentisering är en säkerhetstokenautentiseringsuppgift som skickas 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 connect to IoT Hub-metod för alla SDK-klienter som accepterar Microsoft Entra-autentiseringsuppgifter:

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

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

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

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

Kodexempel

Ett fungerande exempel på Microsoft Entra-tjänstautentisering finns i Exempel på rollbaserad autentisering.

Läsa och uppdatera modulidentitetsfält

Anropa GetModuleAsync för att hämta aktuella modulidentitetstvillingfält till ett modulobjekt .

Klassen Module innehåller properties som motsvarar avsnitt i en modulidentitetstvilling. Använd klassegenskaperna Modul för att visa och uppdatera modulens identitetstvillingfält. Du kan använda objektegenskaperna Module för att uppdatera flera fält innan du skriver uppdateringarna till enheten med hjälp av UpdateModuleAsync.

När du har gjort fältuppdateringar för modulidentitetstvillingar anropar du UpdateModuleAsync för att skriva Module tillbaka objektfältuppdateringar till en enhet. Använd try och catch logik tillsammans med en felhanterare för att fånga felaktigt formaterade korrigeringsfel från UpdateModuleAsync.

Det här exemplet hämtar en modul till ett Module objekt, uppdaterar module LastActivityTime egenskapen och uppdaterar sedan modulen i IoT Hub med hjälp av UpdateModuleAsync.

// Retrieve the module
var module = await registryManager.GetModuleAsync("myDeviceId","myModuleId");

// Update the module object
module.LastActivityTime = DateTime.Now;

// Apply the patch to update the device twin tags section
try
{
   await registryManager.UpdateModuleAsync(module);
}
catch (Exception e)
{
   console.WriteLine("Module update failed.", e.Message);
}

Api för andra moduler

GetModulesOnDeviceAsync – Hämtar modulidentiteterna på en enhet
RemoveModuleAsync – Tar bort en tidigare registrerad modul från en enhet

SDK-tjänstexempel

Azure IoT SDK för .NET innehåller ett fungerande exempel på en tjänstapp som hanterar uppgifter för modulidentitetstvillingar. Mer information finns i Registry Manager E2E-tester.

Python version 3.7 eller senare rekommenderas. Se till att använda en 32-bitars eller 64-bitars installation beroende på vad som krävs för din konfiguration. Se till att du lägger till Python i den plattformsspecifika miljövariabeln när du uppmanas att göra det under installationen.

Översikt

Den här artikeln beskriver hur du använder Azure IoT SDK för Python för att skapa programkod för enhets- och serverdelstjänst för modulidentitetstvillingar.

Installera paket

Biblioteket azure-iot-device måste vara installerat för att skapa enhetsprogram.

pip install azure-iot-device

Biblioteket azure-iot-hub måste installeras för att skapa serverdelstjänstprogram.

pip install azure-iot-hub

Msrest-biblioteket används för att fånga HTTPOperationError-undantag.

pip install msrest

Skapa ett enhetsprogram

I det här avsnittet beskrivs hur du använder enhetsprogramkod för att:

Hämta en modulidentitetstvilling och granska rapporterade egenskaper
Uppdatera rapporterade egenskaper för modulidentitetstvilling
Skapa en modulidentitetstvilling önskad egenskapsuppdateringsanropshanterare

Viktigt!

Importinstruktioner

Lägg till den här import instruktionen för att använda enhetsbiblioteket.

# import the device client library
import asyncio
from azure.iot.device.aio import IoTHubDeviceClient

Ansluta till en enhet

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

Så här ansluter du ett program till en enhet:

Anropa create_from_connection_string för att lägga till modulidentiteten anslutningssträng
Anropa connect för att ansluta enhetsklienten till en Azure IoT-hubb

# import the device client library
import asyncio
from azure.iot.device.aio import IoTHubDeviceClient

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

# connect the application to the device
await device_client.connect()

Kommentar

Python stöder inte anslutning av en enhetsapp till en IoT Hub-modulidentitetstvilling med hjälp av ett certifikat.

Hämta en modulidentitetstvilling och granska egenskaper

Anropa get_twin för att hämta modulidentitetstvillingen från Azure IoT Hub-tjänsten. Tvillinginformationen placeras i en variabel som kan undersökas.

Det här exemplet hämtar enhetstvillingen print och använder kommandot för att visa enhetstvillingen i JSON-format.

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

Uppdatera rapporterade egenskaper för modulidentitetstvilling

Du kan använda en korrigering för att uppdatera rapporterade egenskaper för modulidentitetstvillingar i JSON-format.

Så här tillämpar du en korrigering för att uppdatera rapporterade egenskaper:

Tilldela en JSON-korrigering för rapporterad egenskap till en variabel.
Anropa patch_twin_reported_properties för att tillämpa JSON-korrigeringen på rapporterade egenskaper.

Till exempel:

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

Skapa en modulidentitetstvilling önskad egenskapsuppdateringsanropshanterare

Anropa on_twin_desired_properties_patch_received för att skapa en hanteringsfunktion eller coroutine som anropas när en modulidentitetstvilling önskad egenskapskorrigering tas emot. Hanteraren tar ett argument, vilket är tvillingkorrigeringen i form av ett JSON-ordlisteobjekt.

I det här exemplet konfigureras en korrigeringshanterare för önskade egenskaper med namnet twin_patch_handler.

Till exempel:

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

Tar twin_patch_handler emot och skriver ut önskade JSON-egenskapsuppdateringar.

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

SDK-enhetsexempel

Azure IoT SDK för Python innehåller ett fungerande exempel på enhetsappar som hanterar uppgifter för modulidentitetstvillingar:

get_twin – Anslut till en enhet och hämta tvillinginformation.
update_twin_reported_properties – Uppdatera rapporterade egenskaper för tvilling.
receive_twin_desired_properties – Ta emot och uppdatera önskade egenskaper.

Skapa ett serverdelsprogram

I det här avsnittet beskrivs hur du skapar ett serverdelsprogram för att hämta och uppdatera önskade egenskaper för modulidentitetstvillingar.

Klassen IoTHubRegistryManager exponerar alla metoder som krävs för att skapa ett serverdelsprogram för att interagera med modulidentitetstvillingar från tjänsten.

Tjänstimportinstruktioner

Lägg till den här import instruktionen om du vill använda tjänstbiblioteket.

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

Ansluta till IoT Hub

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

Princip för delad åtkomst
Microsoft Entra

Viktigt!

Ansluta med en princip för delad åtkomst

Anslut till IoT Hub med hjälp av from_connection_string.

Metoden update_module_twin som används i det här avsnittet kräver behörigheten för principen för delad åtkomst i Service Connect för att lägga till önskade egenskaper i en modul. Som parameter till from_connection_stringanger du en princip för delad åtkomst anslutningssträng som innehåller Service Connect-behörighet. Mer information om principer för delad åtkomst finns i Kontrollera åtkomst till IoT Hub med signaturer för delad åtkomst.

Till exempel:

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

Ansluta med Microsoft Entra

En översikt över Python SDK-autentisering finns i Autentisera Python-appar till Azure-tjänster med hjälp av Azure SDK för Python

Konfigurera Microsoft Entra-app

Klienthemlighet
Certifikat
Federerade identitetsautentiseringsuppgifter

Mer information om hur du konfigurerar en Microsoft Entra-app finns i Snabbstart: Registrera ett program med Microsofts identitetsplattform.

Autentisera med defaultAzureCredential

Det enklaste sättet att använda Microsoft Entra för att autentisera ett serverdelsprogram är att använda DefaultAzureCredential, men vi rekommenderar att du använder en annan metod i en produktionsmiljö, inklusive en specifik TokenCredential eller avskalad ChainedTokenCredential. För enkelhetens skull beskriver det här avsnittet autentisering med hjälp av DefaultAzureCredential och klienthemlighet. Mer information om fördelar och nackdelar med att använda finns DefaultAzureCredentiali Kedjor för autentiseringsuppgifter i Azure Identity-klientbiblioteket för Python.

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

Microsoft Entra kräver det här importpaketet och motsvarande import instruktion:

pip install azure-identity

from azure.identity import DefaultAzureCredential

I det här exemplet har Microsoft Entra-appregistreringsklienthemlighet, klient-ID och klient-ID lagts till i miljövariabler. Dessa miljövariabler används av DefaultAzureCredential för att autentisera programmet. Resultatet av en lyckad Microsoft Entra-autentisering är en säkerhetstokenautentiseringsuppgift som skickas till en IoT Hub-anslutningsmetod.

from azure.identity import DefaultAzureCredential
credential = DefaultAzureCredential()

Den resulterande AccessToken kan sedan skickas till from_token_credential för att ansluta till IoT Hub för alla SDK-klienter som accepterar Microsoft Entra-autentiseringsuppgifter:

IoTHubRegistryManager för att skapa en tjänstanslutning till IoT Hub med hjälp av en Entra-tokenautentisering.
IoTHubJobManager
DigitalTwinClient
IoTHubHttpRuntimeManager
IoTHubConfigurationManager

from_token_credential kräver två parametrar:

Url:en för Azure-tjänsten – Azure-tjänst-URL:en ska vara i formatet {Your Entra domain URL}.azure-devices.net utan prefix https:// . Exempel: MyAzureDomain.azure-devices.net
Azure-token för autentiseringsuppgifter

I det här exemplet hämtas Azure-autentiseringsuppgifterna med hjälp av DefaultAzureCredential. Azure-tjänstens URL och autentiseringsuppgifter tillhandahålls sedan för att IoTHubRegistryManager.from_token_credential 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

Arbetsexempel för Microsoft Entra-tjänstautentisering finns i Microsoft Authentication Library (MSAL) för Python.

Hämta och uppdatera önskade egenskaper för modulidentitetstvillingar

Du kan uppdatera önskade egenskaper från ett serverdelsprogram med hjälp av update_module_twin.

Så här hämtar och uppdaterar du önskade egenskaper för modulidentitetstvilling:

Anropa get_module_twin för att hämta den aktuella versionen av modulidentitetstvillingen.
Använd klassen Twin för att lägga till önskade egenskaper i JSON-format.
Anropa update_module_twin för att tillämpa korrigeringen på enhetstvillingen. Du kan också använda replace_module_twin för att ersätta önskade egenskaper och taggar för en modulidentitetstvilling.

I det här exemplet uppdateras den telemetryInterval önskade egenskapen till 122.

try:
    module_twin = iothub_registry_manager.get_module_twin(DEVICE_ID, MODULE_ID)
    print ( "" )
    print ( "Module identity twin properties before update:" )
    print ( "{0}".format(module_twin.properties) )

    # Update twin
    twin_patch = Twin()
    twin_patch.properties = TwinProperties(desired={"telemetryInterval": 122})
    updated_module_twin = iothub_registry_manager.update_module_twin(
        DEVICE_ID, MODULE_ID, twin_patch, module_twin.etag
    )
    print ( "" )
    print ( "Module identity twin properties after update     :" )
    print ( "{0}".format(updated_module_twin.properties) )

except Exception as ex:
    print ( "Unexpected error {0}".format(ex) )
except KeyboardInterrupt:
    print ( "IoTHubRegistryManager sample stopped" )

SDK-tjänstexempel

Azure IoT SDK för Python innehåller ett fungerande exempel på en tjänstapp som hanterar uppgifter för enhetsidentitetsmodultvillingar. Mer information finns i Testa IoTHub Registry Manager.

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

Översikt

Den här artikeln beskriver hur du använder Azure IoT SDK för Node.js för att skapa programkod för enhets- och serverdelstjänst för modulidentitetstvillingar.

Skapa ett enhetsprogram

I det här avsnittet beskrivs hur du använder paketet azure-iot-device i Azure IoT SDK för Node.js för att skapa ett enhetsprogram för att:

Hämta en modulidentitetstvilling och granska rapporterade egenskaper
Uppdatera modulidentitetens rapporterade tvillingegenskaper
Få meddelande om önskade egenskapsändringar för modulidentitetstvillingar

Paketet azure-iot-device innehåller objekt som samverkar med IoT-enheter. Klassen Twin innehåller tvillingspecifika objekt. I det här avsnittet beskrivs klasskod som används för att läsa och skriva enhetsmodulens Client identitetstvillingdata.

Installera SDK-paket

Kör det här kommandot för att installera azure-iot-device SDK på utvecklingsdatorn:

npm install azure-iot-device --save

Ansluta en enhet till IoT Hub

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

Nyckel för delad åtkomst
X.509-certifikat

Viktigt!

Autentisera med hjälp av en nyckel för delad åtkomst

Välj ett transportprotokoll

Objektet Client stöder följande protokoll:

Amqp
Http – När du använder Httpsöker instansen Client efter meddelanden från IoT Hub sällan (minst var 25:e minut).
Mqtt
MqttWs
AmqpWs

Installera nödvändiga transportprotokoll på utvecklingsdatorn.

Det här kommandot installerar till exempel protokollet Amqp :

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

Mer information om skillnaderna mellan MQTT-, AMQP- och HTTPS-stöd finns i Vägledning för kommunikation från moln till enhet och Välj ett protokoll för enhetskommunikation.

Skapa ett klientobjekt

Skapa ett Client objekt med det installerade paketet.

Till exempel:

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

Skapa ett protokollobjekt

Skapa ett Protocol objekt med ett installerat transportpaket.

I det här exemplet tilldelas AMQP-protokollet:

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

Lägg till anslutningssträng- och transportprotokollet för enheten

Anropa fromConnectionString för att ange parametrar för enhetsanslutning:

connStr – IoT Hub-identitetsmodulen anslutningssträng.
transportCtor – transportprotokollet.

I det här exemplet används transportprotokollet Amqp :

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

Öppna anslutningen till IoT Hub

Använd den öppna metoden för att öppna en anslutning mellan en IoT-enhet och IoT Hub.

Till exempel:

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

Autentisera med ett X.509-certifikat

X.509-certifikatet är kopplat till anslutningstransporten från enhet till IoT Hub.

Så här konfigurerar du en enhet-till-IoT Hub-anslutning med hjälp av ett X.509-certifikat:

Anropa fromConnectionString för att lägga till enheten eller identitetsmodulen anslutningssträng och transporttypen till Client objektet. Lägg till x509=true i anslutningssträng för att ange att ett certifikat läggs till i DeviceClientOptions. Till exempel:
- 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
Konfigurera en JSON-variabel med certifikatinformation och skicka den till DeviceClientOptions.
Anropa setOptions för att lägga till ett X.509-certifikat och en nyckel (och eventuellt lösenfras) till klienttransporten.
Anropa öppna för att öppna anslutningen från enheten till IoT Hub.

Det här exemplet visar information om certifikatkonfiguration i en JSON-variabel. Certifieringskonfigurationen clientOptions skickas till setOptionsoch anslutningen öppnas med .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);

Mer information om certifikatautentisering finns i:

Kodexempel

Ett fungerande exempel på X.509-enhetscertifikatautentisering finns i Enkel exempelenhet X.509.

Hämta en modulidentitetstvilling och granska rapporterade egenskaper

Anropa getTwin för att hämta aktuell information om modulidentitetstvillingar till ett Tvillingobjekt .

Enhetskoden kan sedan komma åt egenskaperna för modulidentitetstvillingar.

Till exempel:

// Retrieve the current module identity twin
client.getTwin(function(err, twin))
if (err)
    console.error('could not get twin');

// Display the current properties
console.log('twin contents:');
console.log(twin.properties);

Uppdatera rapporterade egenskaper för modulidentitetstvilling

Använd uppdatering för att uppdatera enhetsrapporterade egenskaper. Inkludera en JSON-formaterad korrigering som den första parametern och återanropsmetoden för funktionskörningsstatus som den andra parametern till metoden.

I det här exemplet lagras en JSON-formaterad modulidentitetstvilling-korrigering i variabeln patch . Korrigeringen innehåller ett uppdateringsvärde för modulidentitetstvillingar connectivity på cellular. Korrigerings- och felhanteraren skickas till update metoden. Om det uppstår ett fel visas ett konsolfelmeddelande.

// Create a patch to send to IoT Hub
var patch = {
  updateTime: new Date().toString(),
  firmwareVersion:'1.2.1',
  weather:{
    temperature: 72,
    humidity: 17
  }
};

// Apply the patch
twin.properties.reported.update(patch, function(err)
  {
    if (err)
      {
        console.error('could not update twin');
      } 
    else
      {
        console.log('twin state reported');
        process.exit();
      }
  });

Få meddelande om önskade egenskapsändringar för modulidentitetstvillingar

Skapa en modulidentitetstvilling som vill uppdatera händelselyssnare för egenskapen som körs när en önskad egenskap ändras genom att skicka namnet på motringningshanterarens metod till twin.on.

Den önskade egenskapshändelselyssnaren kan ha följande formulär:

Ta emot alla korrigeringar med en enskild händelsehanterare
Ta emot en händelse om något ändras under en egenskapsgruppering
Ta emot en händelse för en enskild egenskapsändring

Ta emot alla korrigeringar med en enskild händelsehanterare

Du kan skapa en lyssnare för att få önskad egenskapsändring.

Den här exempelkoden matar 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

Du kan skapa en lyssnare för att ta emot en händelse om något under en egenskapsgruppering ändras.

Till exempel:

Egenskaperna minTemperature och maxTemperature finns under en egenskapsgrupp med namnet properties.desired.climate changes.
Ett serverdelstjänstprogram tillämpar den här korrigeringen för att uppdatera minTemperature och maxTemperature önskade egenskaper:
```
const twinPatch1 = {
properties: {
   desired: {
    climate: { minTemperature: 68, maxTemperature: 76, },
    },
  },
 };
```

Den här koden konfigurerar en önskad händelselyssnare för egenskapsändring som utlöser eventuella ändringar i properties.desired.climate egenskapsgruppering. Om det finns en önskad egenskapsändring i den här gruppen visas meddelanden om minsta och högsta temperaturändring i 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 egenskapsändring

Du kan konfigurera en lyssnare för en enda egenskapsändring. I det här exemplet körs koden för den här händelsen endast om det fanOn booleska värdet är en del av korrigeringen. Koden matar ut det nya önskade fanOn tillståndet när tjänsten uppdaterar det.

Ett serverdelsprogram tillämpar den här önskade egenskapskorrigeringen:

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

Lyssnaren utlöses endast när egenskapen fanOn ändras:

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

Fullständigt exempel

Det här exemplet kapslar in principerna i det här avsnittet, inklusive återanropsfunktionens kapsling på flera nivåer.

var Client = require('azure-iot-device').Client;
var Protocol = require('azure-iot-device-amqp').Amqp;
// Copy/paste your module connection string here.
var connectionString = 'HostName=xxx.azure-devices.net;DeviceId=myFirstDevice2;ModuleId=myFirstModule2;SharedAccessKey=xxxxxxxxxxxxxxxxxx';
// Create a client using the Amqp protocol.
var client = Client.fromConnectionString(connectionString, Protocol);
client.on('error', function (err) {
  console.error(err.message);
});
// connect to the hub
client.open(function(err) {
  if (err) {
    console.error('error connecting to hub: ' + err);
    process.exit(1);
  }
  console.log('client opened');
// Create device Twin
  client.getTwin(function(err, twin) {
    if (err) {
      console.error('error getting twin: ' + err);
      process.exit(1);
    }
    // Output the current properties
    console.log('twin contents:');
    console.log(twin.properties);
    // Add a handler for desired property changes
    twin.on('properties.desired', function(delta) {
        console.log('new desired properties received:');
        console.log(JSON.stringify(delta));
    });
    // create a patch to send to the hub
    var patch = {
      updateTime: new Date().toString(),
      firmwareVersion:'1.2.1',
      weather:{
        temperature: 75,
        humidity: 20
      }
    };
    // send the patch
    twin.properties.reported.update(patch, function(err) {
      if (err) throw err;
      console.log('twin state reported');
    });

  });
});

Exempel på enhets-SDK

Azure IoT SDK för Node.js innehåller arbetsexempel på enhetsappar som hanterar uppgifter för modulidentitetstvillingar. Mer information finns i:

Skapa ett serverdelsprogram

I det här avsnittet beskrivs hur du skapar ett serverdelsprogram som hämtar en modulidentitetstvilling och uppdaterar önskade egenskaper.

Installera tjänst-SDK-paketet

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

npm install azure-iothub --save

Skapa ett registerobjekt

Klassen Registry exponerar alla metoder som krävs för att interagera med modulidentitetstvillingar från ett serverdelsprogram.

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

Ansluta till IoT Hub

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

Princip för delad åtkomst
Microsoft Entra

Viktigt!

Ansluta med en princip för delad åtkomst

Använd fromConnectionString för att ansluta till IoT Hub.

Metoden update som används i det här avsnittet kräver behörigheten för principen för delad åtkomst i Service Connect för att lägga till önskade egenskaper i en modul. Som parameter till fromConnectionStringanger du en princip för delad åtkomst anslutningssträng som innehåller Service Connect-behörighet. Mer information om principer för delad åtkomst finns i Kontrollera åtkomst till IoT Hub med signaturer för delad åtkomst.

let connectionString = '{IoT hub shared access policy connection string}';
let registry = Registry.fromConnectionString(serviceConnectionString);

Ansluta med Microsoft Entra

En översikt över Node.js SDK-autentisering finns i:

Konfigurera Microsoft Entra-app

Klienthemlighet
Certifikat
Federerade identitetsautentiseringsuppgifter

Mer information om hur du konfigurerar en Microsoft Entra-app finns i Snabbstart: Registrera ett program med Microsofts identitetsplattform.

Autentisera med defaultAzureCredential

Det enklaste sättet att använda Microsoft Entra för att autentisera ett serverdelsprogram är att använda DefaultAzureCredential, men vi rekommenderar att du använder en annan metod i en produktionsmiljö, inklusive en specifik TokenCredential eller avskalad ChainedTokenCredential. För enkelhetens skull beskriver det här avsnittet autentisering med hjälp av DefaultAzureCredential och klienthemlighet. Mer information om fördelar och nackdelar med att använda finns DefaultAzureCredentiali Kedjor för autentiseringsuppgifter i Azure Identity-klientbiblioteket för JavaScript

Microsoft Entra kräver det här paketet:

npm install --save @azure/identity

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

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

Den resulterande token för autentiseringsuppgifter kan sedan skickas till frånTokenCredential för att ansluta till IoT Hub för alla SDK-klienter som accepterar Microsoft Entra-autentiseringsuppgifter:

fromTokenCredential kräver två parametrar:

Url:en för Azure-tjänsten – Azure-tjänst-URL:en ska vara i formatet {Your Entra domain URL}.azure-devices.net utan prefix https:// . Exempel: MyAzureDomain.azure-devices.net
Azure-token för autentiseringsuppgifter

I det här exemplet hämtas Azure-autentiseringsuppgifterna med hjälp av DefaultAzureCredential. Url:en och autentiseringsuppgifterna för Azure-domänen skickas sedan till för att Registry.fromTokenCredential 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

Arbetsexempel för Microsoft Entra-tjänstautentisering finns i Azure-identitetsexempel.

Hämta en modulidentitetstvilling och uppdatera önskade egenskaper

Du kan skapa en korrigering som innehåller önskade egenskapsuppdateringar för en modulidentitetstvilling.

Så här uppdaterar du en modulidentitetstvilling:

Anropa getModuleTwin för att hämta enhetstvillingobjektet.
Formatera en korrigering som innehåller modulens identitetstvillinguppdatering. Korrigeringen är formaterad i JSON enligt beskrivningen i Twin-klassen. En serverdelstjänstkorrigering innehåller önskade egenskapsuppdateringar. Mer information om korrigeringsformat finns i Format för taggar och egenskaper.
Anropa uppdateringen för att uppdatera modulidentitetstvillingen med korrigeringen.

I det här exemplet hämtas modulidentitetstvillingen för myDeviceId och myModuleId. Sedan tillämpas en korrigering på tvillingarna som innehåller climate information.

// Insert your device ID and moduleId here.
var deviceId = 'myFirstDevice2';
var moduleId = 'myFirstModule2';

// Retrieve the current module identity twin
registry.getModuleTwin(deviceId, moduleId, function (err, twin) {
  console.log('getModuleTwin returned ' + (err ? err : 'success'));
  if (err) {
    console.log(err);
  } else {
    console.log('success');
    console.log('Current twin:' + JSON.stringify(twin))

    // Format a desired property patch
    const twinPatch1 = {
      properties: {
        desired: {
          climate: { minTemperature: 69, maxTemperature: 77, },
        },
      },
    };

    // Send the desired property patch to IoT Hub
    twin.update(twinPatch1, function(err) {
    if (err) throw err;
    console.log('twin state reported');
    });
  }
});

Service SDK-exempel

Azure IoT SDK för Node.js innehåller arbetsexempel på tjänstappar som hanterar modulidentitetstvillinguppgifter. Mer information finns i:

Dela via

Kom igång med IoT Hub-modulidentiteter och modulidentitetstvillingar

Förutsättningar

Översikt

Skapa ett enhetsprogram

Obligatoriskt NuGet-paket för enhet

Ansluta till en enhet

Hämta en modulidentitetstvilling och granska egenskaper

Uppdatera rapporterade egenskaper för modulidentitetstvilling

Skapa en önskad egenskapsuppdateringsanropshanterare

Exempel på SDK-modul

Skapa ett serverdelsprogram

Obligatoriskt NuGet-tjänstpaket

Ansluta till IoT Hub

Ansluta med en princip för delad åtkomst

Ansluta med Microsoft Entra

Konfigurera Microsoft Entra-app

Autentisera med defaultAzureCredential

Kodexempel

Läsa och uppdatera modulidentitetsfält

Api för andra moduler

SDK-tjänstexempel

Översikt

Installera paket

Skapa ett enhetsprogram

Importinstruktioner

Ansluta till en enhet

Hämta en modulidentitetstvilling och granska egenskaper

Uppdatera rapporterade egenskaper för modulidentitetstvilling

Skapa en modulidentitetstvilling önskad egenskapsuppdateringsanropshanterare

SDK-enhetsexempel

Skapa ett serverdelsprogram

Tjänstimportinstruktioner

Ansluta till IoT Hub

Ansluta med en princip för delad åtkomst

Ansluta med Microsoft Entra

Konfigurera Microsoft Entra-app

Autentisera med defaultAzureCredential

Kodexempel

Hämta och uppdatera önskade egenskaper för modulidentitetstvillingar

SDK-tjänstexempel

Översikt

Skapa ett enhetsprogram

Installera SDK-paket

Ansluta en enhet till IoT Hub

Autentisera med hjälp av en nyckel för delad åtkomst

Välj ett transportprotokoll

Skapa ett klientobjekt

Skapa ett protokollobjekt

Lägg till anslutningssträng- och transportprotokollet för enheten

Öppna anslutningen till IoT Hub

Autentisera med ett X.509-certifikat

Kodexempel

Hämta en modulidentitetstvilling och granska rapporterade egenskaper

Uppdatera rapporterade egenskaper för modulidentitetstvilling

Få meddelande om önskade egenskapsändringar för modulidentitetstvillingar

Ta emot alla korrigeringar med en enskild händelsehanterare

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

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

Fullständigt exempel

Exempel på enhets-SDK

Skapa ett serverdelsprogram

Installera tjänst-SDK-paketet

Skapa ett registerobjekt

Ansluta till IoT Hub

Ansluta med en princip för delad åtkomst

Ansluta med Microsoft Entra

Konfigurera Microsoft Entra-app

Autentisera med defaultAzureCredential

Kodexempel

Hämta en modulidentitetstvilling och uppdatera önskade egenskaper

Service SDK-exempel

Feedback

Ytterligare resurser