Introdução aos dispositivos duplos

Use o SDK de dispositivo do Hub IoT do Azure e o SDK de serviço para desenvolver aplicativos que lidam com tarefas gêmeas de dispositivo comuns. Gêmeos de dispositivo são documentos JSON que armazenam informações de estado do dispositivo, incluindo metadados, configurações e condições. O Hub IoT mantém um gêmeo digital de dispositivo para cada dispositivo que se conecta a ele.

Você pode usar gêmeos de dispositivo para:

Armazene metadados do dispositivo a partir do back-end da solução
Relatar informações de estado atual, como recursos e condições disponíveis, por exemplo, o método de conectividade usado, do aplicativo do dispositivo
Sincronizar o estado de fluxos de trabalho de longa execução, como atualizações de firmware e configuração, entre um aplicativo de dispositivo e um aplicativo back-end
Consultar os metadados, a configuração ou o estado do dispositivo

Para obter mais informações sobre réplicas de dispositivo, incluindo quando utilizar réplicas de dispositivo, consulte Compreender e usar réplicas de dispositivo no IoT Hub.

Nota

Os recursos descritos neste artigo estão disponíveis somente na camada padrão do Hub IoT. Para obter mais informações sobre as camadas básica e padrão/gratuita do Hub IoT, consulte Escolha a camada e o tamanho certos do Hub IoT para sua solução.

Este artigo mostra como desenvolver dois tipos de aplicativos:

Os aplicativos de dispositivo podem lidar com solicitações para atualizar as propriedades desejadas e responder com alterações nas propriedades relatadas.
Os aplicativos de serviço podem atualizar etiquetas de gémeo de dispositivo, definir novas propriedades desejadas e consultar dispositivos com base em valores do gémeo de dispositivo.

Nota

Este artigo destina-se a complementar exemplos de SDKs do Azure IoT referenciados neste artigo. Você pode usar ferramentas SDK para criar aplicativos de dispositivo e back-end.

Pré-requisitos

Um hub IoT
Um dispositivo registado
Se o seu aplicativo usa o protocolo MQTT, certifique-se de que a porta 8883 esteja aberta no firewall. O protocolo MQTT se comunica pela porta 8883. Essa porta pode estar bloqueada em alguns ambientes de rede corporativa e educacional. Para obter mais informações e maneiras de contornar esse problema, consulte Conectando-se ao Hub IoT (MQTT).

Requer o Visual Studio

Descrição geral

Este artigo descreve como usar o SDK do Azure IoT para .NET para criar código de aplicativo de serviço de dispositivo e back-end para gêmeos de dispositivo.

Criar um aplicativo de dispositivo

As aplicações de dispositivos podem ler e gravar propriedades do gémeo relatadas e ser notificadas sobre as alterações nas propriedades desejadas do gémeo que são definidas por uma aplicação de back-end ou pelo Hub IoT.

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

Recuperar um dispositivo gêmeo e examinar as propriedades relatadas
Atualizar propriedades de geminação reportadas do dispositivo
Criar um manipulador de retorno de chamada para atualização de propriedade desejada

Pacote NuGet do dispositivo necessário

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

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

using Microsoft.Azure.Devices.Client;

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

Importante

Este artigo inclui etapas para conectar um dispositivo usando uma assinatura de acesso compartilhado, também chamada de autenticação de chave simétrica. Esse método de autenticação é conveniente para testes e avaliações, mas autenticar um dispositivo usando certificados X.509 é uma abordagem mais segura. Para saber mais, consulte Práticas recomendadas de segurança para soluções > IoT Segurança de conexão.

Autenticar usando uma chave de acesso compartilhada

A classe DeviceClient expõe todos os métodos necessários para interagir com gêmeos de dispositivo do dispositivo.

Conecte-se ao dispositivo usando o método CreateFromConnectionString juntamente com a cadeia de conexão do dispositivo e o protocolo de transporte de conexão.

O CreateFromConnectionStringparâmetro de protocolo de transporte TransportType suporta os seguintes protocolos de transporte:

Mqtt
Mqtt_WebSocket_Only
Mqtt_Tcp_Only
Amqp
Amqp_WebSocket_Only
Amqp_Tcp_Only

O Http1 protocolo não é suportado para atualizações gêmeas de dispositivo.

Este exemplo se conecta a um dispositivo usando o Mqtt protocolo de transporte.

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

static string DeviceConnectionString = "{IoT hub device connection string}";
static _deviceClient = null;
_deviceClient = DeviceClient.CreateFromConnectionString(DeviceConnectionString, 
   TransportType.Mqtt);

Autenticar usando um certificado X.509

Para conectar um dispositivo ao Hub IoT usando um certificado X.509:

Use DeviceAuthenticationWithX509Certificate para criar um objeto que contenha informações de dispositivo e certificado. DeviceAuthenticationWithX509Certificate é passado como o segundo parâmetro para DeviceClient.Create (etapa 2).
Use DeviceClient.Create para conectar o dispositivo ao Hub IoT usando um certificado X.509.

Neste exemplo, as informações do dispositivo e do certificado são preenchidas authDeviceAuthenticationWithX509Certificate no objeto que é passado para DeviceClient.Create.

Este exemplo mostra os valores dos parâmetros de entrada do certificado como variáveis locais para maior clareza. Em um sistema de produção, armazene parâmetros de entrada confidenciais em variáveis de ambiente ou em outro local de armazenamento mais seguro. Por exemplo, use Environment.GetEnvironmentVariable("HOSTNAME") para ler a variável de ambiente do nome de host.

RootCertPath = "~/certificates/certs/sensor-thl-001-device.cert.pem";
Intermediate1CertPath = "~/certificates/certs/sensor-thl-001-device.intermediate1.cert.pem";
Intermediate2CertPath = "~/certificates/certs/sensor-thl-001-device.intermediate2.cert.pem";
DevicePfxPath = "~/certificates/certs/sensor-thl-001-device.cert.pfx";
DevicePfxPassword = "1234";
DeviceName = "MyDevice";
HostName = "xxxxx.azure-devices.net";

var chainCerts = new X509Certificate2Collection();
chainCerts.Add(new X509Certificate2(RootCertPath));
chainCerts.Add(new X509Certificate2(Intermediate1CertPath));
chainCerts.Add(new X509Certificate2(Intermediate2CertPath));
using var deviceCert = new X509Certificate2(DevicePfxPath, DevicePfxPassword);
using var auth = new DeviceAuthenticationWithX509Certificate(DeviceName, deviceCert, chainCerts);

using var deviceClient = DeviceClient.Create(
    HostName,
    auth,
    TransportType.Amqp);

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

Amostras de código

Para obter exemplos funcionais de autenticação de certificado X.509 do dispositivo, consulte:

Recuperar um dispositivo gêmeo e examinar propriedades

Chame GetTwinAsync para recuperar as propriedades gêmeas do dispositivo atual. Há muitas propriedades de objeto Twin que você pode usar para acessar áreas específicas dos Twin dados JSON, incluindo Properties, Status, Tagse Version.

Este exemplo recupera propriedades gêmeas de dispositivo e imprime os valores gêmeos no formato JSON.

Console.WriteLine("Retrieving twin...");
Twin twin = await _deviceClient.GetTwinAsync();
Console.WriteLine("\tInitial twin value received:");
Console.WriteLine($"\t{twin.ToJson()}");

Atualizar propriedades gêmeas do dispositivo relatadas

Para atualizar uma propriedade reportada de um gêmeo:

Criar um objeto TwinCollection para a atualização de propriedade relatada
Atualizar uma ou mais propriedades relatadas dentro do TwinCollection objeto
Usar UpdateReportedPropertiesAsync para transmitir as alterações de propriedades relatadas para o serviço de IoT Hub

Por exemplo:

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

Criar um manipulador de retorno de chamada de atualização de propriedade desejada

Crie um manipulador de callback para atualização de propriedades desejadas que seja executado quando uma propriedade desejada for alterada no gêmeo digital do dispositivo, passando o nome do método do manipulador de callback para SetDesiredPropertyUpdateCallbackAsync.

Por exemplo, essa chamada configura o sistema para notificar um método chamadoOnDesiredPropertyChangedAsync sempre que uma propriedade desejada é alterada.

await _deviceClient.SetDesiredPropertyUpdateCallbackAsync(OnDesiredPropertyChangedAsync, null);

As propriedades gêmeas são passadas para o método de retorno de chamada como um TwinCollection e podem ser examinadas como KeyValuePair estruturas.

Este exemplo recebe as atualizações de propriedade desejadas como um TwinCollection, em seguida, faz um loop e imprime as atualizações da KeyValuePair coleção. Depois de percorrer a coleção KeyValuePair, o código chama UpdateReportedPropertiesAsync para atualizar a propriedade relatada DateTimeLastDesiredPropertyChangeReceived e manter a hora da última atualização atualizada.

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

Exemplo de dispositivo SDK

O SDK do Azure IoT para .NET fornece uma amostra funcional de um aplicativo de dispositivo que lida com tarefas gêmeas de dispositivo. Para obter mais informações, consulte TwinSample.

Criar um aplicativo de back-end

Um aplicativo de back-end se conecta a um dispositivo por meio do Hub IoT e pode ler as propriedades desejadas e relatadas do dispositivo, gravar as propriedades desejadas do dispositivo e executar consultas de dispositivo.

Esta seção descreve como criar código de aplicativo de back-end para:

Ler e atualizar campos gêmeos do dispositivo
Criar uma consulta dupla de dispositivo

A classe RegistryManager expõe todos os métodos necessários para criar um aplicativo de back-end para interagir com gêmeos de dispositivo do serviço.

Adicionar pacote NuGet de serviço

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

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

Importante

Este artigo inclui etapas para se conectar a um serviço usando uma assinatura de acesso compartilhado. Esse método de autenticação é conveniente para teste e avaliação, mas autenticar em um serviço com ID do Microsoft Entra ou identidades gerenciadas é uma abordagem mais segura. Para saber mais, consulte Práticas recomendadas de segurança para soluções > de IoT Segurança na nuvem.

Conectar-se usando uma política de acesso compartilhado

Conecte um aplicativo back-end a um dispositivo usando CreateFromConnectionString. Seu aplicativo precisa da permissão de conexão de serviço para modificar as propriedades desejadas de um gêmeo de dispositivo e precisa de permissão de leitura do registro para consultar o registro de identidade. Não há nenhuma política de acesso compartilhado padrão que contenha apenas essas duas permissões, portanto, você precisa criar uma se uma ainda não existir. Forneça esta cadeia de conexão de política de acesso compartilhado como um parâmetro para fromConnectionString. Para obter mais informações sobre políticas de acesso compartilhado, consulte Controlar o acesso ao Hub IoT com assinaturas de acesso compartilhado.

using Microsoft.Azure.Devices;
static RegistryManager registryManager;
static string connectionString = "{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 com sucesso e obter 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. Por exemplo, é necessário um IoT Hub Twin Contributor para permitir o acesso de leitura e gravação a um dispositivo do Hub IoT e aos gémeos de módulo. 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 forma mais fácil de utilizar o Microsoft Entra para a autenticação de uma aplicação de back-end é usar DefaultAzureCredential, mas é recomendável usar um método diferente em um ambiente de produção, incluindo uma credencial específica TokenCredential ou uma versão simplificada 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 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. Ele tenta usar vários tipos de credenciais numa ordem até encontrar uma credencial válida.

O Microsoft Entra requer estes pacotes NuGet e instruções correspondentes using :

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. O resultado de uma autenticação bem-sucedida do Microsoft Entra é uma credencial de token de segurança que é passada para um método de ligação ao 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();

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

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 o 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 gêmeos do dispositivo

Você pode recuperar campos gêmeos do dispositivo atual em um objeto Twin chamando GetTwinAsync.

A Twin classe inclui propriedades que correspondem a cada seção de um dispositivo gêmeo. Use as propriedades de classe para exibir e atualizar campos gêmeos Twin do dispositivo. Você pode usar as propriedades do Twin objeto para atualizar vários campos gêmeos antes de gravar as atualizações no dispositivo usando UpdateTwinAsynco .

Depois de fazer atualizações de campo duplo, chame UpdateTwinAsync para gravar Twin atualizações de campo de objeto em um dispositivo. Use try e catch lógica juntamente com um manipulador de erros para detetar erros de patch formatados incorretamente do UpdateTwinAsync.

Ler e atualizar tags gêmeas do dispositivo

Use a propriedade Tags gêmeas do dispositivo para ler e gravar informações da tag do dispositivo.

Atualizar tags usando um objeto gêmeo

Este exemplo cria um patch de location marca, atribui-o Twin ao objeto usando a Tags propriedade e, em seguida, aplica o patch usando UpdateTwinAsync.

// Retrieve the device twin
var twin = await registryManager.GetTwinAsync("myDeviceId");

// Create the tag patch
var tagspatch =
   @"{
   tags: {
         location: {
            region: 'US',
            plant: 'Redmond43'
         }
   }
}";

// Assign the patch to the Twin object
twin.Tags["location"] = tagspatch;

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

Atualizar tags usando uma cadeia de caracteres JSON

Você pode criar e aplicar um patch de atualização de informações gêmeas de dispositivo formatado em JSON. O Hub IoT analisa e aplica o patch se ele estiver formatado corretamente.

Este exemplo chama GetTwinAsync para recuperar os campos gêmeos do dispositivo atual em um Twin objeto, cria um patch formatado em tag JSON com informações de região e localização da planta e, em seguida, chama UpdateTwinAsync para aplicar o patch para atualizar o gêmeo do dispositivo. Uma mensagem de erro será exibida se UpdateTwinAsync falhar.

// Retrieve the device twin
var twin = await registryManager.GetTwinAsync("myDeviceId");

// Create the JSON tags patch
var patch =
   @"{
      tags: {
            location: {
               region: 'US',
               plant: 'Redmond43'
            }
      }
   }";
// Apply the patch to update the device twin tags
try
{
   await registryManager.UpdateTwinAsync(twin.DeviceId, patch, twin.ETag);
}
catch (Exception e)
{
   console.WriteLine("Twin update failed.", e.Message);
}

Visualizar e atualizar propriedades desejadas gêmeas

Use a propriedade TwinProperties.Desired do dispositivo twin para ler e gravar as informações da propriedade desejada do dispositivo. Atualize as propriedades gêmeas Desired usando um patch formatado em JSON.

Este exemplo chama GetTwinAsync para recuperar os campos gêmeos do dispositivo atual em um Twin objeto, atualiza a propriedade desejada do gêmeo speed e, em seguida, chama UpdateTwinAsync para aplicar o Twin objeto para atualizar o gêmeo do dispositivo.

// Retrieve the device twin
var twin = await registryManager.GetTwinAsync("myDeviceId");

twin.Properties.Desired["speed"] = "type: '5G'";
await registryManager.UpdateTwinAsync(twin.DeviceId, twin, twin.ETag);

Outros métodos de atualização dupla

Você também pode aplicar atualizações gêmeas usando estes métodos SDK:

Chame ReplaceTwinAsync para substituir todo o dispositivo gêmeo.
Chame UpdateTwins2Async para atualizar uma lista de gêmeos criados anteriormente dentro do sistema.

Criar uma consulta dupla de dispositivo

Esta seção demonstra duas consultas gêmeas de dispositivo. As consultas gêmeas de dispositivo são consultas semelhantes a SQL que retornam um conjunto de resultados de gêmeos de dispositivo.

Para criar uma consulta gêmea de dispositivo, chame CreateQuery para enviar uma consulta SQL de gêmeos e obter uma interface IQuery . Opcionalmente, você pode chamar CreateQuery com um segundo parâmetro para especificar um número máximo de itens por página.

Faça a chamada ao método GetNextAsTwinAsync ou GetNextAsJsonAsync quantas vezes forem necessárias para recuperar todos os resultados twin.

GetNextAsTwinAsync para obter o próximo resultado paginado como objetos Twin.
GetNextAsJsonAsync para recuperar o próximo resultado paginado como cadeias de caracteres JSON.

A IQuery interface inclui uma propriedade booleana HasMoreResults que você pode usar para verificar se há mais resultados gêmeos para buscar.

Esta consulta de exemplo seleciona apenas os gêmeos de dispositivos localizados na planta Redmond43 .

var query = registryManager.CreateQuery(
"SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'", 100);
var twinsInRedmond43 = await query.GetNextAsTwinAsync();
Console.WriteLine("Devices in Redmond43: {0}", 
string.Join(", ", twinsInRedmond43.Select(t => t.DeviceId)));

Esta consulta de exemplo refina a primeira consulta para selecionar apenas os dispositivos que também estão conectados através de uma rede celular.

query = registryManager.CreateQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' AND properties.reported.connectivity.type = 'cellular'", 100);
var twinsInRedmond43UsingCellular = await query.GetNextAsTwinAsync();
Console.WriteLine("Devices in Redmond43 using cellular network: {0}", 
string.Join(", ", twinsInRedmond43UsingCellular.Select(t => t.DeviceId)));

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 dispositivo. Para obter mais informações, consulte Exemplo do Gerenciador do Registro.

Requer Java SE Development Kit 8. Certifique-se de selecionar Java 8 sob suporte de longo prazo para aceder aos downloads para JDK 8.

Descrição geral

Este artigo descreve como usar o Azure IoT SDK para Java para criar código de aplicação para dispositivos e serviços de backend para réplicas de dispositivos.

Criar um aplicativo de dispositivo

As aplicações de dispositivo podem ler e gravar as propriedades relatadas dos gêmeos digitais e ser notificadas sobre as alterações das propriedades desejadas dos gêmeos digitais definidas por uma aplicação de backend ou IoT Hub.

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

Recuperar e visualizar um dispositivo twin
Atualizar propriedades gêmeas do dispositivo relatadas
Subscrever as alterações de propriedade desejadas

A classe DeviceClient expõe todos os métodos necessários para interagir com gêmeos digitais a partir do dispositivo.

Importante

Instruções de importação de dispositivo

Use as seguintes instruções de importação de dispositivo para acessar o SDK do Azure IoT para Java.

import com.microsoft.azure.sdk.iot.device.*;
import com.microsoft.azure.sdk.iot.device.DeviceTwin.*;

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

Importante

Autenticar usando uma chave de acesso compartilhada

Para conectar um dispositivo ao Hub IoT:

Use IotHubClientProtocol para escolher um protocolo de transporte. Por exemplo:
```
IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;
```

Use o DeviceClient construtor para adicionar a cadeia de conexão primária do dispositivo e o protocolo.

String connString = "{IoT hub device connection string}";
DeviceClient client = new DeviceClient(connString, protocol);

Use open para conectar o dispositivo ao hub IoT. Se o cliente já estiver aberto, o método não fará nada.
```
client.open(true);
```

Autenticar usando um certificado X.509

Para conectar um dispositivo ao Hub IoT usando um certificado X.509:

Crie o objeto SSLContext usando buildSSLContext.
Adicione a SSLContext informação a um objeto ClientOptions.
Chame DeviceClient usando as ClientOptions informações para criar a conexão do dispositivo ao Hub IoT.

Este exemplo mostra os valores dos parâmetros de entrada do certificado como variáveis locais para maior clareza. Em um sistema de produção, armazene parâmetros de entrada confidenciais em variáveis de ambiente ou em outro local de armazenamento mais seguro. Por exemplo, use Environment.GetEnvironmentVariable("PUBLICKEY") para ler uma variável de ambiente que contém a cadeia de caracteres de um certificado de chave pública.

private static final String publicKeyCertificateString =
        "-----BEGIN CERTIFICATE-----\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "-----END CERTIFICATE-----\n";

//PEM encoded representation of the private key
private static final String privateKeyString =
        "-----BEGIN EC PRIVATE KEY-----\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "-----END EC PRIVATE KEY-----\n";

SSLContext sslContext = SSLContextBuilder.buildSSLContext(publicKeyCertificateString, privateKeyString);
ClientOptions clientOptions = ClientOptions.builder().sslContext(sslContext).build();
DeviceClient client = new DeviceClient(connString, protocol, clientOptions);

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

Amostras de código

Para obter exemplos funcionais de autenticação de certificado X.509 do dispositivo, consulte:

Recuperar e visualizar um dispositivo twin

Depois de abrir a conexão do cliente, chame getTwin para recuperar as propriedades gêmeas atuais em um Twin objeto.

Por exemplo:

private static Twin twin;
System.out.println("Getting current twin");
twin = client.getTwin();
System.out.println("Received current twin:");
System.out.println(twin);

Atualizar propriedades relatadas do gêmeo digital do dispositivo

Depois de recuperar o gémeo atual, pode começar a fazer atualizações às propriedades reportadas. Você também pode fazer atualizações de propriedade relatadas sem obter o gêmeo atual, desde que tenha a versão correta das propriedades relatadas. Se você enviar propriedades relatadas e receber um erro de "falha na pré-condição", a versão das propriedades relatadas estará desatualizada. Nesse caso, obtenha a versão mais recente ligando getTwin novamente.

Para atualizar as propriedades relatadas:

Chame getReportedProperties para obter as propriedades relatadas do 'twin' num TwinCollection como objeto.
Use put para atualizar uma propriedade relatada dentro do TwinCollection objeto. Chame put para cada atualização de propriedade relatada.
Use updateReportedProperties para aplicar o grupo de propriedades relatadas que foram atualizadas usando o put método.

Por exemplo:

TwinCollection reportedProperties = twin.getReportedProperties();

int newTemperature = new Random().nextInt(80);
reportedProperties.put("HomeTemp(F)", newTemperature);
System.out.println("Updating reported property \"HomeTemp(F)\" to value " + newTemperature);

ReportedPropertiesUpdateResponse response = client.updateReportedProperties(reportedProperties);
System.out.println("Successfully set property \"HomeTemp(F)\" to value " + newTemperature);

Chame subscribeToDesiredProperties para subscrever às alterações de propriedade desejadas. Este cliente recebe uma chamada de retorno com um objeto Twin cada vez que uma propriedade pretendida é atualizada. Este retorno de chamada contém ou o conjunto completo de propriedades desejadas, ou apenas a propriedade desejada atualizada, dependendo de como a propriedade desejada foi alterada.

Este exemplo subscreve as alterações de propriedade desejadas. Todas as alterações de propriedade desejadas são passadas para um manipulador chamado DesiredPropertiesUpdatedHandler.

client.subscribeToDesiredProperties(new DesiredPropertiesUpdatedHandler(), null);

Neste exemplo, o manipulador de retorno de chamada para a alteração da DesiredPropertiesUpdatedHandler propriedade desejada chama getDesiredProperties para recuperar as alterações de propriedade e, em seguida, imprime as propriedades gémeas atualizadas.

  private static class DesiredPropertiesUpdatedHandler implements DesiredPropertiesCallback
  {
      @Override
      public void onDesiredPropertiesUpdated(Twin desiredPropertyUpdateTwin, Object context)
      {
          if (twin == null)
          {
              // No need to care about this update because these properties will be present in the twin retrieved by getTwin.
              System.out.println("Received desired properties update before getting current twin. Ignoring this update.");
              return;
          }

          // desiredPropertyUpdateTwin.getDesiredProperties() contains all the newly updated desired properties as well as the new version of the desired properties
          twin.getDesiredProperties().putAll(desiredPropertyUpdateTwin.getDesiredProperties());
          twin.getDesiredProperties().setVersion(desiredPropertyUpdateTwin.getDesiredProperties().getVersion());
          System.out.println("Received desired property update. Current twin:");
          System.out.println(twin);
      }
  }

Exemplo de dispositivo SDK

O SDK do Azure IoT para Java inclui um exemplo de trabalho para testar os conceitos de aplicativo de dispositivo descritos neste artigo. Para obter mais informações, consulte Exemplo de gêmeo de dispositivo.

Criar um aplicativo de back-end

Esta seção descreve como criar um aplicativo de back-end que:

Atualiza as etiquetas gêmeas do dispositivo
Consulta dispositivos usando filtros nas tags e propriedades

A ServiceClientclasse DeviceTwin contém métodos que os serviços podem usar para acessar gêmeos de dispositivo.

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

Use as seguintes instruções de importação de serviço para acessar o SDK do Azure IoT para Java.

import com.microsoft.azure.sdk.iot.service.devicetwin.*;
import com.microsoft.azure.sdk.iot.service.exceptions.IotHubException;

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

Importante

Conectar-se usando uma política de acesso compartilhado

Use um construtor DeviceTwin para criar a conexão com o hub IoT. O DeviceTwin objeto lida com a comunicação com seu hub IoT.

Seu aplicativo precisa da permissão de conexão de serviço para modificar as propriedades desejadas de um gêmeo digital do dispositivo e precisa da permissão de leitura do registro para consultar o registro de identidade. Não há nenhuma política de acesso compartilhado padrão que contenha apenas essas duas permissões, portanto, você precisa criar uma se uma ainda não existir. Forneça esta cadeia de conexão de política de acesso compartilhado como um parâmetro para fromConnectionString. Para obter mais informações sobre políticas de acesso compartilhado, consulte Controlar o acesso ao Hub IoT com assinaturas de acesso compartilhado.

O objeto DeviceTwinDevice representa o gêmeo de dispositivo com suas propriedades e tags.

Por exemplo:

public static final String iotHubConnectionString = "{Shared access policy connection string}";
public static final String deviceId = "myDeviceId";
public static final String region = "US";
public static final String plant = "Redmond43";

// Get the DeviceTwin and DeviceTwinDevice objects
DeviceTwin twinClient = new DeviceTwin(iotHubConnectionString);
DeviceTwinDevice device = new DeviceTwinDevice(deviceId);

Conectar-se usando o Microsoft Entra

Uma aplicação de back-end que utiliza o Microsoft Entra deverá autenticar-se com sucesso e obter uma credencial de token de segurança antes de se ligar 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 com o SDK do Java, consulte Autenticação do Azure com Java e Azure Identity.

Para simplificar, esta seção se concentra na descrição da autenticação usando o segredo do cliente.

Configurar o aplicativo Microsoft Entra

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. Por exemplo, é necessário o Contribuidor Gêmeo do IoT Hub para habilitar o acesso de leitura e escrita a um dispositivo do IoT Hub e os gêmeos de módulo. 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 utilizar um método diferente num ambiente de produção, incluindo um específico TokenCredential ou reduzido ChainedTokenCredential. Para obter mais informações sobre os prós e contras do uso de DefaultAzureCredential, consulte Cadeias de credenciais na biblioteca de clientes do Azure Identity para Java.

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. Ele tenta usar vários tipos de credenciais numa certa ordem até encontrar uma credencial válida.

Você pode autenticar as credenciais do aplicativo Microsoft Entra usando DefaultAzureCredentialBuilder. Salve parâmetros de conexão, como tenantID secreto do cliente, clientID e valores de segredo do cliente como variáveis ambientais. Uma vez TokenCredential criado, passe-o para ServiceClient ou outro construtor como o parâmetro 'credential'.

Neste exemplo, DefaultAzureCredentialBuilder tenta autenticar uma conexão da lista descrita em DefaultAzureCredential. O resultado de uma autenticação bem-sucedida do Microsoft Entra é uma credencial de token de segurança, que é passada a um construtor como o ServiceClient.

TokenCredential defaultAzureCredential = new DefaultAzureCredentialBuilder().build();

Autenticar usando ClientSecretCredentialBuilder

Você pode usar ClientSecretCredentialBuilder para criar uma credencial usando informações de segredo do cliente. Se bem-sucedido, esse método retorna um TokenCredential que pode ser passado para ServiceClient ou outro construtor como o parâmetro 'credential'.

Neste exemplo, os valores de segredo do cliente de registro do aplicativo Microsoft Entra, ID do cliente e ID do locatário foram adicionados às variáveis de ambiente. Essas variáveis de ambiente são usadas para criar a credencial por ClientSecretCredentialBuilder.

string clientSecretValue = System.getenv("AZURE_CLIENT_SECRET");
string clientID = System.getenv("AZURE_CLIENT_ID");
string tenantID = System.getenv("AZURE_TENANT_ID");

TokenCredential credential =
     new ClientSecretCredentialBuilder()
          .tenantId(tenantID)
          .clientId(clientID)
          .clientSecret(clientSecretValue)
          .build();

Outras classes de autenticação

O Java SDK também inclui estas classes que autenticam um aplicativo de back-end com o Microsoft Entra:

Amostras de código

Para obter exemplos de funcionamento da autenticação de serviço do Microsoft Entra, consulte Exemplo de autenticação baseada em função.

Atualizar campos gêmeos do dispositivo

Para atualizar os campos gêmeos do dispositivo:

Use getTwin para recuperar os campos gêmeos do dispositivo atual

Este exemplo recupera e imprime os campos gêmeos do dispositivo:

// Get the device twin from IoT Hub
System.out.println("Device twin before update:");
twinClient.getTwin(device);
System.out.println(device);

Usar um HashSet objeto para add um grupo de pares de tags gêmeas
Use setTags para adicionar um grupo de pares de tags de um tags objeto a um DeviceTwinDevice objeto

Use updateTwin para atualizar o gêmeo no hub IoT

Este exemplo atualiza as etiquetas do modelo digital (gêmeo) de região e fábrica para um modelo digital de dispositivo (gêmeo):

// Update device twin tags if they are different
// from the existing values
String currentTags = device.tagsToString();
if ((!currentTags.contains("region=" + region) && !currentTags.contains("plant=" + plant))) {

// Create the tags and attach them to the DeviceTwinDevice object
Set<Pair> tags = new HashSet<Pair>();
tags.add(new Pair("region", region));
tags.add(new Pair("plant", plant));
device.setTags(tags);

// Update the device twin in IoT Hub
System.out.println("Updating device twin");
twinClient.updateTwin(device);
}

// Retrieve and display the device twin with the tag values from IoT Hub
System.out.println("Device twin after update:");
twinClient.getTwin(device);
System.out.println(device);

Criar uma consulta dupla de dispositivo

Esta seção demonstra duas consultas gêmeas de dispositivo. Consultas sobre gêmeos de dispositivos são consultas semelhantes ao SQL que retornam um conjunto de resultados de gêmeos de dispositivos.

A classe Query contém métodos que podem ser usados para criar consultas no estilo SQL para réplicas, tarefas, tarefas de dispositivos ou dados brutos no Hub IoT.

Para criar uma consulta de dispositivo:

Use createSqlQuery para criar a consulta SQL de gêmeos
Use queryTwin para executar a consulta
Use hasNextDeviceTwin para verificar se há outro dispositivo gêmeo no conjunto de resultados
Use getNextDeviceTwin para recuperar o próximo dispositivo gêmeo do conjunto de resultados

As consultas de exemplo a seguir retornam um máximo de 100 dispositivos.

Esta consulta de exemplo seleciona apenas as gêmeas digitais dos dispositivos localizados na fábrica Redmond43.

// Query the device twins in IoT Hub
System.out.println("Devices in Redmond:");

// Construct the query
SqlQuery sqlQuery = SqlQuery.createSqlQuery("*", SqlQuery.FromType.DEVICES, "tags.plant='Redmond43'", null);

// Run the query, returning a maximum of 100 devices
Query twinQuery = twinClient.queryTwin(sqlQuery.getQuery(), 100);
while (twinClient.hasNextDeviceTwin(twinQuery)) {
  DeviceTwinDevice d = twinClient.getNextDeviceTwin(twinQuery);
  System.out.println(d.getDeviceId());
}

Esta consulta de exemplo refina a primeira consulta para selecionar apenas os dispositivos que também estão conectados através de uma rede celular.

System.out.println("Devices in Redmond using a cellular network:");

// Construct the query
sqlQuery = SqlQuery.createSqlQuery("*", SqlQuery.FromType.DEVICES, "tags.plant='Redmond43' AND properties.reported.connectivityType = 'cellular'", null);

// Run the query, returning a maximum of 100 devices
twinQuery = twinClient.queryTwin(sqlQuery.getQuery(), 3);
while (twinClient.hasNextDeviceTwin(twinQuery)) {
  DeviceTwinDevice d = twinClient.getNextDeviceTwin(twinQuery);
  System.out.println(d.getDeviceId());
}

Exemplo de serviço SDK

O SDK do Azure IoT para Java fornece uma amostra funcional de um aplicativo de serviço que lida com tarefas gêmeas de dispositivo. Para obter mais informações, consulte Exemplo de gêmeo de dispositivo.

Python SDK - 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

Este artigo descreve como usar o SDK do Azure IoT para Python para criar código de aplicação para dispositivos e serviços de back-end para gêmeos digitais de dispositivos.

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

Criar um aplicativo de dispositivo

Os aplicativos de dispositivo podem ler e gravar propriedades de gêmeos relatados e ser notificados sobre as alterações de propriedades gêmeas desejadas definidas por um aplicativo de back-end ou Hub IoT.

A classe IoTHubDeviceClient contém métodos que podem ser usados para trabalhar com gêmeos de dispositivo.

Esta seção descreve como criar código de aplicativo de dispositivo que:

Recupera um dispositivo gêmeo e examina as propriedades relatadas
Propriedades gêmeas do dispositivo relatadas pelo patch

Declaração de importação de dispositivo

Adicione este código para importar as IoTHubDeviceClient funções do SDK azure.iot.device.

from azure.iot.device import IoTHubDeviceClient

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

Importante

Autenticar usando uma chave de acesso compartilhada

Para conectar um dispositivo ao Hub IoT:

Chame create_from_connection_string para adicionar a cadeia de conexão primária do dispositivo.
Chame connect para conectar o cliente do dispositivo.

Por exemplo:

# Add your IoT hub primary connection string
CONNECTION_STRING = "{Device primary connection string}"
device_client = IoTHubDeviceClient.create_from_connection_string(CONNECTION_STRING)

# Connect the client
device_client.connect()

Autenticar usando um certificado X.509

Para conectar um dispositivo ao Hub IoT usando um certificado X.509:

Use create_from_x509_certificate para adicionar os parâmetros de certificado X.509
Chame connect para ligar o cliente do dispositivo

Este exemplo mostra os valores dos parâmetros de entrada do certificado como variáveis locais para maior clareza. Em um sistema de produção, armazene parâmetros de entrada confidenciais em variáveis de ambiente ou em outro local de armazenamento mais seguro. Por exemplo, use os.getenv("HOSTNAME") para ler a variável de ambiente de nome de host.

# The Azure IoT hub name
hostname = "xxxxx.azure-devices.net"

# The device that has been created on the portal using X509 CA signing or self-signing capabilities
device_id = "MyDevice"

# The X.509 certificate file name
cert_file = "~/certificates/certs/sensor-thl-001-device.cert.pfx"
key_file = "~/certificates/certs/sensor-thl-001-device.cert.key"
# The optional certificate pass phrase
pass_phrase = "1234"

x509 = X509(
    cert_file,
    key_file,
    pass_phrase,
)

# The client object is used to interact with your Azure IoT hub.
device_client = IoTHubDeviceClient.create_from_x509_certificate(
    hostname=hostname, device_id=device_id, x509=x509
)

# Connect to IoT Hub
await device_client.connect()

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

Amostras de código

Para obter exemplos funcionais de autenticação de certificado X.509 do dispositivo, consulte os exemplos cujos nomes de arquivo terminam em x509 em cenários de hub assíncrono.

Recuperar um dispositivo gêmeo e examinar as propriedades relatadas

Você pode recuperar e examinar informações de gêmeos do dispositivo, incluindo tags e propriedades. As informações de gêmeo de dispositivo recuperadas correspondem aos dados formatados em JSON de gêmeo de dispositivo que você pode exibir para um dispositivo no portal do Azure.

Chame get_twin para obter o gêmeo de dispositivo do serviço Hub IoT do Azure. As informações gêmeas são colocadas em uma variável que pode ser impressa ou examinada.

Este exemplo recupera o gêmeo do dispositivo e usa o print comando para exibir o gêmeo do dispositivo no formato JSON.

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

Propriedades gêmeas do dispositivo relatadas pelo patch

Você pode aplicar um patch para atualizar as propriedades relatadas do dispositivo no formato JSON.

Para aplicar um patch para atualizar as propriedades relatadas:

Atribua um patch JSON de propriedade relatada a uma variável.
Chame patch_twin_reported_properties para aplicar o patch JSON às propriedades relatadas. Esta é uma chamada síncrona, o que significa que esta função não retorna até que o patch seja enviado para o serviço e reconhecido.

Se patch_twin_reported_properties retornar um erro, essa função gerará o erro correspondente.

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

Você também pode chamar estes métodos para atualizar gêmeos de dispositivo:

Chame replace_twin para substituir as tags gêmeas do dispositivo e as propriedades desejadas.
Chame update_twin para atualizar os rótulos e propriedades desejadas do dispositivo gêmeo.

Manipulador de patch de propriedades desejadas entrantes

Chame on_twin_desired_properties_patch_received para criar uma função de manipulador ou co-rotina que é chamada quando um patch de propriedades desejadas gêmeas é recebido. O manipulador usa um argumento, que é o patch gêmeo na forma de um objeto de dicionário JSON.

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 inclui os seguintes exemplos:

get_twin - Conecte-se a um dispositivo e recupere informações de gêmeos.
update_twin_reported_properties - Atualize as propriedades relatadas por gêmeos.
receive_twin_desired_properties - Receba e atualize as propriedades desejadas.

Criar um aplicativo de back-end

Esta seção descreve como criar um aplicativo de back-end para:

Atualizar tags gêmeas e propriedades desejadas
Consulta dispositivos usando filtros nas tags e propriedades

A classe IoTHubRegistryManager expõe todos os métodos necessários para criar um aplicativo de back-end para interagir com gêmeos de dispositivo do serviço.

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

Importante

Conectar-se usando uma política de acesso compartilhado

Conecte-se ao hub IoT usando from_connection_string. A sua aplicação precisa da permissão service connect para modificar as propriedades desejadas de um twin do dispositivo e precisa da permissão registry read para consultar o registo de identidade. Não há nenhuma política de acesso compartilhado padrão que contenha apenas essas duas permissões, portanto, você precisa criar uma se uma ainda não existir. Forneça esta cadeia de conexão de política de acesso compartilhado como um parâmetro para fromConnectionString. 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:

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

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

Conectar-se usando o Microsoft Entra

Um aplicativo de back-end que usa o Microsoft Entra deve autenticar e obter com êxito 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

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. Por exemplo, Contribuidor de Gêmeos do Hub IoT é necessário para habilitar o acesso de leitura e escrita a gêmeos de dispositivos e módulos do Hub IoT. 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 é utilizar o DefaultAzureCredential, mas recomenda-se usar um método diferente num ambiente de produção, incluindo um TokenCredential específico ou um ChainedTokenCredential reduzido. 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. Ele 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. O resultado de uma autenticação bem-sucedida do Microsoft Entra é um credencial de segurança na forma de token, que é transferido para um método de conexão do IoT Hub.

from azure.identity import DefaultAzureCredential
credential = DefaultAzureCredential()

O AccessToken resultante pode 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 credencial do Azure

Neste exemplo, a credencial do Azure é obtida usando DefaultAzureCredentialo . A URL e a credencial do serviço do Azure são então fornecidas a IoTHubRegistryManager.from_token_credential para criar a conexão com o 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.

Atualizar etiquetas duplas e propriedades desejadas

Você pode atualizar as tags gêmeas do dispositivo e as propriedades desejadas de um aplicativo de back-end ao mesmo tempo usando update_twin.

Chame get_twin para obter a versão atual do twin do dispositivo
Use a classe Twin para adicionar tags e propriedades no formato JSON.
Ligue update_twin para aplicar o patch no dispositivo gêmeo. Você também pode usar replace_twin para substituir as propriedades e tags desejadas para um dispositivo gêmeo.

Este exemplo atualiza as informações das etiquetas region e plant e define uma propriedade desejada power_level para 1.

new_tags = {
        'location' : {
            'region' : 'US',
            'plant' : 'Redmond43'
        }
    }

DEVICE_ID = "[Device Id]"
twin = iothub_registry_manager.get_twin(DEVICE_ID)
twin_patch = Twin(tags=new_tags, properties= TwinProperties(desired={'power_level' : 1}))
twin = iothub_registry_manager.update_twin(DEVICE_ID, twin_patch, twin.etag)

Criar uma consulta dupla de dispositivo

Você pode consultar informações de gêmeos de dispositivos usando consultas de gêmeos de dispositivos. As consultas gêmeas de dispositivo são consultas semelhantes a SQL que retornam um conjunto de resultados de gêmeos de dispositivo.

Para usar uma consulta gêmea de dispositivo:

Use um objeto QuerySpecification para definir uma solicitação de consulta semelhante a SQL.
Use query_iot_hub para consultar um IoTHub e recuperar informações de gêmeos de dispositivo usando a especificação de consulta semelhante a SQL.

Este exemplo executa duas consultas. O primeiro seleciona apenas os gêmeos de dispositivos localizados na Redmond43 planta, e o segundo refina a consulta para selecionar apenas os dispositivos que também estão conectados através de uma rede celular. Os resultados são impressos após cada consulta.

query_spec = QuerySpecification(query="SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'")
query_result = iothub_registry_manager.query_iot_hub(query_spec, None, 100)
print("Devices in Redmond43 plant: {}".format(', '.join([twin.device_id for twin in query_result.items])))

print()

query_spec = QuerySpecification(query="SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' AND properties.reported.connectivity = 'cellular'")
query_result = iothub_registry_manager.query_iot_hub(query_spec, None, 100)
print("Devices in Redmond43 plant using cellular network: {}".format(', '.join([twin.device_id for twin in query_result.items])))

print()

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 de dispositivo. Para obter mais informações, consulte Exemplo de consulta do Gerenciador do Registro.

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

Descrição geral

Este artigo descreve como usar o Azure IoT SDK para Node.js para criar código de aplicação de serviço para dispositivos e para serviços de back-end relativos a gêmeos de dispositivo.

Criar um aplicativo de dispositivo

As aplicações de dispositivos podem ler e gravar as propriedades reportadas do gêmeo e ser notificadas sobre alterações nas propriedades desejadas do gêmeo definidas por uma aplicação de back-end ou pelo Hub IoT.

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:

Recuperar um dispositivo gêmeo e examinar as propriedades relatadas
Atualizar propriedades gêmeas do dispositivo relatadas
Receber aviso de alterações desejadas na propriedade

Importante

Instalar o pacote SDK do dispositivo

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:

Certificado X.509
Chave de acesso partilhada

Importante

Autenticar usando um certificado X.509

O certificado X.509 é anexado ao transporte de ligação do dispositivo ao Hub IoT.

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

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
- Uma cadeia de ligação do módulo de identidade:
  
  HostName=xxxxx.azure-devices.net;DeviceId=Device-1;ModuleId=Module-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true
Configure uma variável JSON com detalhes do certificado e passe-a para DeviceClientOptions.
Utilize setOptions para adicionar um certificado X.509 e uma chave (e, opcionalmente, frase-passe) ao sistema de transporte do cliente.
Chamada aberta para abrir a conexão do dispositivo com o Hub IoT.

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:

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.

Autenticar usando uma chave de acesso compartilhada

O pacote azure-iot-device contém objetos que fazem interface com dispositivos IoT. A classe Twin inclui objetos específicos para gêmeos. Esta seção descreve o código da classe Client que é usado para ler e escrever dados do device twin.

Escolha um protocolo de transporte

O Client objeto suporta estes protocolos:

Amqp
Http - Ao usar Http, a instância Client verifica mensagens do IoT Hub com pouca frequência (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 Mqtt protocolo:

npm install azure-iot-device-mqtt --save

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

Criar um módulo cliente

Crie um Client módulo usando o pacote instalado.

Por exemplo:

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

Criar um módulo de protocolo

Crie um Protocol módulo usando um pacote de transporte instalado.

Este exemplo atribui o protocolo MQTT:

const Protocol = require('azure-iot-device-mqtt').Mqtt;

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 - Uma cadeia de conexão que encapsula permissões de "conexão de dispositivo" para um hub IoT. A cadeia de conexão contém nome do host, ID do dispositivo ou chave de acesso compartilhado neste formato: "HostName=<iothub_host_name>; DeviceId=<device_id>; SharedAccessKey=<device_key>".
transportCtor - O protocolo de transporte.

Este exemplo usa o Mqtt protocolo de transporte:

const deviceConnectionString = "{IoT hub device connection string}"
const Protocol = require('azure-iot-device-mqtt').Mqtt;
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. Use .catch(err) para capturar um erro e executar o código do manipulador.

Por exemplo:

client.open()  //open the connection
.catch((err) => {
  console.error('Could not connect: ' + err.message);
});

Recuperar um dispositivo gêmeo e examinar as propriedades relatadas

Chame getTwin para recuperar informações gêmeas do dispositivo atual em um objeto Twin .

Por exemplo:

client.getTwin(function(err, twin))
if (err)
    console.error('could not get twin');

Atualizar propriedades gêmeas do dispositivo relatadas

Utilize atualizar para atualizar as propriedades relatadas do dispositivo. Inclua um patch formatado em JSON como o primeiro parâmetro e o método de retorno de chamada de status de execução da função como o segundo parâmetro para o método.

Neste exemplo, um patch de gêmeo de dispositivo em formato JSON é armazenado na variável patch. O patch contém um valor de atualização gêmea connectivity de dispositivo de 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.

var patch = {
    connectivity: {
        type: 'cellular'
    }
}
twin.properties.reported.update(patch, function(err)
  {
    if (err)
      {
        console.error('could not update twin');
      } 
    else
      {
        console.log('twin state reported');
        process.exit();
      }
  });

Receber notificações sobre alterações na propriedade pretendida

Crie um ouvinte de eventos de atualização de propriedade desejada que é executado quando uma propriedade desejada é alterada no dispositivo passando o nome do método do manipulador de retorno de chamada para twin.on.

O ouvinte de eventos de propriedade desejado pode assumir uma das seguintes formas:

Receba todos os patches com um único manipulador de eventos
Receber um evento se algo mudar em um agrupamento de propriedades
Receber um evento para uma única alteração de propriedade

Receba todos os patches com um único manipulador de eventos

Você pode criar um ouvinte para receber qualquer alteração desejada de propriedade.

Este código de exemplo gera a saída de quaisquer 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 algo mudar em um agrupamento de propriedades

Você pode criar um ouvinte para receber um evento se algo em um agrupamento de propriedades mudar.

Por exemplo:

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

Uma aplicação de serviço de back-end aplica este patch para atualizar minTemperature e maxTemperature propriedades desejadas.

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

Este código configura um escutador de eventos de alteração nas propriedades desejadas que é acionado para qualquer alteração dentro do agrupamento de propriedades properties.desired.climate. Se houver uma alteração de propriedade desejada dentro desse grupo, as mensagens de alteração de temperatura mínima e máxima sã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);
    }
});
```

Receber um evento para uma única alteração de propriedade

Você pode configurar um ouvinte para uma única alteração de propriedade. 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.

Um aplicativo de back-end aplica este patch de propriedade desejado:

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

O ouvinte aciona somente quando a fanOn propriedade muda:

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

Exemplos de SDK de dispositivo

O SDK do Azure IoT para Node.js contém dois exemplos gêmeos de dispositivo:

Criar um aplicativo de back-end

Esta seção descreve como criar um aplicativo de back-end que:

Recupera e atualiza um dispositivo gêmeo
Cria uma consulta gêmea de dispositivo

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

A classe Registry expõe todos os métodos necessários para interagir com gêmeos de dispositivo de um aplicativo de back-end.

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

Importante

Conectar-se usando uma política de acesso compartilhado

Utilize fromConnectionString para ligar-se ao hub IoT. Seu aplicativo precisa da permissão service connect para modificar as propriedades desejadas de um device twin, e precisa da permissão de leitura do registo para consultar o registo de identidade. Não há nenhuma política de acesso compartilhado padrão que contenha apenas essas duas permissões, portanto, você precisa criar uma se uma ainda não existir. Forneça esta cadeia de conexão de política de acesso compartilhado como um parâmetro para fromConnectionString. Para obter mais informações sobre políticas de acesso compartilhado, consulte Controlar o acesso ao Hub IoT com assinaturas de acesso compartilhado.

'use strict';
var iothub = require('azure-iothub');
var connectionString = '{Shared access policy connection string}';
var registry = iothub.Registry.fromConnectionString(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 credenciais 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:

Configurar o aplicativo Microsoft Entra

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. Por exemplo, Colaborador de Gêmeos do Hub IoT é necessário para habilitar o acesso de leitura e escrita a um dispositivo e os gêmeos de módulo do Hub IoT. 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 em um ambiente de produção, incluindo um específico TokenCredential ou um ChainedTokenCredential reduzido. 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. Ele tenta usar vários tipos de credenciais em determinada ordem 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. O resultado de uma autenticação bem-sucedida do Microsoft Entra é uma credencial de token de segurança que é passada para um método de conexão do IoT Hub.

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:

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 credencial do Azure

Neste exemplo, a credencial do Azure é obtida usando o DefaultAzureCredential. A URL e a credencial do domínio do Azure são fornecidas para Registry.fromTokenCredential criar a conexão com o Hub IoT.

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.

Recuperar e atualizar um dispositivo twin

Você pode criar um patch que contenha tags e atualizações de propriedades desejadas para um dispositivo gêmeo.

Para atualizar um dispositivo gêmeo:

Chame getTwin para recuperar o objeto gêmeo do dispositivo.

Formate um patch que contenha a atualização gêmea do dispositivo. O patch é formatado em JSON conforme descrito na classe Twin. Um patch de serviço de back-end pode conter atualizações de tags e propriedades desejadas. Para obter mais informações sobre o formato do patch, consulte Formato de Tags e Propriedades.

Ligue para atualizar o dispositivo gêmeo com o patch.

Neste exemplo, o dispositivo gêmeo é recuperado para myDeviceId, em seguida, um patch é aplicado aos gêmeos que contém location a atualização de tag de region: 'US', plant: 'Redmond43'.

     registry.getTwin('myDeviceId', function(err, twin){
         if (err) {
             console.error(err.constructor.name + ': ' + err.message);
         } else {
             var patch = {
                 tags: {
                     location: {
                         region: 'US',
                         plant: 'Redmond43'
                   }
                 }
             };

             twin.update(patch, function(err) {
               if (err) {
                 console.error('Could not update twin: ' + err.constructor.name + ': ' + err.message);
               } else {
                 console.log(twin.deviceId + ' twin updated successfully');
                 queryTwins();
               }
             });
         }
     });

Criar uma consulta dupla de dispositivo

Você pode criar consultas de dispositivo semelhantes ao SQL para coletar informações de gêmeos de dispositivo.

Use createQuery para criar uma consulta que pode ser executada em uma instância do hub IoT para localizar informações sobre dispositivos ou trabalhos.

createQuery Inclui dois parâmetros:

sqlQuery - A consulta escrita como uma cadeia de caracteres SQL.
pageSize - O número desejado de resultados por página (opcional. padrão: 1000, max: 10000).

Se o parâmetro pageSize for especificado, o objeto de consulta conterá uma propriedade booleana que poderá verificar e, ao usar o método nextAsTwin, obter a próxima página de resultados subsequentes tantas vezes quantas forem necessárias para recuperar todos os resultados. Um método chamado next está disponível para resultados que não são gêmeos de dispositivo, por exemplo, os resultados de consultas de agregação.

Esta consulta de exemplo seleciona apenas os gêmeos de dispositivos localizados na Redmond43 planta.

var queryTwins = function() {
var query = registry.createQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'", 100);
query.nextAsTwin(function(err, results) {
    if (err) {
        console.error('Failed to fetch the results: ' + err.message);
    } else {
        console.log("Devices in Redmond43: " + results.map(function(twin) {return twin.deviceId}).join(','));
    }
});

Esta consulta de exemplo refina a primeira consulta para selecionar apenas os dispositivos que também estão conectados através da rede celular.

query = registry.createQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' AND properties.reported.connectivity.type = 'cellular'", 100);
query.nextAsTwin(function(err, results) {
    if (err) {
        console.error('Failed to fetch the results: ' + err.message);
    } else {
        console.log("Devices in Redmond43 using cellular network: " + results.map(function(twin) {return twin.deviceId}).join(','));
    }
});
};

Exemplo de SDK de serviço

O SDK do Azure IoT para Node.js fornece uma amostra funcional de um aplicativo de serviço que lida com tarefas gêmeas de dispositivo. Para obter mais informações, consulte Device Twin Backend Service - Este projeto é usado para enviar atualizações de patch duplo de dispositivo para um dispositivo específico.

Comentários

Esta página foi útil?

Last updated on 2025-01-03

Partilhar via

Introdução aos dispositivos duplos

Pré-requisitos

Descrição geral

Criar um aplicativo de dispositivo

Pacote NuGet do dispositivo necessário

Ligar um dispositivo ao Hub IoT

Autenticar usando uma chave de acesso compartilhada

Autenticar usando um certificado X.509

Amostras de código

Recuperar um dispositivo gêmeo e examinar propriedades

Atualizar propriedades gêmeas do dispositivo relatadas

Criar um manipulador de retorno de chamada de atualização de propriedade desejada

Exemplo de dispositivo SDK

Criar um aplicativo de back-end

Adicionar pacote NuGet de serviço

Conectar-se ao hub IoT

Conectar-se usando uma política de acesso compartilhado

Conectar-se usando o Microsoft Entra

Configurar o aplicativo Microsoft Entra

Autenticar usando DefaultAzureCredential

Exemplo de código

Ler e atualizar campos gêmeos do dispositivo

Ler e atualizar tags gêmeas do dispositivo

Atualizar tags usando um objeto gêmeo

Atualizar tags usando uma cadeia de caracteres JSON

Visualizar e atualizar propriedades desejadas gêmeas

Outros métodos de atualização dupla

Criar uma consulta dupla de dispositivo

Exemplo de serviço SDK

Descrição geral

Criar um aplicativo de dispositivo

Instruções de importação de dispositivo

Ligar um dispositivo ao Hub IoT

Autenticar usando uma chave de acesso compartilhada

Autenticar usando um certificado X.509

Amostras de código

Recuperar e visualizar um dispositivo twin

Atualizar propriedades relatadas do gêmeo digital do dispositivo

Subscrever às alterações desejadas numa propriedade

Exemplo de dispositivo SDK

Criar um aplicativo de back-end

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

Conectar-se ao Hub IoT

Conectar-se usando uma política de acesso compartilhado

Conectar-se usando o Microsoft Entra

Configurar o aplicativo Microsoft Entra

Autenticar usando DefaultAzureCredential

Autenticar usando ClientSecretCredentialBuilder

Outras classes de autenticação

Amostras de código

Atualizar campos gêmeos do dispositivo

Criar uma consulta dupla de dispositivo

Exemplo de serviço SDK

Descrição geral

Instalar pacotes

Criar um aplicativo de dispositivo

Declaração de importação de dispositivo

Ligar um dispositivo ao Hub IoT

Autenticar usando uma chave de acesso compartilhada

Autenticar usando um certificado X.509

Amostras de código

Recuperar um dispositivo gêmeo e examinar as propriedades relatadas

Propriedades gêmeas do dispositivo relatadas pelo patch

Manipulador de patch de propriedades desejadas entrantes

Exemplos de dispositivos SDK

Criar um aplicativo de back-end

Conectar-se ao hub IoT

Conectar-se usando uma política de acesso compartilhado

Conectar-se usando o Microsoft Entra

Configurar o aplicativo Microsoft Entra

Autenticar usando DefaultAzureCredential

Amostras de código

Atualizar etiquetas duplas e propriedades desejadas

Criar uma consulta dupla de dispositivo

Exemplo de serviço SDK

Descrição geral

Criar um aplicativo de dispositivo

Instalar o pacote SDK do dispositivo

Ligar um dispositivo ao Hub IoT