Začínáme s identitami modulů ioT Hubu a dvojčaty identit modulů

Článek
01/03/2025

Identity modulů a dvojčata identit modulů se podobají identitám zařízení a dvojčatům zařízení ve službě Azure IoT Hub, ale poskytují jemně členitost. Zatímco identity zařízení a dvojčata zařízení azure IoT Hub umožňují back-endové aplikaci nakonfigurovat zařízení a poskytnout přehled o podmínkách zařízení, identita modulu a dvojče identit modulu poskytují tyto funkce pro jednotlivé komponenty zařízení. Na zařízeních s více komponentami, jako jsou zařízení s operačním systémem nebo zařízení firmwaru, umožňují identity modulů a dvojčata identit modulů pro každou komponentu izolovanou konfiguraci a podmínky. Další informace najdete v tématu Principy dvojčat modulů Azure IoT Hubu.

Poznámka:

Funkce popsané v tomto článku jsou k dispozici pouze na úrovni Standard služby IoT Hub. Další informace o úrovních Služby IoT Hub úrovně Basic a Standard/Free najdete v tématu Volba správné úrovně IoT Hubu pro vaše řešení.

V tomto článku se dozvíte, jak vyvíjet dva typy aplikací:

Aplikace zařízení, které zobrazují a aktualizují vlastnosti dvojčete identity modulu, a zpracovávají požadavky na aktualizaci požadovaných vlastností.
Aplikace služeb, které mohou číst a nastavovat požadované vlastnosti identity modulu.

Poznámka:

Tento článek je určený k doplnění ukázek sad SDK Azure IoT, na které odkazuje tento článek. Nástroje sady SDK můžete použít k sestavení zařízení i back-endových aplikací.

Požadavky

Služba IoT Hub
Zařízení IoT Hubu
Identita modulu zařízení ioT Hubu
Pokud vaše aplikace používá protokol MQTT, ujistěte se, že je v bráně firewall otevřený port 8883 . Protokol MQTT komunikuje přes port 8883. Tento port může být blokovaný v některých podnikových a vzdělávacích síťových prostředích. Další informace a způsoby řešení tohoto problému najdete v tématu Připojení ke službě IoT Hub (MQTT).

Vyžaduje Visual Studio.

Přehled

Tento článek popisuje, jak pomocí sady Azure IoT SDK pro .NET vytvořit kód aplikace zařízení a back-endové služby pro dvojčata identit modulů.

Vytvoření aplikace zařízení

Tato část popisuje, jak používat kód aplikace zařízení k:

Načtení dvojčete identity modulu a prozkoumání ohlášených vlastností
Aktualizace ohlášených vlastností dvojčete identity modulu
Vytvoření obslužné rutiny zpětného volání aktualizace požadované vlastnosti modulu

Důležité

Tento článek obsahuje postup připojení zařízení pomocí sdíleného přístupového podpisu, označovaného také jako ověřování symetrického klíče. Tato metoda ověřování je vhodná pro testování a vyhodnocení, ale ověřování zařízení pomocí certifikátů X.509 je bezpečnější přístup. Další informace najdete v tématu Zabezpečení osvědčených postupů > zabezpečení připojení.

Požadovaný balíček NuGet zařízení

Klientské aplikace zařízení napsané v jazyce C# vyžadují balíček NuGet Microsoft.Azure.Devices.Client .

Přidejte tyto using příkazy pro použití knihovny zařízení.

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

Připojení k zařízení

Třída ModuleClient zveřejňuje všechny metody potřebné k interakci s dvojčaty identit modulů ze zařízení.

Připojte se k zařízení pomocí metody CreateFromConnectionString s identitou modulu připojovací řetězec.

Volání CreateFromConnectionString bez parametru přenosu se připojuje pomocí výchozího přenosu AMQP.

Tento příklad se připojí k zařízení pomocí výchozího přenosu AMQP.

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

_moduleClient = ModuleClient.CreateFromConnectionString(ModuleConnectionString, null);

Poznámka:

C#/.NET nepodporuje připojení aplikace zařízení k dvojčeti identit modulu Služby IoT Hub pomocí certifikátu.

Načtení dvojčete identity modulu a prozkoumání vlastností

Volání GetTwinAsync k načtení vlastností aktuálního dvojčete identity modulu do objektu Twin .

Tento příklad načte a zobrazí vlastnosti dvojčete identity modulu ve formátu JSON.

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

Aktualizace ohlášených vlastností dvojčete identity modulu

Aktualizace ohlášené vlastnosti dvojčete:

Vytvoření objektu TwinCollection pro aktualizaci ohlášené vlastnosti
Aktualizace jedné nebo více ohlášených vlastností v rámci objektu TwinCollection
Použití UpdateReportedPropertiesAsync k nabízení změn ohlášených vlastností do služby IoT Hub

Příklad:

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

Vytvoření obslužné rutiny zpětného volání aktualizace požadované vlastnosti

Předejte název metody zpětného volání setDesiredPropertyUpdateCallbackAsync pro vytvoření obslužné rutiny zpětného volání aktualizace požadované vlastnosti, která se spustí při změně požadované vlastnosti ve dvojčeti identity modulu.

Toto volání například nastaví systém tak, aby upozorňovat metodu pojmenovanou OnDesiredPropertyChangedAsync při každé změně vlastnosti požadovaného modulu.

await _moduleClient.SetDesiredPropertyUpdateCallbackAsync(OnDesiredPropertyChangedAsync, null);

Vlastnosti dvojčete identity modulu se předávají metodě zpětného volání jako TwinCollection a lze je prozkoumat jako KeyValuePair struktury.

Tento příklad obdrží aktualizace požadované vlastnosti jako a TwinCollectionpak prochází smyčky a vytiskne KeyValuePair aktualizace kolekce. Po procházení KeyValuePair kolekce volání UpdateReportedPropertiesAsync kódu aktualizovat ohlášenou DateTimeLastDesiredPropertyChangeReceived vlastnost tak, aby byl čas poslední aktualizace aktuální.

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

Ukázka modulu SADY SDK

Sada Azure IoT SDK pro .NET poskytuje funkční ukázky aplikací zařízení, které zpracovávají úlohy dvojčete identit modulu. Další informace naleznete v tématu:

Vytvoření back-endové aplikace

Tato část popisuje, jak číst a aktualizovat pole identit modulů.

Třída RegistryManager zveřejňuje všechny metody potřebné k vytvoření back-endové aplikace pro interakci s dvojčaty identit modulu ze služby.

Požadovaný balíček NuGet služby

Aplikace back-endových služeb vyžadují balíček NuGet Microsoft.Azure.Devices .

Přidejte tyto using příkazy pro použití knihovny služeb.

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

Připojení ke službě IoT Hub

Back-endovou službu můžete ke službě IoT Hub připojit pomocí následujících metod:

Zásady sdíleného přístupu
Microsoft Entra

Důležité

Tento článek obsahuje postup připojení ke službě pomocí sdíleného přístupového podpisu. Tato metoda ověřování je vhodná pro testování a vyhodnocení, ale ověřování ve službě pomocí MICROSOFT Entra ID nebo spravovaných identit je bezpečnější přístup. Další informace najdete v tématu Osvědčené postupy > zabezpečení cloudu.

Připojení pomocí zásad sdíleného přístupu

Připojte back-endovou aplikaci ke službě IoT Hub pomocí createFromConnectionString.

Metoda použitá UpdateModuleAsync v této části vyžaduje , aby zásady sdíleného přístupu služby Service Connect přidaly požadované vlastnosti do modulu. Jako parametr CreateFromConnectionStringzadejte zásady sdíleného přístupu připojovací řetězec, které zahrnují oprávnění Service Connect. Další informace o zásadách sdíleného přístupu najdete v tématu Řízení přístupu ke službě IoT Hub pomocí sdílených přístupových podpisů.

Příklad:

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

Připojení pomocí Microsoft Entra

Back-endová aplikace, která používá Microsoft Entra, se musí před připojením ke službě IoT Hub úspěšně ověřit a získat přihlašovací údaje tokenu zabezpečení. Tento token se předá metodě připojení ioT Hubu. Obecné informace o nastavení a používání Microsoft Entra pro IoT Hub naleznete v tématu Řízení přístupu ke službě IoT Hub pomocí Microsoft Entra ID.

Konfigurace aplikace Microsoft Entra

Musíte nastavit aplikaci Microsoft Entra, která je nakonfigurovaná pro vaše upřednostňované přihlašovací údaje ověřování. Aplikace obsahuje parametry, jako je tajný klíč klienta, který používá back-endová aplikace k ověření. Dostupné konfigurace ověřování aplikací:

Tajný klíč klienta
Certifikát
Přihlašovací údaje federované identity

Aplikace Microsoft Entra mohou v závislosti na provedených operacích vyžadovat určitá oprávnění role. K povolení přístupu ke čtení a zápisu k zařízení a dvojčatům modulů služby IoT Hub je například potřeba přispěvatel dvojčete služby IoT Hub. Další informace najdete v tématu Správa přístupu ke službě IoT Hub pomocí přiřazení role Azure RBAC.

Další informace o nastavení aplikace Microsoft Entra najdete v tématu Rychlý start: Registrace aplikace na platformě Microsoft Identity Platform.

Ověřování pomocí DefaultAzureCredential

Nejjednodušší způsob, jak použít Microsoft Entra k ověření back-endové aplikace, je použít DefaultAzureCredential, ale doporučuje se použít jinou metodu v produkčním prostředí, včetně konkrétní TokenCredential nebo pared-down ChainedTokenCredential. Pro zjednodušení popisuje tato část ověřování pomocí DefaultAzureCredential a tajný klíč klienta. Další informace o výhodách a nevýhodách použití naleznete v pokynech k použití DefaultAzureCredentialpro DefaultAzureCredential.

DefaultAzureCredential podporuje různé mechanismy ověřování a určuje odpovídající typ přihlašovacích údajů na základě prostředí, ve které se provádí. Pokusí se použít více typů přihlašovacích údajů v pořadí, dokud nenajde funkční přihlašovací údaje.

Microsoft Entra vyžaduje tyto balíčky NuGet a odpovídající using příkazy:

Azure.Core
Azure.Identity

using Azure.Core;
using Azure.Identity;

V tomto příkladu se do proměnných prostředí přidá tajný klíč klienta registrace aplikace Microsoft Entra, ID klienta a ID tenanta. Tyto proměnné prostředí se používají DefaultAzureCredential k ověření aplikace. Výsledkem úspěšného ověřování Microsoft Entra je přihlašovací údaje tokenu zabezpečení předávané metodě připojení ioT Hubu.

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

Výsledný tokenCredential se pak dá předat metodě připojení ke službě IoT Hub pro libovolného klienta sady SDK, který přijímá přihlašovací údaje Microsoft Entra:

V tomto příkladu TokenCredential se předá objekt ServiceClient.Create připojení ServiceClient k vytvoření objektu připojení ServiceClient .

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

V tomto příkladu TokenCredential se předá k RegistryManager.Create vytvoření objektu RegistryManager .

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

Ukázka kódu

Funkční ukázka ověřování služby Microsoft Entra najdete v ukázce ověřování na základě rolí.

Čtení a aktualizace polí identity modulu

Volání metody GetModuleAsync pro načtení polí dvojčat identit aktuálního modulu do objektu modulu

Třída Module zahrnuje properties oddíly dvojčete identity modulu. Vlastnosti třídy modulu slouží k zobrazení a aktualizaci polí dvojčete identity modulu. Vlastnosti objektu Module můžete použít k aktualizaci více polí před zápisem aktualizací do zařízení pomocí UpdateModuleAsync.

Po provedení aktualizací pole dvojčete identity modulu zavolejte UpdateModuleAsync a zapište Module aktualizace polí objektů zpět do zařízení. Použití try a catch logika spojená s obslužnou rutinou chyby k zachycení nesprávně formátovaných chyb oprav z UpdateModuleAsync.

Tento příklad načte modul do objektu Module , aktualizuje module LastActivityTime vlastnost a pak aktualizuje modul ve službě IoT Hub pomocí 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);
}

Rozhraní API jiného modulu

GetModulesOnDeviceAsync – načte identity modulů na zařízení.
RemoveModuleAsync – Odstraní dříve zaregistrovaný modul ze zařízení.

Ukázka služby SDK

Sada Azure IoT SDK pro .NET poskytuje funkční ukázku aplikace služby, která zpracovává úlohy dvojčete identit modulu. Další informace naleznete v tématu Registry Manager E2E Testy.

Doporučuje se Python verze 3.7 nebo novější . Ujistěte se, že používáte 32bitovou, nebo 64bitovou instalaci podle požadavků vašeho nastavení. Po zobrazení výzvy v průběhu instalace nezapomeňte přidat Python do proměnné prostředí pro konkrétní platformu.

Přehled

Tento článek popisuje, jak pomocí sady Azure IoT SDK pro Python vytvořit kód aplikace zařízení a back-endové služby pro dvojčata identit modulů.

Instalace balíčků

Aby bylo možné vytvářet aplikace zařízení, musí být nainstalovaná knihovna azure-iot-device .

pip install azure-iot-device

Aby bylo možné vytvářet aplikace back-endové služby, musí být nainstalovaná knihovna azure-iot-hub .

pip install azure-iot-hub

Knihovna msrest slouží k zachycení výjimek HTTPOperationError.

pip install msrest

Vytvoření aplikace zařízení

Tato část popisuje, jak používat kód aplikace zařízení k:

Načtení dvojčete identity modulu a prozkoumání ohlášených vlastností
Aktualizace ohlášených vlastností dvojčete identity modulu
Vytvoření požadované vlastnosti dvojčete identity modulu – obslužná rutina zpětného volání

Důležité

Příkazy importu

Přidejte tento import příkaz pro použití knihovny zařízení.

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

Připojení k zařízení

Třída IoTHubModuleClient obsahuje metody, které lze použít k práci s dvojčaty identit modulu.

Připojení aplikace k zařízení:

Volání create_from_connection_string pro přidání identity modulu připojovací řetězec
Volání připojení pro připojení klienta zařízení k centru Azure IoT

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

Poznámka:

Python nepodporuje připojení aplikace zařízení k dvojčeti identit modulu služby IoT Hub pomocí certifikátu.

Načtení dvojčete identity modulu a prozkoumání vlastností

Voláním get_twin načtěte dvojče identity modulu ze služby Azure IoT Hub. Informace o dvojčeti se umístí do proměnné, kterou je možné prozkoumat.

Tento příklad načte dvojče zařízení a pomocí print příkazu zobrazí dvojče zařízení ve formátu JSON.

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

Aktualizace ohlášených vlastností dvojčete identity modulu

Opravu můžete použít k aktualizaci ohlášených vlastností dvojčete identity modulu ve formátu JSON.

Použití opravy pro aktualizaci ohlášených vlastností:

Přiřaďte k proměnné opravu JSON ohlášené vlastnosti.
Volání patch_twin_reported_properties , aby se oprava JSON použila na ohlášené vlastnosti.

Příklad:

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

Vytvoření požadované vlastnosti dvojčete identity modulu – obslužná rutina zpětného volání

Volání on_twin_desired_properties_patch_received k vytvoření funkce obslužné rutiny nebo korutiny, která se volá při přijetí opravy požadovaných vlastností dvojčete identity modulu. Obslužná rutina přebírá jeden argument, což je oprava dvojčete ve formě objektu slovníku JSON.

Tento příklad nastaví obslužnou rutinu opravy požadovaných vlastností s názvem twin_patch_handler.

Příklad:

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

Přijme twin_patch_handler a vytiskne aktualizace požadované vlastnosti JSON.

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

Ukázky zařízení sady SDK

Sada Azure IoT SDK pro Python poskytuje funkční ukázku aplikací zařízení, které zpracovávají úlohy dvojčat identit modulu:

get_twin – Připojte se k zařízení a načtěte informace o dvojčeti.
update_twin_reported_properties – Aktualizace ohlášených vlastností dvojčete
receive_twin_desired_properties – Příjem a aktualizace požadovaných vlastností

Vytvoření back-endové aplikace

Tato část popisuje, jak vytvořit back-endovou aplikaci pro načtení a aktualizaci požadovaných vlastností dvojčete identity modulu.

Třída IoTHubRegistryManager zveřejňuje všechny metody potřebné k vytvoření back-endové aplikace pro interakci s dvojčaty identit modulů ze služby.

Příkazy importu služby

Přidejte tento import příkaz pro použití knihovny služeb.

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

Připojení ke službě IoT Hub

Back-endovou službu můžete ke službě IoT Hub připojit pomocí následujících metod:

Zásady sdíleného přístupu
Microsoft Entra

Důležité

Připojení pomocí zásad sdíleného přístupu

Připojte se ke službě IoT Hub pomocí from_connection_string.

Metoda použitá update_module_twin v této části vyžaduje , aby zásady sdíleného přístupu služby Service Connect přidaly požadované vlastnosti do modulu. Jako parametr from_connection_stringzadejte zásady sdíleného přístupu připojovací řetězec, které zahrnují oprávnění Service Connect. Další informace o zásadách sdíleného přístupu najdete v tématu Řízení přístupu ke službě IoT Hub pomocí sdílených přístupových podpisů.

Příklad:

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

Připojení pomocí Microsoft Entra

Přehled ověřování sady Python SDK najdete v tématu Ověřování aplikací Pythonu ve službách Azure pomocí sady Azure SDK pro Python.

Konfigurace aplikace Microsoft Entra

Tajný klíč klienta
Certifikát
Přihlašovací údaje federované identity

Další informace o nastavení aplikace Microsoft Entra najdete v tématu Rychlý start: Registrace aplikace na platformě Microsoft Identity Platform.

Ověřování pomocí DefaultAzureCredential

Nejjednodušší způsob, jak použít Microsoft Entra k ověření back-endové aplikace, je použít DefaultAzureCredential, ale doporučuje se použít jinou metodu v produkčním prostředí, včetně konkrétní TokenCredential nebo pared-down ChainedTokenCredential. Pro zjednodušení popisuje tato část ověřování pomocí DefaultAzureCredential a tajný klíč klienta. Další informace o výhodách a nevýhodách použití DefaultAzureCredentialnajdete v řetězcích přihlašovacích údajů v klientské knihovně Azure Identity pro Python.

DefaultAzureCredential podporuje různé mechanismy ověřování a určuje odpovídající typ přihlašovacích údajů na základě prostředí, ve které se provádí. Pokusí se použít více typů přihlašovacích údajů v pořadí, dokud nenajde funkční přihlašovací údaje.

Microsoft Entra vyžaduje tento balíček importu a odpovídající import příkaz:

pip install azure-identity

from azure.identity import DefaultAzureCredential

V tomto příkladu se do proměnných prostředí přidal tajný klíč klienta registrace aplikace Microsoft Entra, ID klienta a ID tenanta. Tyto proměnné prostředí se používají DefaultAzureCredential k ověření aplikace. Výsledkem úspěšného ověřování Microsoft Entra je přihlašovací údaje tokenu zabezpečení předávané metodě připojení ioT Hubu.

from azure.identity import DefaultAzureCredential
credential = DefaultAzureCredential()

Výsledný AccessToken se pak dá předat pro from_token_credential připojení ke službě IoT Hub pro libovolného klienta sady SDK, který přijímá přihlašovací údaje Microsoft Entra:

IoTHubRegistryManager k vytvoření připojení služby ke službě IoT Hub pomocí přihlašovacích údajů tokenu Entra.
IoTHubJobManager
DigitalTwinClient
IoTHubHttpRuntimeManager
IoTHubConfigurationManager

from_token_credential vyžaduje dva parametry:

Adresa URL služby Azure – Adresa URL služby Azure by měla být ve formátu {Your Entra domain URL}.azure-devices.net bez předpony https:// . Například MyAzureDomain.azure-devices.net.
Token přihlašovacích údajů Azure

V tomto příkladu se přihlašovací údaje Azure získávají pomocí DefaultAzureCredential. Adresu URL a přihlašovací údaje služby Azure se pak zadají k IoTHubRegistryManager.from_token_credential vytvoření připojení ke službě 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)

Ukázky kódu

Pracovní ukázky ověřování služby Microsoft Entra naleznete v tématu Microsoft Authentication Library (MSAL) pro Python.

Načtení a aktualizace požadovaných vlastností dvojčete identity modulu

Požadované vlastnosti můžete aktualizovat z back-endové aplikace pomocí update_module_twin.

Načtení a aktualizace požadovaných vlastností dvojčete identity modulu:

Zavolejte get_module_twin a získejte aktuální verzi dvojčete identity modulu.
Pomocí třídy Twin přidejte požadované vlastnosti ve formátu JSON.
Volání update_module_twin pro použití opravy na dvojče zařízení Pomocí replace_module_twin můžete také nahradit požadované vlastnosti a značky dvojčete identity modulu.

Tento příklad aktualizuje telemetryInterval požadovanou vlastnost na 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" )

Ukázka služby SDK

Sada Azure IoT SDK pro Python poskytuje funkční ukázku aplikace služby, která zpracovává úlohy dvojčete modulu identit zařízení. Další informace naleznete v tématu Test IoTHub Registry Manager.

Vyžaduje Node.js verze 10.0.x nebo novější.

Přehled

Tento článek popisuje, jak pomocí sady Azure IoT SDK pro Node.js vytvořit kód aplikace zařízení a back-endové služby pro dvojčata identit modulů.

Vytvoření aplikace zařízení

Tato část popisuje, jak pomocí balíčku azure-iot-device v sadě Azure IoT SDK pro Node.js vytvořit aplikaci zařízení pro:

Načtení dvojčete identity modulu a prozkoumání ohlášených vlastností
Aktualizace vlastností ohlášených dvojčat identit modulu
Oznámení o změnách požadovaných vlastností dvojčete identity modulu

Balíček zařízení azure-iot-device obsahuje objekty, které jsou rozhraní se zařízeními IoT. Třída Twin obsahuje objekty specifické pro dvojčete. Tato část popisuje Client kód třídy, který se používá ke čtení a zápisu dat dvojčete identity modulu zařízení.

Instalace balíčku SDK

Spuštěním tohoto příkazu nainstalujte sadu SDK zařízení azure-iot-device na vývojový počítač:

npm install azure-iot-device --save

Připojení zařízení ke službě IoT Hub

Aplikace zařízení se může ověřit ve službě IoT Hub pomocí následujících metod:

Sdílený přístupový klíč
Certifikát X.509

Důležité

Ověřování pomocí sdíleného přístupového klíče

Volba přenosového protokolu

Objekt Client podporuje tyto protokoly:

Amqp
Http– Při použití HttpClient instance kontroluje zprávy ze služby IoT Hub zřídka (minimálně každých 25 minut).
Mqtt
MqttWs
AmqpWs

Nainstalujte na svůj vývojový počítač potřebné přenosové protokoly.

Tento příkaz například nainstaluje Amqp protokol:

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

Další informace o rozdílech mezi podporou MQTT, AMQP a HTTPS najdete v pokynech ke komunikaci typu Cloud-zařízení a volba komunikačního protokolu zařízení.

Vytvoření objektu klienta

Vytvořte Client objekt pomocí nainstalovaného balíčku.

Příklad:

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

Vytvoření objektu protokolu

Vytvořte Protocol objekt pomocí nainstalovaného přenosového balíčku.

Tento příklad přiřadí protokol AMQP:

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

Přidání připojovací řetězec zařízení a přenosového protokolu

Volání zConnectionString pro zadání parametrů připojení zařízení:

connStr – modul identit služby IoT Hub připojovací řetězec.
transportCtor - transportní protokol.

V tomto příkladu se používá přenosový Amqp protokol:

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

Otevření připojení ke službě IoT Hub

Pomocí otevřené metody otevřete připojení mezi zařízením IoT a IoT Hubem.

Příklad:

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

Ověřování pomocí certifikátu X.509

Certifikát X.509 je připojený k přenosu připojení typu device-to-IoT Hub.

Konfigurace připojení typu device-to-IoT Hub pomocí certifikátu X.509:

Voláním zConnectionString přidejte modul zařízení nebo identity připojovací řetězec a typ přenosu do objektuClient. Přidejte x509=true do připojovací řetězec, aby bylo možné označit, že se do DeviceClientOptionssouboru přidá certifikát. Příklad:
- Připojovací řetězec zařízení:
  
  HostName=xxxxx.azure-devices.net;DeviceId=Device-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true
- Modul identity připojovací řetězec:
  
  HostName=xxxxx.azure-devices.net;DeviceId=Device-1;ModuleId=Module-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true
Nakonfigurujte proměnnou JSON s podrobnostmi o certifikátu a předejte ji do DeviceClientOptions.
Volání setOptions pro přidání certifikátu a klíče X.509 (a volitelně i přístupového hesla) do přenosu klienta.
Voláním otevřete připojení ze zařízení ke službě IoT Hub.

Tento příklad ukazuje informace o konfiguraci certifikátu v rámci proměnné JSON. Konfigurace clientOptions certifikace se předává setOptionsa připojení se otevře pomocí 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);

Další informace o ověřování certifikátů najdete tady:

Ukázka kódu

Funkční ukázka ověřování certifikátu X.509 zařízení najdete v tématu Jednoduché ukázkové zařízení X.509.

Načtení dvojčete identity modulu a prozkoumání ohlášených vlastností

Volání metody getTwin pro načtení informací o dvojčeti identity aktuálního modulu do objektu Twin .

Kód zařízení pak může přistupovat k vlastnostem dvojčete identity modulu.

Příklad:

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

Aktualizace ohlášených vlastností dvojčete identity modulu

Aktualizace slouží k aktualizaci ohlášených vlastností zařízení. Zahrňte opravu ve formátu JSON jako první parametr a metodu zpětného volání stavu provádění funkce jako druhý parametr metody.

V tomto příkladu je v patch proměnné uložena oprava dvojčete identity ve formátu JSON. Oprava obsahuje hodnotu cellularaktualizace dvojčete connectivity identity modulu . Obslužná rutina opravy a chyby jsou předány metodě update . Pokud dojde k chybě, zobrazí se chybová zpráva konzoly.

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

Oznámení o změnách požadovaných vlastností dvojčete identity modulu

Vytvořte požadovaná vlastnost dvojčete identity modulu, který aktualizuje naslouchací proces událostí, který se spustí při změně požadované vlastnosti předáním názvu metody obslužné rutiny zpětného volání do twin.on.

Naslouchací proces události požadované vlastnosti může mít následující tvary:

Příjem všech oprav pomocí jedné obslužné rutiny události
Přijetí události, pokud se v seskupování vlastností něco změní
Přijetí události pro změnu jedné vlastnosti

Příjem všech oprav pomocí jedné obslužné rutiny události

Můžete vytvořit naslouchací proces pro příjem jakékoli změny požadované vlastnosti.

Tento příklad kódu vypíše všechny vlastnosti přijaté ze služby.

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

Přijetí události, pokud se v seskupování vlastností něco změní

Pokud se něco pod seskupováním vlastností změní, můžete vytvořit naslouchací proces pro příjem události.

Příklad:

maxTemperature A minTemperature vlastnosti jsou umístěny ve skupině vlastností s názvem properties.desired.climate changes.

Aplikace back-endové služby tuto opravu použije k aktualizaci minTemperature a maxTemperature požadovaným vlastnostem:

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

Tento kód nastaví naslouchací proces změny požadované vlastnosti, který aktivuje všechny změny v rámci properties.desired.climate seskupení vlastností. Pokud se v této skupině změní požadovaná vlastnost, zobrazí se v konzole zprávy o minimální a maximální změně teploty:

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

Přijetí události pro změnu jedné vlastnosti

Naslouchací proces můžete nastavit pro změnu jedné vlastnosti. V tomto příkladu se kód pro tuto událost spustí pouze v případě, že fanOn je logická hodnota součástí opravy. Kód vypíše nový požadovaný fanOn stav pokaždé, když ji služba aktualizuje.

Back-endová aplikace použije tuto opravu požadované vlastnosti:

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

Naslouchací proces se aktivuje pouze v případech, kdy se fanOn vlastnost změní:

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

Kompletní příklad

Tento příklad zapouzdřuje principy této části, včetně vnoření funkce zpětného volání na více úrovní.

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

  });
});

Ukázky sady SDK pro zařízení

Sada Azure IoT SDK pro Node.js poskytuje funkční ukázky aplikací zařízení, které zpracovávají úlohy dvojčat identit modulů. Další informace naleznete v tématu:

Vytvoření back-endové aplikace

Tato část popisuje, jak vytvořit back-endovou aplikaci, která načte dvojče identity modulu a aktualizuje požadované vlastnosti.

Instalace balíčku sady SDK služby

Spuštěním tohoto příkazu nainstalujte azure-iothub na vývojový počítač:

npm install azure-iothub --save

Vytvoření objektu registru

Třída Registry zveřejňuje všechny metody potřebné k interakci s dvojčaty identit modulu z back-endové aplikace.

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

Připojení ke službě IoT Hub

Back-endovou službu můžete ke službě IoT Hub připojit pomocí následujících metod:

Zásady sdíleného přístupu
Microsoft Entra

Důležité

Připojení pomocí zásad sdíleného přístupu

Použijte fromConnectionString pro připojení ke službě IoT Hub.

Metoda použitá update v této části vyžaduje , aby zásady sdíleného přístupu služby Service Connect přidaly požadované vlastnosti do modulu. Jako parametr fromConnectionStringzadejte zásady sdíleného přístupu připojovací řetězec, které zahrnují oprávnění Service Connect. Další informace o zásadách sdíleného přístupu najdete v tématu Řízení přístupu ke službě IoT Hub pomocí sdílených přístupových podpisů.

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

Připojení pomocí Microsoft Entra

Přehled ověřování Node.js SDK najdete v těchto tématech:

Konfigurace aplikace Microsoft Entra

Tajný klíč klienta
Certifikát
Přihlašovací údaje federované identity

Další informace o nastavení aplikace Microsoft Entra najdete v tématu Rychlý start: Registrace aplikace na platformě Microsoft Identity Platform.

Ověřování pomocí DefaultAzureCredential

Nejjednodušší způsob, jak použít Microsoft Entra k ověření back-endové aplikace, je použít DefaultAzureCredential, ale doporučuje se použít jinou metodu v produkčním prostředí, včetně konkrétní TokenCredential nebo pared-down ChainedTokenCredential. Pro zjednodušení popisuje tato část ověřování pomocí DefaultAzureCredential a tajný klíč klienta. Další informace o výhodách a nevýhodách použití DefaultAzureCredentialnajdete v řetězcích přihlašovacích údajů v klientské knihovně Azure Identity pro JavaScript.

Microsoft Entra vyžaduje tento balíček:

npm install --save @azure/identity

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

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

Výsledný token přihlašovacích údajů se pak dá předat zTokenCredential pro připojení ke službě IoT Hub pro libovolného klienta sady SDK, který přijímá přihlašovací údaje Microsoft Entra:

fromTokenCredential vyžaduje dva parametry:

Adresa URL služby Azure – Adresa URL služby Azure by měla být ve formátu {Your Entra domain URL}.azure-devices.net bez předpony https:// . Například MyAzureDomain.azure-devices.net.
Token přihlašovacích údajů Azure

V tomto příkladu se přihlašovací údaje Azure získávají pomocí DefaultAzureCredential. Adresa URL domény Azure a přihlašovací údaje se pak zadají k Registry.fromTokenCredential vytvoření připojení ke službě 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);

Ukázky kódu

Pracovní ukázky ověřování služby Microsoft Entra najdete v příkladech identit Azure.

Načtení dvojčete identity modulu a aktualizace požadovaných vlastností

Můžete vytvořit opravu, která obsahuje aktualizace požadovaných vlastností dvojčete identity modulu.

Aktualizace dvojčete identity modulu:

Volání getModuleTwin k načtení objektu dvojčete zařízení.
Naformátujte opravu, která obsahuje aktualizaci dvojčete identity modulu. Oprava je formátována ve formátu JSON, jak je popsáno ve třídě Twin. Oprava back-endové služby obsahuje aktualizace požadovaných vlastností. Další informace o formátu opravy naleznete v tématu Značky a formát vlastností.
Aktualizace volání pro aktualizaci dvojčete identity modulu pomocí opravy

V tomto příkladu se načte dvojče identity modulu pro myDeviceId a myModuleId. Potom se na dvojčata, která obsahují climate informace, použije oprava.

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

Ukázky sady SDK služby

Sada Azure IoT SDK pro Node.js poskytuje funkční ukázky aplikací služeb, které zpracovávají úlohy dvojčat identit modulů. Další informace naleznete v tématu:

Sdílet prostřednictvím

Začínáme s identitami modulů ioT Hubu a dvojčaty identit modulů

Požadavky

Přehled

Vytvoření aplikace zařízení

Požadovaný balíček NuGet zařízení

Připojení k zařízení

Načtení dvojčete identity modulu a prozkoumání vlastností

Aktualizace ohlášených vlastností dvojčete identity modulu

Vytvoření obslužné rutiny zpětného volání aktualizace požadované vlastnosti

Ukázka modulu SADY SDK

Vytvoření back-endové aplikace

Požadovaný balíček NuGet služby

Připojení ke službě IoT Hub

Připojení pomocí zásad sdíleného přístupu

Připojení pomocí Microsoft Entra

Konfigurace aplikace Microsoft Entra

Ověřování pomocí DefaultAzureCredential

Ukázka kódu

Čtení a aktualizace polí identity modulu

Rozhraní API jiného modulu

Ukázka služby SDK

Přehled

Instalace balíčků

Vytvoření aplikace zařízení

Příkazy importu

Připojení k zařízení

Načtení dvojčete identity modulu a prozkoumání vlastností

Aktualizace ohlášených vlastností dvojčete identity modulu

Vytvoření požadované vlastnosti dvojčete identity modulu – obslužná rutina zpětného volání

Ukázky zařízení sady SDK

Vytvoření back-endové aplikace

Příkazy importu služby

Připojení ke službě IoT Hub

Připojení pomocí zásad sdíleného přístupu

Připojení pomocí Microsoft Entra

Konfigurace aplikace Microsoft Entra

Ověřování pomocí DefaultAzureCredential

Ukázky kódu

Načtení a aktualizace požadovaných vlastností dvojčete identity modulu

Ukázka služby SDK

Přehled

Vytvoření aplikace zařízení

Instalace balíčku SDK

Připojení zařízení ke službě IoT Hub

Ověřování pomocí sdíleného přístupového klíče

Volba přenosového protokolu

Vytvoření objektu klienta

Vytvoření objektu protokolu

Přidání připojovací řetězec zařízení a přenosového protokolu

Otevření připojení ke službě IoT Hub

Ověřování pomocí certifikátu X.509

Ukázka kódu

Načtení dvojčete identity modulu a prozkoumání ohlášených vlastností

Aktualizace ohlášených vlastností dvojčete identity modulu

Oznámení o změnách požadovaných vlastností dvojčete identity modulu

Příjem všech oprav pomocí jedné obslužné rutiny události

Přijetí události, pokud se v seskupování vlastností něco změní

Přijetí události pro změnu jedné vlastnosti

Kompletní příklad

Ukázky sady SDK pro zařízení

Vytvoření back-endové aplikace

Instalace balíčku sady SDK služby

Vytvoření objektu registru

Připojení ke službě IoT Hub

Připojení pomocí zásad sdíleného přístupu

Připojení pomocí Microsoft Entra

Konfigurace aplikace Microsoft Entra

Ověřování pomocí DefaultAzureCredential

Ukázky kódu

Načtení dvojčete identity modulu a aktualizace požadovaných vlastností

Ukázky sady SDK služby

Váš názor

Další materiály