Ismerkedés az IoT Hub modulidentitásaival és a modulidentitás-ikerpéldányokkal

• Visual Studio-t igényel

Áttekintés

Ez a cikk azt ismerteti, hogyan hozhat létre eszköz- és háttérszolgáltatás-alkalmazáskódot modulidentitás-ikerpéldányokhoz az Azure IoT SDK for .NET használatával.

Eszközalkalmazás létrehozása

Ez a szakasz azt ismerteti, hogyan használhatja az eszközalkalmazás kódját a következőre:

• Modulidentitás ikerpéldány lekérése és jelentett tulajdonságok vizsgálata
• A modul identitásának jelentett ikertulajdonságainak frissítése
• Modul kívánt tulajdonságfrissítési visszahíváskezelő létrehozása

Szükséges eszköz NuGet-csomag

A C# nyelven írt eszközügyfél-alkalmazásokhoz a Microsoft.Azure.Devices.Client NuGet-csomag szükséges.

Adja hozzá ezeket az using utasításokat az eszköztár használatához.

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

Csatlakozás eszközhöz

A ModuleClient osztály az eszközről származó modulidentitás-ikerpéldányok használatához szükséges összes metódust elérhetővé teszi.

Csatlakozzon az eszközhöz a CreateFromConnectionString metódussal a modul identitásával kapcsolati sztring.

Az átviteli paraméter nélküli hívás CreateFromConnectionString az alapértelmezett AMQP-átvitel használatával csatlakozik.

Ez a példa az alapértelmezett AMQP-átvitel használatával csatlakozik az eszközhöz.

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

_moduleClient = ModuleClient.CreateFromConnectionString(ModuleConnectionString, null);

Modulidentitás ikerpéldány lekérése és tulajdonságok vizsgálata

Hívja meg a GetTwinAsync-et , hogy lekérje az aktuális modulidentitás-ikertulajdonságokat egy ikerobjektumba .

Ez a példa JSON formátumban kéri le és jeleníti meg a modulidentitás ikertulajdonságait.

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

A modul identitási ikerpéldányának jelentett tulajdonságainak frissítése

Iker jelentett tulajdonság frissítése:

1. TwinCollection-objektum létrehozása a jelentett tulajdonságfrissítéshez
2. Egy vagy több jelentett tulajdonság frissítése az objektumon TwinCollection belül
3. Az UpdateReportedPropertiesAsync használatával küldje le a jelentett tulajdonságmódosításokat az IoT Hub szolgáltatásba

Példa:

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

Kívánt tulajdonságfrissítési visszahíváskezelő létrehozása

Adja át a visszahíváskezelő metódus nevét a SetDesiredPropertyUpdateCallbackAsync metódusnak, hogy létrehozzon egy kívánt tulajdonságfrissítési visszahíváskezelőt, amely akkor hajtja végre a kívánt tulajdonság módosítását a modul identitási ikerpéldányában.

Ez a hívás például úgy állítja be a rendszert, hogy értesítse a kívánt modultulajdonságok módosításakor elnevezett OnDesiredPropertyChangedAsync metódust.

await _moduleClient.SetDesiredPropertyUpdateCallbackAsync(OnDesiredPropertyChangedAsync, null);

A modul identitási ikertulajdonságait a rendszer TwinCollectionként továbbítja a visszahívási metódusnak, és struktúrákként KeyValuePair vizsgálható.

Ez a példa fogadja a kívánt tulajdonságfrissítéseket, TwinCollectionmajd végighalad a gyűjteményfrissítéseken, és kinyomtatja.KeyValuePair A gyűjtemény végigcsukása KeyValuePair után a kód meghívja UpdateReportedPropertiesAsync a DateTimeLastDesiredPropertyChangeReceived jelentett tulajdonság frissítését, hogy naprakészen tartsa az utolsó frissítési időt.

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

SDK-modulminta

A .NET-hez készült Azure IoT SDK a modulidentitás-ikerfeladatokat kezelő eszközalkalmazások munkamintáit tartalmazza. További információk:

• TwinSample
• Eszközügyfél-tesztek

Háttéralkalmazás létrehozása

Ez a szakasz a modul identitásmezőinek olvasását és frissítését ismerteti.

A RegistryManager osztály minden olyan metódust elérhetővé tesz, amely egy háttéralkalmazás létrehozásához szükséges a szolgáltatás modulidentitás-ikerpéldányaival való interakcióhoz.

Kötelező szolgáltatás NuGet-csomag

A háttérszolgáltatás-alkalmazásokhoz a Microsoft.Azure.Devices NuGet-csomag szükséges.

Adja hozzá ezeket az using utasításokat a szolgáltatástár használatához.

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

Csatlakozás az IoT Hubhoz

Háttérszolgáltatást az alábbi módszerekkel csatlakoztathat az IoT Hubhoz:

• Megosztott hozzáférési szabályzat
• Microsoft Entra

Csatlakozás megosztott hozzáférési szabályzattal

Háttéralkalmazás csatlakoztatása az IoT Hubhoz a CreateFromConnectionString használatával.

Az UpdateModuleAsync ebben a szakaszban használt módszerhez a Service Connect megosztott hozzáférési szabályzatának engedélyére van szükség a kívánt tulajdonságok modulhoz való hozzáadásához. Paraméterként CreateFromConnectionStringadjon meg egy olyan megosztott hozzáférési szabályzatot kapcsolati sztring, amely Service Connect-engedélyt tartalmaz. A megosztott hozzáférési szabályzatokról további információt az IoT Hub hozzáférésének szabályozása közös hozzáférésű jogosultságkódokkal című témakörben talál.

Példa:

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

Csatlakozás a Microsoft Entra használatával

A Microsoft Entrát használó háttéralkalmazásnak sikeresen hitelesítenie kell és be kell szereznie egy biztonsági jogkivonat hitelesítő adatait, mielőtt csatlakozik az IoT Hubhoz. Ez a jogkivonat egy IoT Hub-kapcsolati metódusnak lesz átadva. A Microsoft Entra for IoT Hub beállításával és használatával kapcsolatos általános információkért tekintse meg az IoT Hubhoz való hozzáférés Szabályozása a Microsoft Entra ID használatával című témakört.

A Microsoft Entra alkalmazás konfigurálása

Be kell állítania egy Microsoft Entra-alkalmazást, amely az előnyben részesített hitelesítési hitelesítő adatokhoz van konfigurálva. Az alkalmazás olyan paramétereket tartalmaz, mint az ügyfélkulcs, amelyeket a háttéralkalmazás használ a hitelesítéshez. Az elérhető alkalmazáshitelesítési konfigurációk a következők:

• Titkos ügyfélkód
• Tanúsítvány
• Összevont identitás hitelesítő adatai

A Microsoft Entra-alkalmazások adott szerepkör-engedélyeket igényelhetnek a végrehajtott műveletektől függően. Az IoT Hub ikerpéldány-közreműködője például az IoT Hub-eszközökhöz és modulikrekhez való olvasási és írási hozzáférés engedélyezéséhez szükséges. További információ: IoT Hub-hozzáférés kezelése Azure RBAC-szerepkör-hozzárendeléssel.

A Microsoft Entra-alkalmazások beállításáról további információt a rövid útmutatóban talál: Alkalmazás regisztrálása a Microsoft Identitásplatform.

Hitelesítés DefaultAzureCredential használatával

A Microsoft Entra segítségével a legegyszerűbben a DefaultAzureCredential használatával hitelesíthet egy háttéralkalmazást, de ajánlott egy másik módszert használni egy éles környezetben, beleértve egy adott TokenCredential vagy pared-down ChainedTokenCredentialmetódust is. Az egyszerűség kedvéért ez a szakasz a hitelesítést és az ügyfél titkos kódjának használatát DefaultAzureCredential ismerteti. A használat DefaultAzureCredentialelőnyeiről és hátrányairól további információt a DefaultAzureCredential használati útmutatója tartalmaz.

DefaultAzureCredential támogatja a különböző hitelesítési mechanizmusokat, és meghatározza a megfelelő hitelesítőadat-típust az általa futtatott környezet alapján. Több hitelesítő adattípust próbál meg egy sorrendben használni, amíg nem talál egy működő hitelesítő adatot.

A Microsoft Entra megköveteli ezeket a NuGet-csomagokat és a hozzájuk tartozó using utasításokat:

• Azure.Core
• Azure.Identity

using Azure.Core;
using Azure.Identity;

Ebben a példában a Microsoft Entra alkalmazásregisztrációs ügyfélkulcsa, ügyfél-azonosítója és bérlőazonosítója hozzáadódik a környezeti változókhoz. Ezek a környezeti változók az DefaultAzureCredential alkalmazás hitelesítésére szolgálnak. A sikeres Microsoft Entra-hitelesítés eredménye egy biztonsági jogkivonat hitelesítő adatai, amelyet egy IoT Hub-kapcsolati módszernek ad át.

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

Az eredményül kapott TokenCredential ezután átadható egy IoT Hub-metódushoz való csatlakozásnak minden olyan SDK-ügyfél esetében, amely elfogadja a Microsoft Entra hitelesítő adatait:

• JobClient
• RegistryManager
• DigitalTwinClient
• ServiceClient

Ebben a példában a TokenCredential serviceClient kapcsolati objektum létrehozásához szükséges átadás ServiceClient.Create történik.

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

Ebben a példában a rendszer átadja a TokenCredential RegistryManager objektum létrehozásához.RegistryManager.Create

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

Kódminta

A Microsoft Entra szolgáltatáshitelesítés működő mintájáért tekintse meg a szerepköralapú hitelesítési mintát.

Modul identitásmezőinek olvasása és frissítése

Hívja meg a GetModuleAsync parancsot a modul identitásának aktuális ikermezőinek modulobjektumba való lekéréséhez.

Az Module osztály tartalmazza properties a modul identitás ikerpéldányainak megfelelő szakaszokat. A Modul osztály tulajdonságaival megtekintheti és frissítheti a modul identitási ikermezőit. Az objektumtulajdonságok használatával Module több mezőt is frissíthet, mielőtt a frissítéseket az eszközre UpdateModuleAsyncíranál.

A modulidentitás ikermezőinek frissítése után hívja meg az UpdateModuleAsync-et, hogy írja Module vissza az objektummező frissítéseit egy eszközre. Hibakezelővel párosított logika és catch használat try a hibásan formázott javításhibák UpdateModuleAsyncelfogásához.

Ez a példa beolvassa a modult egy Module objektumba, frissíti a moduleLastActivityTime tulajdonságot, majd frissíti a modult az IoT Hubban a használatával 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);
}

Egyéb modul API

• GetModulesOnDeviceAsync – Lekéri a modulidentitásokat egy eszközön
• RemoveModuleAsync – Töröl egy korábban regisztrált modult egy eszközről

SDK-szolgáltatásminta

A .NET-hez készült Azure IoT SDK egy olyan szolgáltatásalkalmazás működő mintáját biztosítja, amely modulidentitás-ikerfeladatokat kezel. További információ: Registry Manager E2E-tesztek.

• A Python 3.7-es vagy újabb verziója ajánlott. Mindenképp a rendszernek megfelelő, 32 vagy 64 bites telepítést használja. Amikor a rendszer erre kéri, mindenképp adja hozzá a Pythont a platformspecifikus környezeti változóhoz.

Áttekintés

Ez a cikk azt ismerteti, hogyan használható a Pythonhoz készült Azure IoT SDK eszköz- és háttérszolgáltatás-alkalmazáskód létrehozása modulidentitás-ikerpéldányokhoz.

Csomagok telepítése

Az azure-iot-device kódtárat telepíteni kell az eszközalkalmazások létrehozásához.

pip install azure-iot-device

A háttérszolgáltatás-alkalmazások létrehozásához telepíteni kell az azure-iot-hub kódtárat.

pip install azure-iot-hub

Az msrest-kódtár a HTTPOperationError-kivételek elfogására szolgál.

pip install msrest

Eszközalkalmazás létrehozása

Ez a szakasz azt ismerteti, hogyan használhatja az eszközalkalmazás kódját a következőre:

• Modulidentitás ikerpéldány lekérése és jelentett tulajdonságok vizsgálata
• A modul identitási ikerpéldányának jelentett tulajdonságainak frissítése
• Modulidentitás ikertulajdonság-frissítési visszahíváskezelő létrehozása

Utasítások importálása

Adja hozzá ezt az import utasítást az eszköztár használatához.

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

Csatlakozás eszközhöz

Az IoTHubModuleClient osztály olyan metódusokat tartalmaz, amelyek a modulidentitás-ikerpéldányok használatához használhatók.

Alkalmazás csatlakoztatása eszközhöz:

1. Hívja meg create_from_connection_string a modul identitásának hozzáadásához kapcsolati sztring
2. Csatlakozás hívása az eszközügyfél Azure IoT Hubhoz való csatlakoztatásához

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

Modulidentitás ikerpéldány lekérése és tulajdonságok vizsgálata

Hívja meg get_twin , hogy lekérje a modulidentitás ikerpéldányát az Azure IoT Hub szolgáltatásból. Az ikeradatok egy vizsgálható változóba kerülnek.

Ez a példa lekéri az ikereszközt, és a print paranccsal JSON formátumban jeleníti meg az ikereszközt.

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

A modul identitási ikerpéldányának jelentett tulajdonságainak frissítése

Javítást alkalmazhat a modul identitás ikerpéldányának jelentett tulajdonságainak JSON formátumban történő frissítéséhez.

Javítás alkalmazása a jelentett tulajdonságok frissítéséhez:

1. Hozzárendelhet egy jelentett tulajdonság JSON-javítást egy változóhoz.
2. Hívja meg patch_twin_reported_properties , hogy alkalmazza a JSON-javítást a jelentett tulajdonságokra.

Példa:

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

Modulidentitás ikertulajdonság-frissítési visszahíváskezelő létrehozása

Hívja meg a on_twin_desired_properties_patch_received , hogy hozzon létre egy kezelőfüggvényt vagy coroutine-t, amelyet a modul identitásának ikertulajdonság-javításának érkezésekor hív meg. A kezelő egy argumentumot vesz fel, amely az ikerjavítás JSON-szótárobjektum formájában.

Ez a példa beállít egy kívánt tulajdonságjavítás-kezelőt.twin_patch_handler

Példa:

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

A twin_patch_handler JSON kívánt tulajdonságfrissítéseinek fogadása és nyomtatása.

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

SDK-eszközminták

A Pythonhoz készült Azure IoT SDK a modulidentitás-ikerfeladatokat kezelő eszközalkalmazások működő mintáját biztosítja:

• get_twin – Csatlakozzon egy eszközhöz, és kérje le az ikeradatokat.
• update_twin_reported_properties – Az ikerpéldány jelentett tulajdonságainak frissítése.
• receive_twin_desired_properties – A kívánt tulajdonságok fogadása és frissítése.

Háttéralkalmazás létrehozása

Ez a szakasz azt ismerteti, hogyan hozhat létre háttéralkalmazást a modul identitási ikerpéldányának kívánt tulajdonságainak lekéréséhez és frissítéséhez.

Az IoTHubRegistryManager osztály minden olyan módszert elérhetővé tesz, amely egy háttéralkalmazás létrehozásához szükséges a szolgáltatás modulidentitás-ikerpéldányaival való interakcióhoz.

Szolgáltatásimportálási utasítások

Adja hozzá ezt az import utasítást a szolgáltatástár használatához.

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

Csatlakozás az IoT Hubhoz

Háttérszolgáltatást az alábbi módszerekkel csatlakoztathat az IoT Hubhoz:

• Megosztott hozzáférési szabályzat
• Microsoft Entra

Csatlakozás megosztott hozzáférési szabályzattal

Csatlakozzon az IoT Hubhoz from_connection_string használatával.

Az update_module_twin ebben a szakaszban használt módszerhez a Service Connect megosztott hozzáférési szabályzatának engedélyére van szükség a kívánt tulajdonságok modulhoz való hozzáadásához. Paraméterként from_connection_stringadjon meg egy olyan megosztott hozzáférési szabályzatot kapcsolati sztring, amely Service Connect-engedélyt tartalmaz. A megosztott hozzáférési szabályzatokról további információt az IoT Hub hozzáférésének szabályozása közös hozzáférésű jogosultságkódokkal című témakörben talál.

Példa:

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

Csatlakozás a Microsoft Entra használatával

A Microsoft Entrát használó háttéralkalmazásnak sikeresen hitelesítenie kell és be kell szereznie egy biztonsági jogkivonat hitelesítő adatait, mielőtt csatlakozik az IoT Hubhoz. Ez a jogkivonat egy IoT Hub-kapcsolati metódusnak lesz átadva. A Microsoft Entra for IoT Hub beállításával és használatával kapcsolatos általános információkért tekintse meg az IoT Hubhoz való hozzáférés Szabályozása a Microsoft Entra ID használatával című témakört.

A Python SDK-hitelesítés áttekintését lásd : Python-alkalmazások hitelesítése Az Azure-szolgáltatásokban a Pythonhoz készült Azure SDK használatával

A Microsoft Entra alkalmazás konfigurálása

Be kell állítania egy Microsoft Entra-alkalmazást, amely az előnyben részesített hitelesítési hitelesítő adatokhoz van konfigurálva. Az alkalmazás olyan paramétereket tartalmaz, mint az ügyfélkulcs, amelyeket a háttéralkalmazás használ a hitelesítéshez. Az elérhető alkalmazáshitelesítési konfigurációk a következők:

• Titkos ügyfélkód
• Tanúsítvány
• Összevont identitás hitelesítő adatai

A Microsoft Entra-alkalmazások adott szerepkör-engedélyeket igényelhetnek a végrehajtott műveletektől függően. Az IoT Hub ikerpéldány-közreműködője például az IoT Hub-eszközökhöz és modulikrekhez való olvasási és írási hozzáférés engedélyezéséhez szükséges. További információ: IoT Hub-hozzáférés kezelése Azure RBAC-szerepkör-hozzárendeléssel.

A Microsoft Entra-alkalmazások beállításáról további információt a rövid útmutatóban talál: Alkalmazás regisztrálása a Microsoft Identitásplatform.

Hitelesítés DefaultAzureCredential használatával

A Microsoft Entra segítségével a legegyszerűbben a DefaultAzureCredential használatával hitelesíthet egy háttéralkalmazást, de ajánlott egy másik módszert használni egy éles környezetben, beleértve egy adott TokenCredential vagy pared-down ChainedTokenCredentialmetódust is. Az egyszerűség kedvéért ez a szakasz a hitelesítést és az ügyfél titkos kódjának használatát DefaultAzureCredential ismerteti. A használat DefaultAzureCredentialelőnyeiről és hátrányairól további információt a PythonHoz készült Azure Identity ügyfélkódtár hitelesítőadat-láncai című témakörben talál.

A DefaultAzureCredential különböző hitelesítési mechanizmusokat támogat, és meghatározza a megfelelő hitelesítőadat-típust a környezet alapján, amelyben végrehajtja. Több hitelesítő adattípust próbál meg egy sorrendben használni, amíg nem talál egy működő hitelesítő adatot.

A Microsoft Entra megköveteli ezt az importálási csomagot és a megfelelő import utasítást:

pip install azure-identity

from azure.identity import DefaultAzureCredential

Ebben a példában a Microsoft Entra alkalmazásregisztrációs ügyfél titkos kódját, ügyfél-azonosítóját és bérlőazonosítóját hozzáadtuk a környezeti változókhoz. Ezek a környezeti változók az DefaultAzureCredential alkalmazás hitelesítésére szolgálnak. A sikeres Microsoft Entra-hitelesítés eredménye egy biztonsági jogkivonat hitelesítő adatai, amelyet egy IoT Hub-kapcsolati módszernek ad át.

from azure.identity import DefaultAzureCredential
credential = DefaultAzureCredential()

Az eredményül kapott AccessToken ezután átadható az from_token_credential IoT Hubhoz való csatlakozáshoz minden olyan SDK-ügyfélhez, amely elfogadja a Microsoft Entra hitelesítő adatait:

• IoTHubRegistryManager az IoT Hub szolgáltatáskapcsolatának létrehozásához Entra-jogkivonat hitelesítő adataival.
• IoTHubJobManager
• DigitalTwinClient
• IoTHubHttpRuntimeManager
• IoTHubConfigurationManager

from_token_credential két paramétert igényel:

• Az Azure-szolgáltatás URL-címe – Az Azure-szolgáltatás URL-címének előtag nélküli https:// formátumban {Your Entra domain URL}.azure-devices.net kell lennie. Például: MyAzureDomain.azure-devices.net.
• Az Azure hitelesítőadat-jogkivonata

Ebben a példában az Azure-hitelesítő adatokat a rendszer a használatával szerzi be DefaultAzureCredential. Ezután megjelenik IoTHubRegistryManager.from_token_credential az Azure-szolgáltatás URL-címe és hitelesítő adatai az IoT Hubhoz való kapcsolat létrehozásához.

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)

Kódminták

A Microsoft Entra szolgáltatáshitelesítés működő mintáit a Pythonhoz készült Microsoft Authentication Library (MSAL) című témakörben talál.

A modul identitási ikerpéldányának kívánt tulajdonságainak lekérése és frissítése

A háttéralkalmazások kívánt tulajdonságait a update_module_twin használatával frissítheti.

A modul identitási ikerpéldányának kívánt tulajdonságainak lekérése és frissítése:

1. Hívja meg a get_module_twin a modul identitási ikerpéldányának aktuális verziójának lekéréséhez.
2. Az Ikerosztály használatával adja hozzá a kívánt tulajdonságokat JSON formátumban.
3. Hívja meg update_module_twin , hogy alkalmazza a javítást az ikereszközre. A modul identitási ikerpéldányának kívánt tulajdonságait és címkéinek cseréjéhez replace_module_twin is használhatja.

Ez a példa frissíti a telemetryInterval kívánt tulajdonságot a következőre 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-szolgáltatásminta

A Pythonhoz készült Azure IoT SDK egy olyan szolgáltatásalkalmazás működő mintáját biztosítja, amely ikereszköz-identitásmodul-feladatokat kezel. További információ: IoTHub Registry Manager tesztelése.

• Node.js 10.0.x vagy újabb verziót igényel

Áttekintés

Ez a cikk azt ismerteti, hogyan használható az Azure IoT SDK Node.js eszköz- és háttérszolgáltatás-alkalmazáskódjának létrehozására modulidentitás-ikerpéldányokhoz.

Eszközalkalmazás létrehozása

Ez a szakasz azt ismerteti, hogyan használható az azure-iot-device csomag az Azure IoT SDK-ban Node.js eszközalkalmazás létrehozásához a következő célokra:

• Modulidentitás ikerpéldány lekérése és jelentett tulajdonságok vizsgálata
• Modul identitásának jelentett ikertulajdonságainak frissítése
• Értesítést kap a modul identitásának ikertulajdonság-módosításairól

Az azure-iot-device csomag olyan objektumokat tartalmaz, amelyek IoT-eszközökhöz illesztenek. Az ikerosztály ikerspecifikus objektumokat tartalmaz. Ez a szakasz az eszközmodul identitási ikeradatainak olvasására és írására használt osztálykódot ismerteti Client .

SDK-csomag telepítése

Futtassa ezt a parancsot az azure-iot-device SDK telepítéséhez a fejlesztői gépen:

npm install azure-iot-device --save

Eszköz csatlakoztatása az IoT Hubhoz

Az eszközalkalmazások az alábbi módszerekkel végezhetnek hitelesítést az IoT Hubon:

• Megosztott hozzáférési kulcs
• X.509-tanúsítvány

Hitelesítés megosztott hozzáférési kulccsal

Átviteli protokoll kiválasztása

Az Client objektum a következő protokollokat támogatja:

• Amqp
• Http - Használat Httpesetén a példány ritkán (legalább 25 percenként) ellenőrzi az Client IoT Hubtól érkező üzeneteket.
• Mqtt
• MqttWs
• AmqpWs

Telepítse a szükséges átviteli protokollokat a fejlesztői gépen.

Ez a parancs például telepíti a protokollt Amqp :

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

Az MQTT, az AMQP és a HTTPS-támogatás közötti különbségekről további információt a felhőalapú kommunikációs útmutatóban és az Eszközkommunikációs protokoll kiválasztása című témakörben talál.

Ügyfélobjektum létrehozása

Hozzon létre egy objektumot Client a telepített csomag használatával.

Példa:

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

Protokollobjektum létrehozása

Objektum létrehozása Protocol telepített átviteli csomag használatával.

Ez a példa az AMQP protokollt rendeli hozzá:

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

Az eszköz kapcsolati sztring és átviteli protokolljának hozzáadása

Hívás aConnectionStringtől az eszközkapcsolati paraméterek megadásához:

• connStr – Az IoT Hub identitásmodulja kapcsolati sztring.
• transportCtor – A szállítási protokoll.

Ez a példa az átviteli protokollt Amqp használja:

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

Az IoT Hubhoz való kapcsolat megnyitása

A nyitott metódussal megnyithat egy kapcsolatot egy IoT-eszköz és az IoT Hub között.

Példa:

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

Hitelesítés X.509-tanúsítvánnyal

Az X.509-tanúsítvány az eszköz–IoT Hub kapcsolatátvitelhez van csatolva.

Eszköz–IoT Hub kapcsolat konfigurálása X.509-tanúsítvány használatával:

1. AConnectionString hívásával adja hozzá az eszköz- vagy identitásmodul kapcsolati sztring, és adja hozzá az Client objektum átviteli típusát. Adja hozzá x509=true a kapcsolati sztring, hogy jelezze, hogy a rendszer tanúsítványt ad hozzáDeviceClientOptions. Példa:

   • Eszköz kapcsolati sztring:

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

   • Identitásmodul kapcsolati sztring:

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

2. Konfiguráljon egy JSON-változót tanúsítványadatokkal, és adja át a DeviceClientOptionsnak.

3. Hívja meg a setOptionst , hogy adjon hozzá egy X.509-tanúsítványt és kulcsot (és opcionálisan jelszót) az ügyfélátvitelhez.

4. Nyissa meg a hívást az eszköz és az IoT Hub közötti kapcsolat megnyitásához.

Ez a példa egy JSON-változó tanúsítványkonfigurációs adatait mutatja be. A rendszer átadja a tanúsítványkonfigurációt clientOptionssetOptions, és a kapcsolat a következő használatával opennyílik meg: .

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

További információ a tanúsítványhitelesítésről:

• Identitások hitelesítése X.509-tanúsítványokkal
• Tanúsítványok létrehozása és feltöltése teszteléshez

Kódminta

Az X.509-tanúsítványhitelesítés működő mintájáért tekintse meg az X.509 egyszerű mintaeszközt.

Modulidentitás ikerpéldány lekérése és jelentett tulajdonságok vizsgálata

Hívja meg a getTwint , hogy lekérje a modul identitásának aktuális ikeradatait egy ikerobjektumba .

Az eszközkód ezután hozzáférhet a modul identitási ikertulajdonságaihoz.

Példa:

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

A modul identitási ikerpéldányának jelentett tulajdonságainak frissítése

Az eszköz jelentett tulajdonságainak frissítéséhez használja a frissítést . A metódus második paramétereként adjon meg egy JSON formátumú javítást az első paraméter és a függvény végrehajtási állapotának visszahívási módszereként.

Ebben a példában egy JSON-formátumú modul identitási ikerjavítása van tárolva a patch változóban. A javítás a modul identitásának ikerpéldányának connectivity frissítési cellularértékét tartalmazza. A rendszer átadja a javítás- és hibakezelőt a update metódusnak. Hiba esetén megjelenik egy konzol hibaüzenete.

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

Értesítést kap a modul identitásának ikertulajdonság-módosításairól

Hozzon létre egy modulidentitás ikertulajdonság-frissítési eseményfigyelőt, amely a kívánt tulajdonság módosításakor hajtja végre a visszahíváskezelő metódus nevét a twin.on-nak.

A kívánt tulajdonságesemény-figyelő a következő űrlapokat használhatja:

• Az összes javítás fogadása egyetlen eseménykezelővel
• Esemény fogadása, ha valami megváltozik a tulajdonságok csoportosítása alatt
• Esemény fogadása egyetlen tulajdonságmódosításhoz

Az összes javítás fogadása egyetlen eseménykezelővel

Létrehozhat egy figyelőt a kívánt tulajdonságmódosítások fogadásához.

Ez a példakód a szolgáltatástól kapott tulajdonságokat adja ki.

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

Esemény fogadása, ha valami megváltozik a tulajdonságok csoportosítása alatt

Létrehozhat egy figyelőt, hogy eseményt fogadjon, ha a tulajdonságcsoportba tartozó bármi megváltozik.

Példa:

1. A minTemperature tulajdonságok és maxTemperature a tulajdonságok egy névvel ellátott properties.desired.climate changestulajdonságcsoport alatt találhatók.

2. Egy háttérszolgáltatás-alkalmazás alkalmazza ezt a javítást a frissítésre minTemperature és maxTemperature a kívánt tulajdonságokra:

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

3. Ez a kód beállít egy kívánt tulajdonságmódosítási eseményfigyelőt, amely aktiválja a properties.desired.climate tulajdonságcsoporton belüli módosításokat. Ha a csoporton belül a kívánt tulajdonság megváltozik, a minimális és a maximális hőmérséklet-változási üzenetek megjelennek a konzolon:

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

Esemény fogadása egyetlen tulajdonságmódosításhoz

Beállíthat egy figyelőt egyetlen tulajdonságmódosításhoz. Ebben a példában az esemény kódja csak akkor lesz végrehajtva, ha a fanOn logikai érték a javítás része. A kód az új kívánt fanOn állapotot adja ki, amikor a szolgáltatás frissíti.

1. Egy háttéralkalmazás alkalmazza ezt a kívánt tulajdonságjavítást:

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

2. A figyelő csak akkor aktiválódik, ha a fanOn tulajdonság megváltozik:

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

Példa kitöltése

Ez a példa a szakasz alapelveit foglalja magában, beleértve a többszintű visszahívási függvények beágyazását is.

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

  });
});

Eszköz SDK-minták

Az Azure IoT SDK for Node.js a modulidentitás-ikerfeladatokat kezelő eszközalkalmazások munkamintáit tartalmazza. További információk:

• Modul identitás ikerpéldánya
• Modulteszt súgója
• Iker e2e-tesztek

Háttéralkalmazás létrehozása

Ez a szakasz bemutatja, hogyan hozhat létre egy háttéralkalmazást, amely lekéri a modulidentitás ikerpéldányát, és frissíti a kívánt tulajdonságokat.

Szolgáltatás SDK-csomag telepítése

Futtassa ezt a parancsot az Azure-iotHub fejlesztői gépen való telepítéséhez:

npm install azure-iothub --save

Beállításjegyzék-objektum létrehozása

A Beállításjegyzék-osztály minden olyan metódust elérhetővé tesz, amely egy háttéralkalmazás modulidentitás-ikerpéldányaival való interakcióhoz szükséges.

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

Csatlakozás az IoT Hubhoz

Háttérszolgáltatást az alábbi módszerekkel csatlakoztathat az IoT Hubhoz:

• Megosztott hozzáférési szabályzat
• Microsoft Entra

Csatlakozás megosztott hozzáférési szabályzattal

A fromConnectionString használatával csatlakozhat az IoT Hubhoz.

Az update ebben a szakaszban használt módszerhez a Service Connect megosztott hozzáférési szabályzatának engedélyére van szükség a kívánt tulajdonságok modulhoz való hozzáadásához. Paraméterként fromConnectionStringadjon meg egy olyan megosztott hozzáférési szabályzatot kapcsolati sztring, amely Service Connect-engedélyt tartalmaz. A megosztott hozzáférési szabályzatokról további információt az IoT Hub hozzáférésének szabályozása közös hozzáférésű jogosultságkódokkal című témakörben talál.

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

Csatlakozás a Microsoft Entra használatával

A Microsoft Entrát használó háttéralkalmazásnak sikeresen hitelesítenie kell és be kell szereznie egy biztonsági jogkivonat hitelesítő adatait, mielőtt csatlakozik az IoT Hubhoz. Ez a jogkivonat egy IoT Hub-kapcsolati metódusnak lesz átadva. A Microsoft Entra for IoT Hub beállításával és használatával kapcsolatos általános információkért tekintse meg az IoT Hubhoz való hozzáférés Szabályozása a Microsoft Entra ID használatával című témakört.

Az SDK-hitelesítés Node.js áttekintése:

• A felhasználói hitelesítés első lépései az Azure-ban
• Azure Identity-ügyfélkódtár JavaScripthez

A Microsoft Entra alkalmazás konfigurálása

Be kell állítania egy Microsoft Entra-alkalmazást, amely az előnyben részesített hitelesítési hitelesítő adatokhoz van konfigurálva. Az alkalmazás olyan paramétereket tartalmaz, mint az ügyfélkulcs, amelyeket a háttéralkalmazás használ a hitelesítéshez. Az elérhető alkalmazáshitelesítési konfigurációk a következők:

• Titkos ügyfélkód
• Tanúsítvány
• Összevont identitás hitelesítő adatai

A Microsoft Entra-alkalmazások adott szerepkör-engedélyeket igényelhetnek a végrehajtott műveletektől függően. Az IoT Hub ikerpéldány-közreműködője például az IoT Hub-eszközökhöz és modulikrekhez való olvasási és írási hozzáférés engedélyezéséhez szükséges. További információ: IoT Hub-hozzáférés kezelése Azure RBAC-szerepkör-hozzárendeléssel.

A Microsoft Entra-alkalmazások beállításáról további információt a rövid útmutatóban talál: Alkalmazás regisztrálása a Microsoft Identitásplatform.

Hitelesítés DefaultAzureCredential használatával

A Microsoft Entra segítségével a legegyszerűbben a DefaultAzureCredential használatával hitelesíthet egy háttéralkalmazást, de ajánlott egy másik módszert használni egy éles környezetben, beleértve egy adott TokenCredential vagy pared-down ChainedTokenCredentialmetódust is. Az egyszerűség kedvéért ez a szakasz a hitelesítést és az ügyfél titkos kódjának használatát DefaultAzureCredential ismerteti. A használat DefaultAzureCredentialelőnyeiről és hátrányairól további információt a JavaScripthez készült Azure Identity ügyfélkódtár hitelesítőadat-láncai című témakörben talál .

A DefaultAzureCredential különböző hitelesítési mechanizmusokat támogat, és meghatározza a megfelelő hitelesítőadat-típust a környezet alapján, amelyben végrehajtja. Több hitelesítő adattípust próbál meg egy sorrendben használni, amíg nem talál egy működő hitelesítő adatot.

A Microsoft Entra a következő csomagot igényli:

npm install --save @azure/identity

Ebben a példában a Microsoft Entra alkalmazásregisztrációs ügyfél titkos kódját, ügyfél-azonosítóját és bérlőazonosítóját hozzáadtuk a környezeti változókhoz. Ezek a környezeti változók az DefaultAzureCredential alkalmazás hitelesítésére szolgálnak. A sikeres Microsoft Entra-hitelesítés eredménye egy biztonsági jogkivonat hitelesítő adatai, amelyet egy IoT Hub-kapcsolati módszernek ad át.

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

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

Az eredményül kapott hitelesítő jogkivonat ezután átadható a FromTokenCredential-nak , hogy csatlakozzon az IoT Hubhoz minden olyan SDK-ügyfélhez, amely elfogadja a Microsoft Entra hitelesítő adatait:

• Registry
• Ügyfél
• JobClient

fromTokenCredential két paramétert igényel:

• Az Azure-szolgáltatás URL-címe – Az Azure-szolgáltatás URL-címének előtag nélküli https:// formátumban {Your Entra domain URL}.azure-devices.net kell lennie. Például: MyAzureDomain.azure-devices.net.
• Az Azure hitelesítőadat-jogkivonata

Ebben a példában az Azure-hitelesítő adatokat a rendszer a használatával szerzi be DefaultAzureCredential. A rendszer ezután az Azure-tartomány URL-címét és hitelesítő adatait adja meg Registry.fromTokenCredential az IoT Hubhoz való kapcsolat létrehozásához.

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

Kódminták

A Microsoft Entra szolgáltatáshitelesítés működő mintáit az Azure-identitásra vonatkozó példákban talál.

Modulidentitás ikerpéldányának lekérése és a kívánt tulajdonságok frissítése

Létrehozhat egy javítást, amely a modul identitási ikerpéldányának kívánt tulajdonságfrissítéseit tartalmazza.

Modulidentitás ikerpéldányának frissítése:

1. Hívja meg a getModuleTwint az ikereszköz-objektum lekéréséhez.

2. Formázzon egy javítást, amely tartalmazza a modulidentitás ikerpéldányának frissítését. A javítás JSON formátumban van formázva az ikerosztályban leírtak szerint. A háttérszolgáltatás-javítások a kívánt tulajdonságfrissítéseket tartalmazzák. További információ a javításformátumról: Címkék és tulajdonságok formátuma.

3. Hívja meg a frissítést , hogy frissítse a modul identitási ikerpéldányát a javítással.

Ebben a példában a modulidentitás ikerpéldánya lesz lekérve a következőhöz myDeviceId : és myModuleId. Ezután egy javítás lesz alkalmazva az információkat tartalmazó climate ikerpéldányokra.

// 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-minták

Az Azure IoT SDK for Node.js a modulidentitás-ikerfeladatokat kezelő szolgáltatásalkalmazások munkamintáit tartalmazza. További információk:

• Modul identitás ikerpéldánya
• Modulteszt súgója
• Iker e2e-tesztek