Get started with IoT Hub module identities and module identity twins

• Requires Visual Studio

Descrição geral

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

Criar um aplicativo de dispositivo

Esta seção descreve como usar o código do aplicativo de dispositivo para:

• Retrieve a module identity twin and examine reported properties
• Update reported module identity twin properties
• Criar um manipulador de callback para atualização das propriedades desejadas do módulo

Pacote NuGet do dispositivo necessário

Os aplicativos cliente de dispositivo escritos em C# exigem o pacote NuGet Microsoft.Azure.Devices.Client.

Adicione estas using instruções para usar a biblioteca de dispositivos.

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

Ligar a um dispositivo

The ModuleClient class exposes all methods required to interact with module identity twins from the device.

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

A chamada CreateFromConnectionString sem um parâmetro de transporte se conecta usando o transporte AMQP padrão.

Este exemplo se conecta ao dispositivo usando o transporte AMQP padrão.

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.

Este exemplo recupera e exibe propriedades gêmeas de identidade do módulo no formato JSON.

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. Create a TwinCollection object for the reported property update
2. Atualizar uma ou mais propriedades relatadas dentro do TwinCollection objeto
3. Use UpdateReportedPropertiesAsync para enviar as alterações nas propriedades relatadas para o serviço de hub IoT

Por exemplo:

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.

Por exemplo, essa chamada configura o sistema para notificar um método chamado OnDesiredPropertyChangedAsync sempre que uma propriedade de módulo desejada é alterada.

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

Exemplo de módulo SDK

O SDK do Azure IoT para .NET fornece exemplos funcionais de aplicativos de dispositivo que lidam com tarefas gêmeas de identidade de módulo. Para obter mais informações, consulte:

• TwinSample
• Testes de cliente de dispositivo

Criar um aplicativo de back-end

Esta seção descreve como ler e atualizar campos de identidade do módulo.

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

Pacote de serviço NuGet necessário

As aplicações de serviço de back-end exigem o pacote NuGet Microsoft.Azure.Devices.

Adicione as seguintes using instruções para usar a biblioteca de serviço.

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

Connect to IoT Hub

Você pode conectar um serviço de back-end ao Hub IoT usando os seguintes métodos:

• Política de acesso partilhado
• Microsoft Entra

Conectar-se usando uma política de acesso compartilhado

Conecte um aplicativo de back-end ao hub IoT usando CreateFromConnectionString.

O UpdateModuleAsync método usado nesta seção requer a permissão da política de acesso compartilhado do Service Connect para adicionar as propriedades desejadas a um módulo. Como parâmetro para CreateFromConnectionString, forneça uma cadeia de conexão de uma política de acesso partilhado que inclua a permissão Service Connect. Para obter mais informações sobre políticas de acesso compartilhado, consulte Controlar o acesso ao Hub IoT com assinaturas de acesso compartilhado.

Por exemplo:

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

Conectar-se usando o Microsoft Entra

Uma aplicação de back-end que utiliza o Microsoft Entra deve autenticar-se e obter com sucesso uma credencial de token de segurança antes de se conectar ao Hub IoT. Esse token é passado para um método de conexão do Hub IoT. Para obter informações gerais sobre como configurar e usar o Microsoft Entra para Hub IoT, consulte Controlar o acesso ao Hub IoT usando a ID do Microsoft Entra.

Configurar o aplicativo Microsoft Entra

Você deve configurar um aplicativo Microsoft Entra configurado para sua credencial de autenticação preferida. O aplicativo contém parâmetros como segredo do cliente que são usados pelo aplicativo back-end para autenticar. As configurações de autenticação de aplicativo disponíveis são:

• Segredo do cliente
• Certificado
• Credencial de identidade federada

Os aplicativos Microsoft Entra podem exigir permissões de função específicas, dependendo das operações que estão sendo executadas. For example, IoT Hub Twin Contributor is required to enable read and write access to a IoT Hub device and module twins. Para obter mais informações, consulte Gerenciar o acesso ao Hub IoT usando a atribuição de função RBAC do Azure.

Para obter mais informações sobre como configurar um aplicativo Microsoft Entra, consulte Guia de início rápido: registrar um aplicativo com a plataforma de identidade da Microsoft.

Autenticar usando DefaultAzureCredential

A maneira mais fácil de usar o Microsoft Entra para autenticar uma aplicação de back-end é usar DefaultAzureCredential, mas é recomendável usar um método diferente num ambiente de produção, incluindo um método específico TokenCredential ou um método reduzido ChainedTokenCredential. Para simplificar, esta seção descreve o uso da DefaultAzureCredential autenticação e o segredo do cliente. Para obter mais informações sobre os prós e contras de usar DefaultAzureCredential, consulte Orientações de uso para DefaultAzureCredential.

DefaultAzureCredential suporta diferentes mecanismos de autenticação e determina o tipo de credencial apropriado com base no ambiente em que está sendo executado. Tenta usar vários tipos de credenciais sequencialmente até encontrar uma credencial válida.

Microsoft Entra requires these NuGet packages and corresponding using statements:

• Azure.Core
• Azure.Identity

using Azure.Core;
using Azure.Identity;

Neste exemplo, o segredo do cliente de registro do aplicativo Microsoft Entra, a ID do cliente e a ID do locatário são adicionados às variáveis de ambiente. Essas variáveis de ambiente são usadas por DefaultAzureCredential para autenticar o aplicativo. The result of a successful Microsoft Entra authentication is a security token credential that is passed to an IoT Hub connection method.

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

O TokenCredential resultante pode ser passado para um método de conexão ao IoT Hub para qualquer cliente SDK que aceite credenciais da Microsoft Entra.

• JobClient
• RegistryManager
• DigitalTwinClient
• ServiceClient

Neste exemplo, o TokenCredential é passado para ServiceClient.Create para criar um objeto de conexão ServiceClient .

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

Neste exemplo, o TokenCredential é passado para RegistryManager.Create para criar um objeto RegistryManager.

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

Exemplo de código

Para obter um exemplo prático de autenticação de serviço do Microsoft Entra, consulte Exemplo de autenticação baseada em função.

Ler e atualizar campos de identidade do módulo

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

The Module class includes properties that correspond to sections of a module identity twin. Use as propriedades da classe Module para exibir e atualizar os campos gêmeos de identidade do módulo. Você pode usar as propriedades do objeto Module para atualizar vários campos antes de gravar as atualizações no dispositivo usando UpdateModuleAsync.

After making module identity twin field updates, call UpdateModuleAsync to write Module object field updates back to a device. Use try and catch logic coupled with an error handler to catch incorrectly formatted patch errors from UpdateModuleAsync.

Este exemplo recupera um módulo em um Module objeto, atualiza a moduleLastActivityTime propriedade e, em seguida, atualiza o módulo no Hub IoT usando UpdateModuleAsync.

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

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

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

API de outro módulo

• GetModulesOnDeviceAsync - Recupera as identidades do módulo em um dispositivo
• RemoveModuleAsync - Exclui um módulo registrado anteriormente de um dispositivo

Exemplo de serviço SDK

O SDK do Azure IoT para .NET fornece uma amostra funcional de um aplicativo de serviço que lida com tarefas gêmeas de identidade de módulo. Para obter mais informações, consulte Testes E2E do Gestor de Registos.

• Python versão 3.7 ou posterior é recomendado. Certifique-se de que utiliza a instalação de 32 ou 64 bits, conforme exigido pela sua configuração. Quando lhe for pedido durante a instalação, confirme que adiciona Python à variável de ambiente específica da sua plataforma.

Descrição geral

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

Instalar pacotes

A biblioteca azure-iot-device deve ser instalada para criar aplicativos de dispositivo.

pip install azure-iot-device

A biblioteca azure-iot-hub deve ser instalada para criar aplicativos de serviço de back-end.

pip install azure-iot-hub

A biblioteca msrest é usada para capturar exceções HTTPOperationError.

pip install msrest

Criar um aplicativo de dispositivo

Esta seção descreve como usar o código do aplicativo de dispositivo para:

• 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

Declarações de importação

Adicione esta import instrução para usar a biblioteca de dispositivos.

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

Ligar a um dispositivo

A classe IoTHubModuleClient contém métodos que podem ser usados para trabalhar com gêmeos de identidade de módulo.

Para conectar um aplicativo a um dispositivo:

1. Call create_from_connection_string to add the module identity connection string
2. Call connect to connect the device client to an 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

Call get_twin to retrieve the module identity twin from the Azure IoT Hub service. As informações gêmeas são colocadas em uma variável que pode ser examinada.

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

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

Update module identity twin reported properties

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

Para aplicar um patch para atualizar as propriedades relatadas:

1. Atribua um patch JSON de propriedade relatada a uma variável.
2. Invoque patch_twin_reported_properties para aplicar o patch JSON às propriedades relatadas.

Por exemplo:

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

Este exemplo configura um manipulador de patch de propriedades desejadas chamado twin_patch_handler.

Por exemplo:

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

O twin_patch_handler recebe e imprime as atualizações de propriedade desejadas do JSON.

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

Exemplos de dispositivos SDK

O SDK do Azure IoT para Python fornece um exemplo funcional de aplicativos de dispositivo que lidam com tarefas gêmeas de identidade de módulo:

• 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.

Criar um aplicativo de back-end

This section describes how to create a backend application to retrieve and update module identity twin desired properties.

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

Declarações de importação de serviço

Adicione esta import instrução para usar a biblioteca de serviços.

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

Conectar-se ao hub IoT

Você pode conectar um serviço de back-end ao Hub IoT usando os seguintes métodos:

• Política de acesso partilhado
• Microsoft Entra

Conectar-se usando uma política de acesso compartilhado

Conecte-se ao hub IoT usando from_connection_string.

O update_module_twin método usado nesta seção requer a permissão da política de acesso compartilhado do Service Connect para adicionar as propriedades desejadas a um módulo. Como parâmetro para from_connection_string, forneça uma cadeia de conexão de uma política de acesso partilhado que inclua a permissão Service Connect. Para obter mais informações sobre políticas de acesso compartilhado, consulte Controlar o acesso ao Hub IoT com assinaturas de acesso compartilhado.

Por exemplo:

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

Conectar-se usando o Microsoft Entra

Uma aplicação de back-end que utiliza o Microsoft Entra deve autenticar-se e obter com sucesso uma credencial de token de segurança antes de se conectar ao Hub IoT. Esse token é passado para um método de conexão do Hub IoT. Para obter informações gerais sobre como configurar e usar o Microsoft Entra para Hub IoT, consulte Controlar o acesso ao Hub IoT usando a ID do Microsoft Entra.

Para obter uma visão geral da autenticação do SDK do Python, consulte Autenticar aplicativos Python nos serviços do Azure usando o SDK do Azure para Python

Configurar o aplicativo Microsoft Entra

Você deve configurar um aplicativo Microsoft Entra configurado para sua credencial de autenticação preferida. O aplicativo contém parâmetros como segredo do cliente que são usados pelo aplicativo back-end para autenticar. As configurações de autenticação de aplicativo disponíveis são:

• Segredo do cliente
• Certificado
• Credencial de identidade federada

Os aplicativos Microsoft Entra podem exigir permissões de função específicas, dependendo das operações que estão sendo executadas. For example, IoT Hub Twin Contributor is required to enable read and write access to a IoT Hub device and module twins. Para obter mais informações, consulte Gerenciar o acesso ao Hub IoT usando a atribuição de função RBAC do Azure.

Para obter mais informações sobre como configurar um aplicativo Microsoft Entra, consulte Guia de início rápido: registrar um aplicativo com a plataforma de identidade da Microsoft.

Autenticar usando DefaultAzureCredential

A maneira mais fácil de usar o Microsoft Entra para autenticar uma aplicação de back-end é usar DefaultAzureCredential, mas é recomendável usar um método diferente num ambiente de produção, incluindo um método específico TokenCredential ou um método reduzido ChainedTokenCredential. Para simplificar, esta seção descreve o uso da DefaultAzureCredential autenticação e o segredo do cliente. Para obter mais informações sobre os prós e contras do uso de DefaultAzureCredential, consulte Cadeias de Credenciais na Biblioteca de Cliente Azure Identity para Python.

DefaultAzureCredential dá suporte a diferentes mecanismos de autenticação e determina o tipo de credencial apropriado com base no ambiente em que está sendo executado. Tenta usar vários tipos de credenciais sequencialmente até encontrar uma credencial válida.

O Microsoft Entra requer este pacote de importação e a instrução correspondente import :

pip install azure-identity

from azure.identity import DefaultAzureCredential

Neste exemplo, o segredo do cliente de registro do aplicativo Microsoft Entra, a ID do cliente e a ID do locatário foram adicionados às variáveis de ambiente. Essas variáveis de ambiente são usadas por DefaultAzureCredential para autenticar o aplicativo. The result of a successful Microsoft Entra authentication is a security token credential that is passed to an IoT Hub connection method.

from azure.identity import DefaultAzureCredential
credential = DefaultAzureCredential()

O resultado AccessToken pode então ser passado para from_token_credential para se conectar ao Hub IoT para qualquer cliente SDK que aceite credenciais do Microsoft Entra.

• IoTHubRegistryManager para criar uma conexão de serviço com o Hub IoT usando uma credencial de token Entra.
• IoTHubJobManager
• DigitalTwinClient
• IoTHubHttpRuntimeManager
• IoTHubConfigurationManager

from_token_credential requer dois parâmetros:

• A URL do serviço do Azure - A URL do serviço do Azure deve estar no formato {Your Entra domain URL}.azure-devices.net sem um https:// prefixo. Por exemplo, MyAzureDomain.azure-devices.net.
• O token de autenticação do Azure

Neste exemplo, a credencial do Azure é obtida usando DefaultAzureCredential. A URL e a credencial do serviço do Azure são fornecidas a IoTHubRegistryManager.from_token_credential para criar a ligação ao Hub IoT.

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)

Amostras de código

Para obter exemplos de trabalho da autenticação do serviço Microsoft Entra, consulte Microsoft Authentication Library (MSAL) for Python.

Retrieve and update module identity twin desired properties

Você pode atualizar as propriedades desejadas de um aplicativo de back-end usando update_module_twin.

To retrieve and update module identity twin desired properties:

1. Call get_module_twin to get the current version of the module identity twin.
2. Use a classe Twin para adicionar as propriedades desejadas no formato 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.

Este exemplo atualiza a telemetryInterval propriedade desejada para 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" )

Exemplo de serviço SDK

O SDK do Azure IoT para Python fornece uma amostra funcional de um aplicativo de serviço que lida com tarefas gêmeas do módulo de identidade do dispositivo. Para obter mais informações, consulte Test IoTHub Registry Manager.

• Requer Node.js versão 10.0.x ou posterior

Descrição geral

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.

Criar um aplicativo de dispositivo

Esta seção descreve como usar o pacote azure-iot-device no SDK do Azure IoT para Node.js criar um aplicativo de dispositivo para:

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

O pacote azure-iot-device contém objetos que fazem interface com dispositivos IoT. A classe Twin inclui objetos específicos para gêmeos. This section describes Client class code that is used to read and write device module identity twin data.

Instalar o pacote SDK

Execute este comando para instalar o SDK do dispositivo azure-iot-device em sua máquina de desenvolvimento:

npm install azure-iot-device --save

Ligar um dispositivo ao Hub IoT

Um aplicativo de dispositivo pode se autenticar com o Hub IoT usando os seguintes métodos:

• Chave de acesso partilhada
• Certificado X.509

Autenticar usando uma chave de acesso compartilhada

Escolha um protocolo de transporte

O Client objeto suporta estes protocolos:

• Amqp
• Http - Ao usar Http, a instância Client verifica mensagens do Hub IoT de forma pouco frequente (no mínimo a cada 25 minutos).
• Mqtt
• MqttWs
• AmqpWs

Instale os protocolos de transporte necessários em sua máquina de desenvolvimento.

Por exemplo, este comando instala o Amqp protocolo:

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

Para obter mais informações sobre as diferenças entre o suporte a MQTT, AMQP e HTTPS, consulte Orientação de comunicações entre a nuvem e o dispositivo e Escolha um protocolo de comunicação de dispositivo.

Criar um objeto cliente

Crie um Client objeto usando o pacote instalado.

Por exemplo:

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

Criar um objeto de protocolo

Crie um Protocol objeto usando um pacote de transporte instalado.

Este exemplo atribui o protocolo AMQP:

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

Adicionar a cadeia de conexão do dispositivo e o protocolo de transporte

Chame fromConnectionString para fornecer parâmetros de conexão do dispositivo:

• connStr - A cadeia de conexão do módulo de identidade do hub IoT.
• transportCtor - O protocolo de transporte.

Este exemplo usa o Amqp protocolo de transporte:

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

Abra a conexão com o Hub IoT

Use o método open para abrir uma conexão entre um dispositivo IoT e o Hub IoT.

Por exemplo:

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

Autenticar usando um certificado X.509

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

Para configurar uma conexão de dispositivo para Hub IoT usando um certificado X.509:

1. Chame fromConnectionString para adicionar a cadeia de conexão do dispositivo ou do módulo de identidade e o Client tipo de transporte ao objeto. Adicione x509=true à cadeia de conexão para indicar que um certificado foi adicionado ao DeviceClientOptions. Por exemplo:

   • Uma cadeia de conexão de dispositivo :

     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. Configure uma variável JSON com detalhes do certificado e passe-a para DeviceClientOptions.

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

4. Call open to open the connection from the device to IoT Hub.

Este exemplo mostra informações de configuração de certificado em uma variável JSON. A configuração clientOptions de certificação é passada para setOptions, e a conexão é aberta usando 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);

Para obter mais informações sobre autenticação de certificado, consulte:

• Autenticar identidades com certificados X.509
• Criar e carregar certificados para teste

Exemplo de código

Para obter um exemplo funcional de autenticação de certificado X.509 do dispositivo, consulte Dispositivo de exemplo simples X.509.

Retrieve a module identity twin and examine reported properties

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

Device code can then access the module identity twin properties.

Por exemplo:

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

Use atualizar para atualizar as propriedades relatadas do dispositivo. Include a JSON-formatted patch as the first parameter and function execution status callback method as the second parameter to the method.

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. O patch e o manipulador de erros são passados para o update método. Se houver um erro, uma mensagem de erro do console será exibida.

// 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.

The desired property event listener can take the following forms:

• Receba todos os patches com um único manipulador de eventos
• Receber um evento se ocorrer alguma alteração dentro de um agrupamento de propriedades
• Receive an event for a single property change

Receba todos os patches com um único manipulador de eventos

You can create a listener to receive any desired property change.

Este código de exemplo exibe todas as propriedades recebidas do serviço.

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

Receber um evento se ocorrer alguma alteração dentro de um agrupamento de propriedades

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

Por exemplo:

1. As minTemperature propriedades e maxTemperature estão localizadas sob um agrupamento de propriedades chamado properties.desired.climate changes.

2. Um aplicativo de serviço de back-end aplica esse patch para atualizar minTemperature e maxTemperature as propriedades desejadas.

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

3. This code sets up a desired property change event listener that triggers for any changes within the properties.desired.climate property grouping. Se houver uma alteração de propriedade desejada dentro desse grupo, as mensagens de alteração de temperatura mínima e máxima serão exibidas no console:

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

Receive an event for a single property change

You can set up a listener for a single property change. Neste exemplo, o código para esse evento é executado somente se o fanOn valor booleano fizer parte do patch. O código produz o novo estado desejado fanOn sempre que o serviço o atualiza.

1. A backend application applies this desired property patch:

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

Exemplo completo

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

  });
});

Exemplos de SDK de dispositivo

O SDK do Azure IoT para Node.js fornece exemplos funcionais de aplicativos de dispositivo que lidam com tarefas gêmeas de identidade de módulo. Para obter mais informações, consulte:

• Module Identity Twin
• Auxiliar de teste de módulo
• Twin e2e tests

Criar um aplicativo de back-end

This section describes how to create a backend application that retrieves a module identity twin and updates desired properties.

Instalar pacote SDK de serviço

Execute este comando para instalar o azure-iothub em sua máquina de desenvolvimento:

npm install azure-iothub --save

Criar um objeto Registry

The Registry class exposes all methods required to interact with module identity twins from a backend application.

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

Conectar-se ao hub IoT

Você pode conectar um serviço de back-end ao Hub IoT usando os seguintes métodos:

• Política de acesso partilhado
• Microsoft Entra

Conectar-se usando uma política de acesso compartilhado

Use fromConnectionString to connect to IoT hub.

O update método usado nesta seção requer a permissão da política de acesso compartilhado do Service Connect para adicionar as propriedades desejadas a um módulo. Como parâmetro para fromConnectionString, forneça uma cadeia de conexão de uma política de acesso partilhado que inclua a permissão Service Connect. Para obter mais informações sobre políticas de acesso compartilhado, consulte Controlar o acesso ao Hub IoT com assinaturas de acesso compartilhado.

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

Conectar-se usando o Microsoft Entra

Uma aplicação de back-end que utiliza o Microsoft Entra deve autenticar-se e obter com sucesso uma credencial de token de segurança antes de se conectar ao Hub IoT. Esse token é passado para um método de conexão do Hub IoT. Para obter informações gerais sobre como configurar e usar o Microsoft Entra para Hub IoT, consulte Controlar o acesso ao Hub IoT usando a ID do Microsoft Entra.

Para obter uma visão geral da autenticação Node.js SDK, consulte:

• Introdução à autenticação de usuário no Azure
• Biblioteca de cliente do Azure Identity para JavaScript

Configurar o aplicativo Microsoft Entra

Você deve configurar um aplicativo Microsoft Entra configurado para sua credencial de autenticação preferida. O aplicativo contém parâmetros como segredo do cliente que são usados pelo aplicativo back-end para autenticar. As configurações de autenticação de aplicativo disponíveis são:

• Segredo do cliente
• Certificado
• Credencial de identidade federada

Os aplicativos Microsoft Entra podem exigir permissões de função específicas, dependendo das operações que estão sendo executadas. For example, IoT Hub Twin Contributor is required to enable read and write access to a IoT Hub device and module twins. Para obter mais informações, consulte Gerenciar o acesso ao Hub IoT usando a atribuição de função RBAC do Azure.

Para obter mais informações sobre como configurar um aplicativo Microsoft Entra, consulte Guia de início rápido: registrar um aplicativo com a plataforma de identidade da Microsoft.

Autenticar usando DefaultAzureCredential

A maneira mais fácil de usar o Microsoft Entra para autenticar uma aplicação de back-end é usar DefaultAzureCredential, mas é recomendável usar um método diferente num ambiente de produção, incluindo um método específico TokenCredential ou um método reduzido ChainedTokenCredential. Para simplificar, esta seção descreve o uso da DefaultAzureCredential autenticação e o segredo do cliente. Para obter mais informações sobre os prós e contras do uso de DefaultAzureCredential, consulte Cadeias de credenciais na biblioteca de cliente do Azure Identity para JavaScript

DefaultAzureCredential dá suporte a diferentes mecanismos de autenticação e determina o tipo de credencial apropriado com base no ambiente em que está sendo executado. Tenta usar vários tipos de credenciais sequencialmente até encontrar uma credencial válida.

O Microsoft Entra requer este pacote:

npm install --save @azure/identity

Neste exemplo, o segredo do cliente de registro do aplicativo Microsoft Entra, a ID do cliente e a ID do locatário foram adicionados às variáveis de ambiente. Essas variáveis de ambiente são usadas por DefaultAzureCredential para autenticar o aplicativo. The result of a successful Microsoft Entra authentication is a security token credential that is passed to an IoT Hub connection method.

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

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

O token de credencial resultante pode ser passado para fromTokenCredential para se conectar ao Hub IoT para qualquer cliente SDK que aceite credenciais do Microsoft Entra:

• Registo
• Cliente
• JobClient

fromTokenCredential requer dois parâmetros:

• A URL do serviço do Azure - A URL do serviço do Azure deve estar no formato {Your Entra domain URL}.azure-devices.net sem um https:// prefixo. Por exemplo, MyAzureDomain.azure-devices.net.
• O token de autenticação do Azure

Neste exemplo, a credencial do Azure é obtida usando DefaultAzureCredential. O URL e as credenciais do domínio do Azure são fornecidas a Registry.fromTokenCredential para criar a conexão com o 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);

Amostras de código

Para obter exemplos de trabalho da autenticação do serviço Microsoft Entra, consulte Exemplos de identidade do Azure.

Retrieve a module identity twin and update desired properties

You can create a patch that contains desired property updates for a module identity twin.

To update a module identity twin:

1. Chame getModuleTwin para recuperar o objeto Twin do dispositivo.

2. Format a patch that contains the module identity twin update. O patch é formatado em JSON conforme descrito na classe Twin. A backend service patch contains desired property updates. Para obter mais informações sobre o formato do patch, consulte Formato de etiquetas e propriedades.

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

In this example, the module identity twin is retrieved for myDeviceId and 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');
    });
  }
});

Exemplos de SDK de serviço

O SDK do Azure IoT para Node.js fornece exemplos funcionais de aplicativos de serviço que lidam com tarefas gêmeas de identidade de módulo. Para obter mais informações, consulte:

• Module Identity Twin
• Auxiliar de teste de módulo
• Twin e2e tests