Get started with IoT Hub module identities and module identity twins

• Wymaga programu Visual Studio

Omówienie

This article describes how to use the Azure IoT SDK for .NET to create device and backend service application code for module identity twins.

Tworzenie aplikacji urządzenia

W tej sekcji opisano sposób używania kodu aplikacji urządzenia do wykonywania następujących czynności:

• Retrieve a module identity twin and examine reported properties
• Zaktualizuj zgłoszone właściwości bliźniaczej tożsamości modułu
• Create a module desired property update callback handler

Wymagany pakiet NuGet dla urządzenia

Aplikacje klienckie urządzeń napisane w języku C# wymagają pakietu NuGet Microsoft.Azure.Devices.Client .

Add these using statements to use the device library.

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

Nawiązywanie połączenia z urządzeniem

Klasa ModuleClient udostępnia wszystkie metody wymagane do interakcji z bliźniakami tożsamości modułu z urządzenia.

Connect to the device using the CreateFromConnectionString method with the module identity connection string.

Calling CreateFromConnectionString without a transport parameter connects using the default AMQP transport.

W tym przykładzie nawiąż połączenie z urządzeniem przy użyciu domyślnego transportu protokołu AMQP.

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

_moduleClient = ModuleClient.CreateFromConnectionString(ModuleConnectionString, null);

Retrieve a module identity twin and examine properties

Call GetTwinAsync to retrieve the current module identity twin properties into a Twin object.

This example retrieves and displays module identity twin properties in JSON format.

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

Update module identity twin reported properties

To update a twin reported property:

1. Tworzenie obiektu TwinCollection dla zgłaszanej aktualizacji właściwości
2. Aktualizowanie co najmniej jednej zgłoszonej właściwości w TwinCollection obiekcie
3. Użyj UpdateReportedPropertiesAsync, aby przesłać zmiany zgłaszanych właściwości do usługi IoT Hub.

Na przykład:

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

Create a desired property update callback handler

Pass the callback handler method name to SetDesiredPropertyUpdateCallbackAsync to create a desired property update callback handler that executes when a desired property is changed in the module identity twin.

Na przykład to wywołanie konfiguruje system, aby powiadomić metodę o nazwie OnDesiredPropertyChangedAsync za każdym razem, gdy zmieniono żądaną właściwość modułu.

await _moduleClient.SetDesiredPropertyUpdateCallbackAsync(OnDesiredPropertyChangedAsync, null);

The module identity twin properties are passed to the callback method as a TwinCollection and can be examined as KeyValuePair structures.

This example receives the desired property updates as a TwinCollection, then loops through and prints the KeyValuePair collection updates. After looping through the KeyValuePair collection, the code calls UpdateReportedPropertiesAsync to update the DateTimeLastDesiredPropertyChangeReceived reported property to keep the last updated time up to date.

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

Przykładowy moduł ZESTAWU SDK

The Azure IoT SDK for .NET provides working samples of device apps that handle module identity twin tasks. Aby uzyskać więcej informacji, zobacz:

• TwinSample
• Testy klienta urządzenia

Tworzenie aplikacji zaplecza

W tej sekcji opisano sposób odczytywania i aktualizowania pól tożsamości modułu.

The RegistryManager class exposes all methods required to create a backend application to interact with module identity twins from the service.

Wymagany pakiet usługi NuGet

Aplikacje usługi zaplecza wymagają pakietu NuGet Microsoft.Azure.Devices .

Add these using statements to use the service library.

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

Łączenie z usługą IoT Hub

Usługę zaplecza można połączyć z usługą IoT Hub przy użyciu następujących metod:

• Zasady dostępu współdzielonego
• Microsoft Entra

Nawiązywanie połączenia przy użyciu zasad dostępu współdzielonego

Połącz aplikację zaplecza z IoT hub za pomocą CreateFromConnectionString.

Metoda UpdateModuleAsync używana w tej sekcji wymaga uprawnienia zasad dostępu współdzielonego programu Service Connect w celu dodania żądanych właściwości do modułu. As a parameter to CreateFromConnectionString, supply a shared access policy connection string that includes Service Connect permission. Aby uzyskać więcej informacji na temat zasad dostępu współdzielonego, zobacz Kontrola dostępu do usługi IoT Hub przy użyciu sygnatur dostępu współdzielonego.

Na przykład:

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

Nawiązywanie połączenia przy użyciu usługi Microsoft Entra

Aplikacja zaplecza korzystająca z usługi Microsoft Entra musi pomyślnie uwierzytelnić się i uzyskać poświadczenia tokenu zabezpieczającego przed nawiązaniem połączenia z usługą IoT Hub. Ten token jest przekazywany do metody połączenia z hubem IoT. Aby uzyskać ogólne informacje na temat konfigurowania i używania usługi Microsoft Entra dla usługi IoT Hub, zobacz Kontrola dostępu do usługi IoT Hub przy użyciu identyfikatora Microsoft Entra.

Konfigurowanie aplikacji Microsoft Entra

Musisz skonfigurować aplikację Firmy Microsoft Entra skonfigurowaną dla preferowanych poświadczeń uwierzytelniania. Aplikacja zawiera parametry, takie jak klucz tajny klienta, który jest używany przez aplikację zaplecza do uwierzytelniania. Dostępne konfiguracje uwierzytelniania aplikacji to:

• Client secret
• Certyfikat
• Poświadczenie tożsamości federacyjnej

Aplikacje Firmy Microsoft Entra mogą wymagać określonych uprawnień roli w zależności od wykonywanych operacji. For example, IoT Hub Twin Contributor is required to enable read and write access to a IoT Hub device and module twins. Aby uzyskać więcej informacji, zobacz Zarządzanie dostępem do usługi IoT Hub, przypisując rolę RBAC na platformie Azure.

Aby uzyskać więcej informacji na temat konfigurowania aplikacji Microsoft Entra, zobacz Szybki start: rejestrowanie aplikacji przy użyciu Platforma tożsamości Microsoft.

Uwierzytelnij się przy użyciu DefaultAzureCredential

The easiest way to use Microsoft Entra to authenticate a backend application is to use DefaultAzureCredential, but it's recommended to use a different method in a production environment including a specific TokenCredential or pared-down ChainedTokenCredential. Dla uproszczenia w tej sekcji opisano uwierzytelnianie przy użyciu DefaultAzureCredential i tajnego klucza klienta. Aby uzyskać więcej informacji na temat zalet i wad korzystania z DefaultAzureCredential, zobacz Wskazówki dotyczące użycia DefaultAzureCredential.

DefaultAzureCredential obsługuje różne mechanizmy uwierzytelniania i określa odpowiedni typ poświadczeń na podstawie środowiska, w których jest wykonywany. Próbuje użyć wielu typów poświadczeń w kolejności, dopóki nie znajdzie działającego poświadczenia.

Microsoft Entra requires these NuGet packages and corresponding using statements:

• Azure.Core
• Azure.Identity

using Azure.Core;
using Azure.Identity;

W tym przykładzie tajny klucz klienta, identyfikator klienta i identyfikator dzierżawy zarejestrowanej aplikacji Microsoft Entra są dodawane do zmiennych środowiskowych. Te zmienne środowiskowe są używane przez DefaultAzureCredential program do uwierzytelniania aplikacji. Wynikiem pomyślnego uwierzytelnienia Microsoft Entra jest token zabezpieczający, który jest przekazywany do metody połączenia IoT Hub.

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

Rezultatowy TokenCredential może następnie zostać przekazany do metody łączenia z IoT Hub dla dowolnego klienta SDK, który akceptuje poświadczenia Microsoft Entra.

• JobClient
• RegistryManager
• DigitalTwinClient
• ServiceClient

W tym przykładzie TokenCredential zostaje przekazany do ServiceClient.Create w celu utworzenia obiektu połączenia ServiceClient.

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

W tym przykładzie TokenCredential jest przekazywane do RegistryManager.Create , aby utworzyć obiekt RegistryManager .

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

Przykład kodu

Aby zapoznać się z roboczym przykładem uwierzytelniania usługi Entra firmy Microsoft, zobacz Przykład uwierzytelniania opartego na rolach.

Odczytywanie i aktualizowanie pól tożsamości modułu

Call GetModuleAsync to retrieve current module identity twin fields into a Module object.

Klasa Module obejmuje properties, które odpowiadają sekcjom bliźniaka tożsamości modułu. Użyj właściwości klasy modułu, aby wyświetlić i zaktualizować pola tożsamości bliźniaczej modułu. Właściwości obiektu Module można użyć do zaktualizowania wielu pól przed zapisaniem tych aktualizacji na urządzeniu, korzystając z UpdateModuleAsync.

Po dokonaniu aktualizacji pól identyfikacyjnych modułu, wywołaj UpdateModuleAsync, aby zapisać aktualizacje pól obiektu z powrotem do urządzenia. Użyj logiki try i catch połączonej z obsługą błędów, aby wykryć niepoprawnie sformatowane błędy łatek z UpdateModuleAsync.

W tym przykładzie moduł jest tworzony jako obiekt Module, właściwość moduleLastActivityTime jest aktualizowana, a następnie moduł w usłudze IoT Hub jest aktualizowany przy użyciu polecenia 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);
}

Other module API

• GetModulesOnDeviceAsync — pobiera tożsamości modułu na urządzeniu
• RemoveModuleAsync — usuwa wcześniej zarejestrowany moduł z urządzenia

Przykład usługi SDK

The Azure IoT SDK for .NET provides a working sample of a service app that handles module identity twin tasks. For more information, see Registry Manager E2E Tests.

• Zalecane jest użycie języka Python w wersji 3.7 lub nowszej . Upewnij się, że używasz 32-bitowej lub 64-bitowej instalacji zgodnie z wymaganiami konfiguracji. Po wyświetleniu monitu podczas instalacji upewnij się, że język Python został dodany do zmiennej środowiskowej specyficznej dla platformy.

Omówienie

Ten artykuł opisuje, jak używać Azure IoT SDK for Python do tworzenia kodu aplikacji urządzeń i usług backendowych dla bliźniaków tożsamości modułu.

Instalowanie pakietów

Aby tworzyć aplikacje urządzeń, należy zainstalować bibliotekę azure-iot-device .

pip install azure-iot-device

Aby tworzyć aplikacje usługi zaplecza, należy zainstalować bibliotekę azure-iot-hub .

pip install azure-iot-hub

Biblioteka msrest służy do przechwytywania wyjątków HTTPOperationError.

pip install msrest

Tworzenie aplikacji urządzenia

W tej sekcji opisano sposób używania kodu aplikacji urządzenia do wykonywania następujących czynności:

• Retrieve a module identity twin and examine reported properties
• Update module identity twin reported properties
• Create a module identity twin desired property update callback handler

Instrukcje importu

Dodaj to import wyrażenie, aby użyć biblioteki urządzeń.

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

Nawiązywanie połączenia z urządzeniem

Klasa IoTHubModuleClient zawiera metody, których można użyć do pracy z bliźniaczymi reprezentacjami tożsamości modułu.

Aby połączyć aplikację z urządzeniem:

1. Wywołaj create_from_connection_string, aby dodać łańcuch połączenia identyfikacji modułu.
2. Wywołaj connect, aby połączyć klienta urządzenia z centralą Azure IoT Hub

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

Retrieve a module identity twin and examine properties

Wywołaj get_twin, aby uzyskać bliźniaka tożsamości modułu z usługi Azure IoT Hub. Informacje o bliźniakach są umieszczane w zmiennej, którą można zbadać.

Ten przykład pobiera bliźniaka urządzenia i używa polecenia print, aby wyświetlić bliźniaka urządzenia w formacie JSON.

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

Update module identity twin reported properties

You can apply a patch to update module identity twin reported properties in JSON format.

Aby zastosować poprawkę w celu zaktualizowania zgłoszonych właściwości:

1. Assign a reported property JSON patch to a variable.
2. Wywołaj patch_twin_reported_properties , aby zastosować poprawkę JSON do zgłoszonych właściwości.

Na przykład:

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

Create a module identity twin desired property update callback handler

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

W tym przykładzie skonfigurowano żądaną procedurę obsługi poprawek właściwości o nazwie twin_patch_handler.

Na przykład:

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

The twin_patch_handler receives and prints JSON desired property updates.

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

Przykłady urządzeń z zestawem SDK

The Azure IoT SDK for Python provides a working sample of device apps that handle module identity twin tasks:

• get_twin - Connect to a device and retrieve twin information.
• update_twin_reported_properties - Update twin reported properties.
• receive_twin_desired_properties - Receive and update desired properties.

Tworzenie aplikacji zaplecza

Ta sekcja opisuje, jak utworzyć aplikację zaplecza do pobierania i aktualizowania żądanych właściwości bliźniaczej tożsamości modułu.

Klasa IoTHubRegistryManager udostępnia wszystkie metody wymagane do utworzenia aplikacji backendowej umożliwiającej interakcję z bliźniakami tożsamości modułu z usługi.

Service import statements

Dodaj to import stwierdzenie, aby użyć biblioteki usługowej.

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

Nawiązywanie połączenia z centrum IoT

Usługę zaplecza można połączyć z usługą IoT Hub przy użyciu następujących metod:

• Zasady dostępu współdzielonego
• Microsoft Entra

Nawiązywanie połączenia przy użyciu zasad dostępu współdzielonego

Nawiąż połączenie z centrum IoT używając from_connection_string.

Metoda update_module_twin używana w tej sekcji wymaga uprawnienia zasad dostępu współdzielonego programu Service Connect w celu dodania żądanych właściwości do modułu. As a parameter to from_connection_string, supply a shared access policy connection string that includes Service Connect permission. Aby uzyskać więcej informacji na temat zasad dostępu współdzielonego, zobacz Kontrola dostępu do usługi IoT Hub przy użyciu sygnatur dostępu współdzielonego.

Na przykład:

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

Nawiązywanie połączenia przy użyciu usługi Microsoft Entra

Aplikacja zaplecza korzystająca z usługi Microsoft Entra musi pomyślnie uwierzytelnić się i uzyskać poświadczenia tokenu zabezpieczającego przed nawiązaniem połączenia z usługą IoT Hub. Ten token jest przekazywany do metody połączenia z IoT Hub. Aby uzyskać ogólne informacje na temat konfigurowania i używania usługi Microsoft Entra dla usługi IoT Hub, zobacz Kontrola dostępu do usługi IoT Hub przy użyciu identyfikatora Microsoft Entra.

Aby zapoznać się z omówieniem uwierzytelniania zestawu PYTHON SDK, zobacz Uwierzytelnianie aplikacji języka Python w usługach platformy Azure przy użyciu zestawu Azure SDK dla języka Python

Konfigurowanie aplikacji Microsoft Entra

Musisz skonfigurować aplikację Firmy Microsoft Entra skonfigurowaną dla preferowanych poświadczeń uwierzytelniania. Aplikacja zawiera parametry, takie jak klucz tajny klienta, który jest używany przez aplikację zaplecza do uwierzytelniania. Dostępne konfiguracje uwierzytelniania aplikacji to:

• Client secret
• Certyfikat
• Poświadczenie tożsamości federacyjnej

Aplikacje Firmy Microsoft Entra mogą wymagać określonych uprawnień roli w zależności od wykonywanych operacji. For example, IoT Hub Twin Contributor is required to enable read and write access to a IoT Hub device and module twins. Aby uzyskać więcej informacji, zobacz Zarządzanie dostępem do usługi IoT Hub, przypisując rolę RBAC na platformie Azure.

Aby uzyskać więcej informacji na temat konfigurowania aplikacji Microsoft Entra, zobacz Szybki start: rejestrowanie aplikacji przy użyciu Platforma tożsamości Microsoft.

Uwierzytelnij się przy użyciu DefaultAzureCredential

The easiest way to use Microsoft Entra to authenticate a backend application is to use DefaultAzureCredential, but it's recommended to use a different method in a production environment including a specific TokenCredential or pared-down ChainedTokenCredential. Dla uproszczenia w tej sekcji opisano uwierzytelnianie przy użyciu DefaultAzureCredential i tajnego klucza klienta. Aby uzyskać więcej informacji na temat zalet i wad korzystania z programu DefaultAzureCredential, zobacz Łańcuchy poświadczeń w bibliotece klienta tożsamości platformy Azure dla języka Python.

DefaultAzureCredential obsługuje różne mechanizmy uwierzytelniania i określa odpowiedni typ poświadczenia na podstawie środowiska, w którym jest wykonywana. Próbuje użyć wielu typów poświadczeń w kolejności, dopóki nie znajdzie działającego poświadczenia.

Microsoft Entra requires this import package and corresponding import statement:

pip install azure-identity

from azure.identity import DefaultAzureCredential

W tym przykładzie, tajny klucz klienta, identyfikator klienta i identyfikator dzierżawcy rejestracji aplikacji Microsoft Entra zostały dodane do zmiennych środowiskowych. Te zmienne środowiskowe są używane przez DefaultAzureCredential program do uwierzytelniania aplikacji. Wynikiem pomyślnego uwierzytelnienia Microsoft Entra jest token zabezpieczający, który jest przekazywany do metody połączenia IoT Hub.

from azure.identity import DefaultAzureCredential
credential = DefaultAzureCredential()

Wynikowy token dostępu AccessToken można następnie przekazać do from_token_credential w celu nawiązania połączenia z usługą IoT Hub dla dowolnego klienta zestawu SDK, który akceptuje poświadczenia firmy Microsoft Entra:

• IoTHubRegistryManager do utworzenia połączenia serwisowego z IoT Hub przy użyciu poświadczenia tokenu Entra.
• IoTHubJobManager
• DigitalTwinClient
• IoTHubHttpRuntimeManager
• IoTHubConfigurationManager

from_token_credential wymaga dwóch parametrów:

• Adres URL usługi platformy Azure — adres URL usługi platformy Azure powinien być w formacie {Your Entra domain URL}.azure-devices.net bez prefiksu https:// . Na przykład MyAzureDomain.azure-devices.net.
• Token poświadczeń platformy Azure

W tym przykładzie poświadczenia platformy Azure są uzyskiwane przy użyciu polecenia DefaultAzureCredential. Adres URL i poświadczenia usługi Azure są następnie dostarczane do IoTHubRegistryManager.from_token_credential, aby utworzyć połączenie z 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)

Przykłady kodu

Aby zapoznać się z roboczymi przykładami uwierzytelniania usługi Entra firmy Microsoft, zobacz Biblioteka Microsoft Authentication Library (MSAL) dla języka Python.

Retrieve and update module identity twin desired properties

Żądane właściwości można zaktualizować z poziomu aplikacji zaplecza przy użyciu update_module_twin.

To retrieve and update module identity twin desired properties:

1. Wywołaj get_module_twin, aby uzyskać bieżącą wersję bliźniaczego modułu identyfikacji.
2. Użyj klasy Twin, aby dodać żądane właściwości w formacie JSON.
3. Call update_module_twin to apply the patch to the device twin. You can also use replace_module_twin to replace desired properties and tags for a module identity twin.

W tym przykładzie żądana właściwość aktualizuje się z telemetryInterval 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" )

Przykład usługi SDK

The Azure IoT SDK for Python provides a working sample of a service app that handles device identity module twin tasks. Aby uzyskać więcej informacji, zobacz Test IoTHub Registry Manager.

• Wymaga Node.js w wersji 10.0.x lub nowszej

Omówienie

This article describes how to use the Azure IoT SDK for Node.js to create device and backend service application code for module identity twins.

Tworzenie aplikacji urządzenia

W tej sekcji opisano sposób użycia pakietu azure-iot-device w zestawie SDK usługi Azure IoT dla Node.js w celu utworzenia aplikacji urządzenia w celu:

• Retrieve a module identity twin and examine reported properties
• Update module identity reported twin properties
• Receive notice of module identity twin desired property changes

Pakiet azure-iot-device zawiera obiekty interfejsu z urządzeniami IoT. Klasa Twin zawiera obiekty specyficzne dla bliźniaków. W tej sekcji opisano kod klasy Client używany do odczytywania i zapisywania danych tożsamości bliźniaczej modułu urządzenia.

Instalowanie pakietu ZESTAWU SDK

Uruchom to polecenie, aby zainstalować zestaw SDK urządzenia azure-iot-device na maszynie dewelopera:

npm install azure-iot-device --save

Łączenie urządzenia z usługą IoT Hub

Aplikacja urządzenia może uwierzytelniać się w usłudze IoT Hub przy użyciu następujących metod:

• Klucz dostępu współdzielonego
• Certyfikat X.509

Uwierzytelnianie przy użyciu klucza dostępu współdzielonego

Wybieranie protokołu transportowego

Obiekt Client obsługuje następujące protokoły:

• Amqp
• Http - When using Http, the Client instance checks for messages from IoT Hub infrequently (a minimum of every 25 minutes).
• Mqtt
• MqttWs
• AmqpWs

Zainstaluj wymagane protokoły transportu na maszynie dewelopera.

Na przykład to polecenie instaluje Amqp protokół:

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

Aby uzyskać więcej informacji na temat różnic między obsługą protokołów MQTT, AMQP i HTTPS, zobacz Wskazówki dotyczące komunikacji między chmurą i urządzeniem i Wybieranie protokołu komunikacyjnego urządzenia.

Tworzenie obiektu klienta

Client Utwórz obiekt przy użyciu zainstalowanego pakietu.

Na przykład:

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

Tworzenie obiektu protokołu

Utwórz Protocol obiekt przy użyciu zainstalowanego pakietu transportowego.

W tym przykładzie przypisywany jest protokół AMQP:

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

Dodaj łańcuch połączenia urządzenia i protokół transportowy

Wywołaj metodę fromConnectionString, aby podać parametry połączenia urządzenia:

• connStr — ciąg połączenia modułu tożsamości centrum IoT.
• transportCtor — protokół transportowy.

W tym przykładzie użyto Amqp protokołu transportu:

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

Otwieranie połączenia z usługą IoT Hub

Użyj metody open, aby otworzyć połączenie między urządzeniem IoT i usługą IoT Hub.

Na przykład:

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

Uwierzytelnianie przy użyciu certyfikatu X.509

The X.509 certificate is attached to the device-to-IoT Hub connection transport.

Aby skonfigurować połączenie urządzenia z usługą IoT Hub przy użyciu certyfikatu X.509:

1. Wywołaj metodę fromConnectionString, aby dodać parametry połączenia modułu urządzenia lub tożsamości oraz typ transportu do Client obiektu. Dodaj x509=true do łącza ciągu, aby wskazać, że certyfikat został dodany do DeviceClientOptions. Na przykład:

   • Parametry połączenia urządzenia:

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

   • An identity module connection string:

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

2. Skonfiguruj zmienną JSON ze szczegółami certyfikatu i przekaż ją do elementu DeviceClientOptions.

3. Call setOptions to add an X.509 certificate and key (and optionally, passphrase) to the client transport.

4. Wywołaj otwórz, aby nawiązać połączenie między urządzeniem a usługą IoT Hub.

W tym przykładzie przedstawiono informacje o konfiguracji certyfikatu w zmiennej JSON. The certification configuration clientOptions are passed to setOptions, and the connection is opened using 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);

Aby uzyskać więcej informacji na temat uwierzytelniania certyfikatów, zobacz:

• Uwierzytelnianie tożsamości przy użyciu certyfikatów X.509
• Tworzenie i przekazywanie certyfikatów na potrzeby testowania

Przykład kodu

Aby zapoznać się z roboczym przykładem uwierzytelniania certyfikatu X.509 urządzenia, zobacz Simple sample device X.509 (Proste przykładowe urządzenie X.509).

Retrieve a module identity twin and examine reported properties

Aby pobrać bieżące informacje o tożsamości bliźniaczej modułu do obiektu Twin, wywołaj getTwin.

Device code can then access the module identity twin properties.

Na przykład:

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

Update module identity twin reported properties

Użyj aktualizacji , aby zaktualizować zgłaszane właściwości urządzenia. Dołącz poprawkę w formacie JSON jako pierwszy parametr i metodę wywołania zwrotnego stanu wykonywania funkcji jako drugi parametr metody .

In this example, a JSON-formatted module identity twin patch is stored in the patch variable. The patch contains a module identity twin connectivity update value of cellular. Patch i obsługa błędów są przekazywane do metody update. Jeśli wystąpi błąd, zostanie wyświetlony komunikat o błędzie konsoli.

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

Receive notice of module identity twin desired property changes

Create a module identity twin desired property update event listener that executes when a desired property is changed by passing the callback handler method name to twin.on.

Żądany nasłuchiwacz zdarzeń właściwości może przybierać następujące formy:

• Receive all patches with a single event handler
• Otrzymuj zdarzenia, gdy cokolwiek zmieni się w grupie właściwości.
• Otrzymaj zdarzenie dotyczące zmiany jednej właściwości

Receive all patches with a single event handler

Możesz stworzyć nasłuchiwacz, aby odbierać wszelkie pożądane zmiany właściwości.

Ten przykładowy kod generuje wszystkie właściwości odebrane z usługi.

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

Otrzymaj powiadomienie, jeśli cokolwiek się zmieni w ramach grupowania właściwości.

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

Na przykład:

1. Właściwości minTemperature i maxTemperature znajdują się w grupie właściwości o nazwie properties.desired.climate changes.

2. Aplikacja usługi zaplecza stosuje tę poprawkę do aktualizacji minTemperature i maxTemperature żądanych właściwości:

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

3. Ten kod konfiguruje odbiornik zdarzeń zmiany żądanej właściwości, który wyzwala wszelkie zmiany w properties.desired.climate grupie właściwości. Jeśli w tej grupie zostanie zmieniona żądana właściwość, zostaną wyświetlone komunikaty o minimalnych i maksymalnych zmianach temperatury w konsoli:

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

Otrzymaj zdarzenie dla pojedynczej zmiany właściwości.

Odbiornik można skonfigurować pod kątem zmiany pojedynczej właściwości. W tym przykładzie kod tego zdarzenia jest wykonywany tylko wtedy, gdy wartość logiczna fanOn jest częścią poprawki. Kod generuje nowy żądany fanOn stan za każdym razem, gdy usługa go zaktualizuje.

1. Aplikacja zaplecza stosuje tę żądaną poprawkę właściwości:

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

2. The listener triggers only when the fanOn property changes:

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

Kompletny przykład

This example encapsulates the principles of this section, including multi-level callback function nesting.

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

  });
});

Przykłady zestawu SDK urządzeń

The Azure IoT SDK for Node.js provides working samples of device apps that handle module identity twin tasks. Aby uzyskać więcej informacji, zobacz:

• Module Identity Twin
• Pomocnik testu modułu
• Twin e2e tests

Tworzenie aplikacji zaplecza

W tej sekcji opisano sposób utworzenia aplikacji zaplecza, która pobiera tożsamość bliźniaczą modułu i aktualizuje żądane właściwości.

Instalowanie pakietu zestawu SDK usługi

Uruchom to polecenie, aby zainstalować usługę azure-iothub na maszynie deweloperskiej:

npm install azure-iothub --save

Tworzenie obiektu rejestru

Klasa Registry uwidacznia wszystkie metody wymagane do interakcji z bliźniaczymi reprezentacjami tożsamości modułu z aplikacji zaplecza.

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

Nawiązywanie połączenia z centrum IoT

Usługę zaplecza można połączyć z usługą IoT Hub przy użyciu następujących metod:

• Zasady dostępu współdzielonego
• Microsoft Entra

Nawiązywanie połączenia przy użyciu zasad dostępu współdzielonego

Użyj polecenia fromConnectionString , aby nawiązać połączenie z centrum IoT.

Metoda update używana w tej sekcji wymaga uprawnienia zasad dostępu współdzielonego programu Service Connect w celu dodania żądanych właściwości do modułu. As a parameter to fromConnectionString, supply a shared access policy connection string that includes Service Connect permission. Aby uzyskać więcej informacji na temat zasad dostępu współdzielonego, zobacz Kontrola dostępu do usługi IoT Hub przy użyciu sygnatur dostępu współdzielonego.

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

Nawiązywanie połączenia przy użyciu usługi Microsoft Entra

Aplikacja zaplecza korzystająca z usługi Microsoft Entra musi pomyślnie uwierzytelnić się i uzyskać poświadczenia tokenu zabezpieczającego przed nawiązaniem połączenia z usługą IoT Hub. Token jest przekazywany do metody połączenia IoT Hub. Aby uzyskać ogólne informacje na temat konfigurowania i używania usługi Microsoft Entra dla usługi IoT Hub, zobacz Kontrola dostępu do usługi IoT Hub przy użyciu identyfikatora Microsoft Entra.

Aby zapoznać się z omówieniem uwierzytelniania zestawu NODE.JS SDK, zobacz:

• Wprowadzenie do uwierzytelniania użytkowników na platformie Azure
• Biblioteka klienta tożsamości platformy Azure dla języka JavaScript

Konfigurowanie aplikacji Microsoft Entra

Musisz skonfigurować aplikację Firmy Microsoft Entra skonfigurowaną dla preferowanych poświadczeń uwierzytelniania. Aplikacja zawiera parametry, takie jak klucz tajny klienta, który jest używany przez aplikację zaplecza do uwierzytelniania. Dostępne konfiguracje uwierzytelniania aplikacji to:

• Tajemnica klienta
• Certyfikat
• Poświadczenie tożsamości federacyjnej

Aplikacje Firmy Microsoft Entra mogą wymagać określonych uprawnień roli w zależności od wykonywanych operacji. For example, IoT Hub Twin Contributor is required to enable read and write access to a IoT Hub device and module twins. Aby uzyskać więcej informacji, zobacz Zarządzanie dostępem do usługi IoT Hub, przypisując rolę RBAC na platformie Azure.

Aby uzyskać więcej informacji na temat konfigurowania aplikacji Microsoft Entra, zobacz Szybki start: rejestrowanie aplikacji przy użyciu Platforma tożsamości Microsoft.

Uwierzytelnij się przy użyciu DefaultAzureCredential

The easiest way to use Microsoft Entra to authenticate a backend application is to use DefaultAzureCredential, but it's recommended to use a different method in a production environment including a specific TokenCredential or pared-down ChainedTokenCredential. Dla uproszczenia w tej sekcji opisano uwierzytelnianie przy użyciu DefaultAzureCredential i tajnego klucza klienta. Aby uzyskać więcej informacji na temat zalet i wad korzystania z usługi DefaultAzureCredential, zobacz Łańcuchy poświadczeń w bibliotece klienta tożsamości platformy Azure dla języka JavaScript

DefaultAzureCredential obsługuje różne mechanizmy uwierzytelniania i określa odpowiedni typ poświadczenia na podstawie środowiska, w którym jest wykonywana. Próbuje użyć wielu typów poświadczeń w kolejności, dopóki nie znajdzie działającego poświadczenia.

Firma Microsoft Entra wymaga tego pakietu:

npm install --save @azure/identity

W tym przykładzie tajny klucz klienta, identyfikator klienta i identyfikator dzierżawy rejestracji aplikacji Microsoft Entra zostały dodane do zmiennych środowiskowych. Te zmienne środowiskowe są używane przez DefaultAzureCredential program do uwierzytelniania aplikacji. Wynikiem pomyślnego uwierzytelnienia Microsoft Entra jest token zabezpieczający, który jest przekazywany do metody połączenia IoT Hub.

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

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

Wynikowy token poświadczeń można następnie przekazać do fromTokenCredential, aby połączyć się z IoT Hub dla dowolnego klienta SDK, który akceptuje poświadczenia Microsoft Entra.

• Rejestr
• Klient
• JobClient

fromTokenCredential wymaga dwóch parametrów:

• Adres URL usługi platformy Azure — adres URL usługi platformy Azure powinien być w formacie {Your Entra domain URL}.azure-devices.net bez prefiksu https:// . Na przykład MyAzureDomain.azure-devices.net.
• Token poświadczeń platformy Azure

W tym przykładzie poświadczenia platformy Azure są uzyskiwane przy użyciu polecenia DefaultAzureCredential. Następnie adres URL domeny platformy Azure i poświadczenia są podawane do Registry.fromTokenCredential w celu utworzenia połączenia z usługą 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);

Przykłady kodu

Aby zapoznać się z działającymi przykładami działania uwierzytelniania usługi Microsoft Entra, zobacz Przykłady tożsamości usługi Azure.

Pobierz bliźniaka tożsamości modułu i zaktualizuj pożądane właściwości

Możesz utworzyć łatkę, która zawiera oczekiwane aktualizacje właściwości dla tożsamości modułu bliźniaczego.

To update a module identity twin:

1. Wywołaj getModuleTwin, aby pobrać obiekt Twin urządzenia.

2. Sformatuj łatkę, która zawiera aktualizację bliźniaka tożsamości modułu. Poprawka jest formatowana w formacie JSON zgodnie z opisem w klasie Twin. Poprawka usługi zaplecza zawiera żądane aktualizacje właściwości. Aby uzyskać więcej informacji na temat formatu poprawek, zobacz Format tagów i właściwości.

3. Call update to update the module identity twin with the patch.

W tym przykładzie, bliźniak tożsamości modułu jest pobierany dla myDeviceId i myModuleId. Then a patch is applied to the twins that contains 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');
    });
  }
});

Przykłady zestawu SDK usługi

SDK Azure IoT dla Node.js zapewnia działające przykłady aplikacji usługowych obsługujących zadania związane z podwójnym tożsamością modułów. Aby uzyskać więcej informacji, zobacz:

• Module Identity Twin
• Pomocnik testu modułu
• Twin e2e tests