Introdução à gestão de dispositivos

Os aplicativos back-end podem usar primitivos do Hub IoT do Azure, como gêmeos de dispositivo e métodos diretos, para iniciar e monitorar remotamente ações de gerenciamento de dispositivos em dispositivos.

Use um método direto de um aplicativo back-end para iniciar ações de gerenciamento de dispositivos, como reinicialização, redefinição de fábrica e atualização de firmware.

O dispositivo é responsável por:

• Manipulando a solicitação de método direto enviada do Hub IoT
• Iniciar a ação específica do dispositivo correspondente no dispositivo
• Fornecendo atualizações de status por meio de propriedades relatadas para o Hub IoT

Este artigo mostra como um aplicativo back-end e um aplicativo de dispositivo podem trabalhar juntos para iniciar e monitorar uma ação de dispositivo remoto usando um método direto.

• Um aplicativo de serviço chama um método direto para reinicializar em um aplicativo de dispositivo por meio de um hub IoT.
• Um aplicativo de dispositivo lida com um método direto para reiniciar um dispositivo.

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 certa do Hub IoT para sua solução.

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 back-end e dispositivo para mensagens diretas de dispositivo.

Criar um aplicativo de dispositivo

Esta seção descreve como usar o código do aplicativo de dispositivo para criar um ouvinte de retorno de chamada de método direto.

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 Segurança de conexão.

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

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

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

O CreateFromConnectionString parâ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
• Http1

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

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

Criar um ouvinte de retorno de chamada de método direto

Use SetMethodHandlerAsync para inicializar um ouvinte de retorno de chamada de método direto. O ouvinte está associado a uma palavra-chave de nome de método, como "reboot". O nome do método pode ser usado em um Hub IoT ou aplicativo de back-end para disparar o método de retorno de chamada no dispositivo.

Este exemplo configura um ouvinte de retorno de chamada chamado onReboot que será acionado quando o nome do método direto "reboot" for chamado.

try
{
      // setup callback for "reboot" method
      deviceClient.SetMethodHandlerAsync("reboot", onReboot, null).Wait();
      Console.WriteLine("Waiting for reboot method\n Press enter to exit.");
      Console.ReadLine();

      Console.WriteLine("Exiting...");

      // as a good practice, remove the "reboot" handler
      deviceClient.SetMethodHandlerAsync("reboot", null, null).Wait();
      deviceClient.CloseAsync().Wait();
}
catch (Exception ex)
{
      Console.WriteLine();
      Console.WriteLine("Error in sample: {0}", ex.Message);
}

Continuando o exemplo, o onReboot método de retorno de chamada implementa o método direct no dispositivo.

A função handler chama MethodResponse para enviar uma confirmação de resposta para o aplicativo de chamada.

static Task<MethodResponse> onReboot(MethodRequest methodRequest, object userContext)
{
      // In a production device, you would trigger a reboot 
      // scheduled to start after this method returns.
      // For this sample, we simulate the reboot by writing to the console
      // and updating the reported properties.
      try
      {
         Console.WriteLine("Rebooting!");
      }
      catch (Exception ex)
      {
         Console.WriteLine();
         Console.WriteLine("Error in sample: {0}", ex.Message);
      }

      string result = @"{""result"":""Reboot started.""}";
      return Task.FromResult(new MethodResponse(Encoding.UTF8.GetBytes(result), 200));
}

Nota

Para simplificar, este artigo não implementa nenhuma política de novas tentativas. No código de produção, você deve implementar políticas de repetição (como um backoff exponencial), como sugerido em Tratamento de falhas transitórias.

Exemplos de dispositivos SDK

O SDK do Azure IoT para .NET fornece exemplos funcionais de aplicativos de dispositivo que lidam com tarefas diretas do método. Para obter mais informações, consulte:

• Amostra de método
• Dispositivo simulado com comando
• Controlador de Temperatura
• Amostra de termostato

Criar um aplicativo de back-end

Esta seção descreve como acionar um método direto em um dispositivo.

A classe ServiceClient expõe todos os métodos necessários para criar um aplicativo de back-end para enviar chamadas diretas de método para dispositivos.

Pacote NuGet de serviço necessário

Os aplicativos de serviço de back-end exigem o pacote NuGet Microsoft.Azure.Devices.

Adicione essas using instruções para usar a biblioteca de serviços.

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

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 Segurança na nuvem.

Conectar-se usando uma política de acesso compartilhado

Conecte um aplicativo back-end usando CreateFromConnectionString.

Para invocar um método direto em um dispositivo por meio do Hub IoT, seu serviço precisa da permissão de conexão de serviço. Por padrão, cada Hub IoT é criado com uma política de acesso compartilhado chamada serviço que concede essa permissão.

Como parâmetro para CreateFromConnectionString, forneça a política de acesso compartilhado do serviço . Para obter mais informações sobre políticas de acesso compartilhado, consulte Controlar o acesso ao Hub IoT com assinaturas de acesso compartilhado.

ServiceClient serviceClient;
string connectionString = "{IoT hub service shared access policy connection string}";
serviceClient = ServiceClient.CreateFromConnectionString(connectionString);

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.

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, o Colaborador Gêmeo do Hub IoT é necessário para habilitar o acesso de leitura e gravação a um dispositivo do Hub IoT e 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 um aplicativo 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 ChainedTokenCredentialreduzido. 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 DefaultAzureCredentialdo , consulte Diretrizes 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 em uma ordem até encontrar uma credencial de trabalho.

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 conexão do Hub IoT.

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:

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

Invocar um método num dispositivo

Para invocar um método em um dispositivo:

1. Crie um objeto CloudToDeviceMethod . Passe o nome do método direto do dispositivo como um parâmetro.
2. Chame InvokeDeviceMethodAsync para invocar o método no dispositivo.

Este exemplo chama o método "reboot" para iniciar uma reinicialização no dispositivo. O método "reboot" é mapeado para um ouvinte no dispositivo, conforme descrito na seção Criar um ouvinte de retorno de chamada de método direto deste artigo.

string targetDevice = "myDeviceId";
CloudToDeviceMethod method = new CloudToDeviceMethod("reboot");
method.ResponseTimeout = TimeSpan.FromSeconds(30);

CloudToDeviceMethodResult response = await serviceClient.InvokeDeviceMethodAsync(targetDevice, method);

Console.WriteLine("Invoked firmware update on device.");

Exemplos de serviço SDK

O SDK do Azure IoT para .NET fornece exemplos funcionais de aplicativos de serviço que lidam com tarefas de mensagem. Para obter mais informações, consulte:

• Método Invoke Device
• Método E2E Ensaios
• Controlador de Temperatura
• Amostra de termostato

• Requer Java SE Development Kit 8. Certifique-se de selecionar Java 8 em Suporte de longo prazo para navegar até downloads para JDK 8.

Descrição geral

Este artigo descreve como usar o SDK do Azure IoT para Java para criar código de aplicativo de serviço de dispositivo e back-end para métodos diretos de dispositivo.

Criar um aplicativo de dispositivo

Esta seção descreve como usar o código do aplicativo de dispositivo para criar um ouvinte de retorno de chamada de método direto.

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 Segurança de conexão.

Declaração 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.exceptions.IotHubClientException;
import com.microsoft.azure.sdk.iot.device.twin.DirectMethodPayload;
import com.microsoft.azure.sdk.iot.device.twin.DirectMethodResponse;
import com.microsoft.azure.sdk.iot.device.twin.MethodCallback;
import com.microsoft.azure.sdk.iot.device.transport.IotHubConnectionStatus;
import com.microsoft.azure.sdk.iot.device.twin.SubscriptionAcknowledgedCallback;

Ligar a um dispositivo

A classe DeviceClient expõe todos os métodos necessários para interagir com métodos diretos no dispositivo.

Para ligar a um dispositivo:

1. Use IotHubClientProtocol para escolher um protocolo de transporte. Por exemplo:

   IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;
   

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

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

Criar um ouvinte de retorno de chamada de método direto

Use subscribeToMethods para inicializar um ouvinte de retorno de chamada de método direto. subscribeToMethods escuta os métodos diretos de entrada até que a conexão seja encerrada. O nome do método e a carga útil são recebidos para cada chamada direta do método.

O ouvinte deve chamar DirectMethodResponse para enviar uma confirmação de resposta de método para o aplicativo de chamada.

Por exemplo:

client.subscribeToMethods(
    (methodName, methodData, context) ->
    {
        System.out.println("Received a direct method invocation with name " + methodName + " and payload " + methodData.getPayloadAsJsonString());
        return new DirectMethodResponse(200, methodData);
    },
    null);
System.out.println("Successfully subscribed to direct methods");

Nota

Para simplificar, este artigo não implementa nenhuma política de novas tentativas. No código de produção, você deve implementar políticas de repetição (como um backoff exponencial), como sugerido em Tratamento de falhas transitórias.

Exemplos de dispositivos 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 Direct Method Sample.

Criar um aplicativo de back-end

Esta seção descreve como iniciar uma reinicialização remota em um dispositivo usando um método direto.

A ServiceClient classe DeviceMethod 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.methods.DirectMethodRequestOptions;
import com.microsoft.azure.sdk.iot.service.methods.DirectMethodsClient;
import com.microsoft.azure.sdk.iot.service.methods.DirectMethodResponse;

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 Segurança na nuvem.

Conectar-se usando uma política de acesso compartilhado

Use o construtor DeviceMethod para adicionar a cadeia de conexão primária do serviço e conectar-se ao Hub IoT.

Para invocar um método direto em um dispositivo por meio do Hub IoT, seu serviço precisa da permissão de conexão de serviço. Por padrão, cada Hub IoT é criado com uma política de acesso compartilhado chamada serviço que concede essa permissão.

Como parâmetro para o DeviceMethod construtor, forneça a política de acesso compartilhado do serviço . 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:

String iotHubConnectionString = "HostName=xxxxx.azure-devices.net;SharedAccessKeyName=service;SharedAccessKey=xxxxxxxxxxxxxxxxxxxxxxxx";
DeviceMethod methodClient = new DeviceMethod(iotHubConnectionString);

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 Java SDK, consulte Autenticação do Azure com Java e Identidade do Azure.

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

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, o Colaborador Gêmeo do Hub IoT é necessário para habilitar o acesso de leitura e gravação a um dispositivo do Hub IoT e 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 um aplicativo 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 ChainedTokenCredentialreduzido. Para obter mais informações sobre os prós e contras do uso DefaultAzureCredentialdo , consulte Cadeias de credenciais na biblioteca de cliente 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 em uma ordem até encontrar uma credencial de trabalho.

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 criado, passe-o TokenCredential 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 para um construtor como 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 ClientSecretCredentialBuilder criar a credencial.

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:

• AuthorizationCodeCredential
• AzureCliCredential
• AzureDeveloperCliCredential
• AzurePipelinesCredential
• ChainedTokenCredential
• ClientAssertionCredential
• ClientCertificateCredential
• DeviceCodeCredential
• AmbienteCredencial
• InteractiveBrowserCredential
• ManagedIdentityCredential
• OnBehalfOfCredential

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.

Invocar um método num dispositivo

Chame DeviceMethod.invoke para invocar um método em um dispositivo e retornar o status do resultado.

O invoke parâmetro payload é opcional. Use null se não houver carga útil fornecida. O parâmetro payload pode assumir diferentes formas de dados, incluindo string, matriz de bytes e HashMap. Para obter exemplos, consulte Testes de método direto.

Este exemplo chama o método "reboot" para iniciar uma reinicialização no dispositivo. O método "reboot" é mapeado para um ouvinte no dispositivo, conforme descrito na seção Criar um ouvinte de retorno de chamada de método direto deste artigo.

Por exemplo:

String deviceId = "myFirstDevice";
String methodName = "reboot";
String payload = "Test payload";
Long responseTimeout = TimeUnit.SECONDS.toSeconds(30);
Long connectTimeout = TimeUnit.SECONDS.toSeconds(5);

MethodResult result = methodClient.invoke(deviceId, methodName, responseTimeout, connectTimeout, payload);
if (result == null)
{
    throw new IOException("Method invoke returns null");
}
System.out.println("Status=" + result.getStatus());

Exemplos de serviço SDK

O SDK do Azure IoT para Java fornece um exemplo funcional de aplicativos de serviço que lidam com tarefas diretas do método. Para obter mais informações, consulte:

• Amostra direta do método
• Amostra de serviço de termostato

• 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 aplicativo de serviço de back-end e dispositivo para métodos diretos de dispositivo.

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

Esta seção descreve como usar o código do aplicativo de dispositivo para criar um ouvinte de retorno de chamada de método direto.

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 Segurança de conexão.

Instruções de importação de dispositivo

Adicione esta instrução import ao access IoTHubDeviceClient e MethodResponse.

# import the device client library
from azure.iot.device import IoTHubDeviceClient, MethodResponse

Ligar a um dispositivo

O IoTHubDeviceClient classe contém métodos que podem ser usados para trabalhar com métodos diretos.

Use create_from_connection_string para conectar um aplicativo a um dispositivo usando uma cadeia de conexão de dispositivo.

# substitute the device connection string in conn_str
# and add it to the IoTHubDeviceClient object
conn_str = "{IoT hub device connection string}"
device_client = IoTHubDeviceClient.create_from_connection_string(conn_str)

Criar um retorno de chamada de método direto

Use on_method_request_received para criar uma função de manipulador ou co-rotina que é chamada quando um método direto é recebido. O ouvinte está associado a uma palavra-chave de nome de método, como "reboot". O nome do método pode ser usado em um Hub IoT ou aplicativo de back-end para disparar o método de retorno de chamada no dispositivo.

A função handler deve criar um MethodResponse e passá-lo para send_method_response para enviar uma confirmação de resposta de método direto para o aplicativo chamador.

Este exemplo configura um manipulador de método direto chamado method_request_handler.

try:
    # Attach the handler to the client
    client.on_method_request_received = method_request_handler
except:
    # In the event of failure, clean up
    client.shutdown()

Neste exemplo, o method_request_handler método de retorno de chamada implementa o método direct no dispositivo. O código é executado quando o método direto "rebootDevice" é chamado de um aplicativo de serviço. O método chama send_method_response para enviar uma confirmação de resposta direta do método para o aplicativo de chamada.

# Define the handler for method requests
def method_request_handler(method_request):
    if method_request.name == "rebootDevice":
        # Act on the method by rebooting the device
        print("Rebooting device")
        time.sleep(20)
        print("Device rebooted")
        # Create a method response indicating the method request was resolved
        resp_status = 200
        resp_payload = {"Response": "This is the response from the device"}
        method_response = MethodResponse(method_request.request_id, resp_status, resp_payload)
    else:
        # Create a method response indicating the method request was for an unknown method
        resp_status = 404
        resp_payload = {"Response": "Unknown method"}
        method_response = MethodResponse(method_request.request_id, resp_status, resp_payload)

    # Send the method response
    client.send_method_response(method_response)

Exemplos de dispositivos SDK

O SDK do Azure IoT para Python fornece uma amostra funcional de um aplicativo de dispositivo que lida com tarefas diretas do método. Para obter mais informações, consulte Método Receive direct.

Criar um aplicativo de back-end

Esta seção descreve como usar um aplicativo de serviço de back-end para chamar um método direto em um dispositivo.

A classe IoTHubRegistryManager expõe todos os métodos necessários para criar um aplicativo de back-end para enviar mensagens para um dispositivo.

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

Adicione essas instruções de importação para se conectar ao Iot Hub, enviar métodos diretos da nuvem para o dispositivo e receber respostas diretas do método do dispositivo.

from azure.iot.hub import IoTHubRegistryManager
from azure.iot.hub.models import CloudToDeviceMethod, CloudToDeviceMethodResult

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 Segurança na nuvem.

Conectar-se usando uma política de acesso compartilhado

Conecte-se ao hub IoT usando from_connection_string.

Para invocar um método direto em um dispositivo por meio do Hub IoT, seu serviço precisa da permissão de conexão de serviço. Por padrão, cada Hub IoT é criado com uma política de acesso compartilhado chamada serviço que concede essa permissão.

Como parâmetro para from_connection_string, forneça a política de acesso compartilhado do serviço . 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 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

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, o Colaborador Gêmeo do Hub IoT é necessário para habilitar o acesso de leitura e gravação a um dispositivo do Hub IoT e 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 um aplicativo 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 ChainedTokenCredentialreduzido. 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 DefaultAzureCredentialdo , consulte Cadeias de credenciais na biblioteca de cliente do 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 em uma ordem até encontrar uma credencial de trabalho.

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 é uma credencial de token de segurança que é passada para um método de conexão do Hub IoT.

from azure.identity import DefaultAzureCredential
credential = DefaultAzureCredential()

O AccessToken resultante pode ser passado para from_token_credential 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 fornecidas para IoTHubRegistryManager.from_token_credential 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.

Invocar um método num dispositivo

Você pode invocar um método direto pelo nome em um dispositivo. O nome do método identifica o método. No exemplo de dispositivo a seguir e anterior mostrado em Criar um retorno de chamada de método direto, o nome do método direto é "rebootDevice".

Para invocar um método direto em um dispositivo:

1. Crie um objeto CloudToDeviceMethod . Forneça o nome do método e a carga útil como parâmetros.
2. Chame invoke_device_method para invocar um método direto em um dispositivo. Forneça o ID do dispositivo e CloudToDeviceMethod o objeto de carga útil como parâmetros.

Este exemplo chama CloudToDeviceMethod para invocar um método direto chamado "rebootDevice" em um dispositivo. Depois que o método direct tiver sido invocado com êxito, a carga útil de resposta direta do método será exibida.

CONNECTION_STRING = "{IoTHubConnectionString}"
DEVICE_ID = "{deviceId}"

METHOD_NAME = "rebootDevice"
METHOD_PAYLOAD = "{\"method_number\":\"42\"}"
TIMEOUT = 60
WAIT_COUNT = 10

try:
    print ( "" )
    print ( "Invoking device to reboot..." )

    # Call the direct method.
    deviceMethod = CloudToDeviceMethod(method_name=METHOD_NAME, payload=METHOD_PAYLOAD)
    response = registry_manager.invoke_device_method(DEVICE_ID, deviceMethod)

    print ( "Successfully invoked the device to reboot." )

    print ( "The device has returned this payload:" )
    print ( response.payload )

except Exception as ex:
    print ( "" )
    print ( "Unexpected error {0}".format(ex) )
    return

Exemplos de serviço SDK

O SDK do Azure IoT para Python fornece exemplos funcionais de aplicativos de serviço que lidam com tarefas diretas do método. Para obter mais informações, consulte:

• Sincronização do auxiliar de serviço
• Operações de serviço

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

Descrição geral

Este artigo descreve como usar o SDK do Azure IoT para Node.js para criar código de aplicativo de serviço de dispositivo e back-end para métodos diretos de dispositivo.

Criar um aplicativo de dispositivo

Esta seção descreve como usar o código do aplicativo de dispositivo para criar um retorno de chamada de método direto.

Instalar pacotes SDK

O pacote azure-iot-device contém objetos que fazem interface com dispositivos IoT. Execute este comando para instalar o SDK do dispositivo azure-iot-device em sua máquina de desenvolvimento:

npm install azure-iot-device --save

Escolha um protocolo de transporte

O Client objeto suporta estes protocolos:

• Amqp
• Http - Ao usar Httpo , a Client instância verifica mensagens do Hub IoT 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 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 da nuvem para o dispositivo e Escolha um protocolo de comunicação.

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 dispositivo.
• transportCtor - O protocolo de transporte.

Este exemplo usa o Amqp protocolo de transporte:

const deviceConnectionString = "{IoT hub device 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 a 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);
  }
})

Criar um retorno de chamada de método direto

Chame onDeviceMethod para criar uma função de manipulador de retorno de chamada ou co-rotina que é chamada quando um método direto é recebido. O ouvinte está associado a uma palavra-chave de nome de método, como "reboot". O nome do método pode ser usado em um Hub IoT ou aplicativo de back-end para disparar o método de retorno de chamada no dispositivo.

A função de manipulador de retorno de chamada deve chamar response.send para enviar uma mensagem de confirmação de resposta para o aplicativo de chamada.

Este exemplo configura um manipulador de método direto chamado onReboot que é chamado quando o nome do método direto "reboot" é usado.

client.onDeviceMethod('reboot', onReboot);

Neste exemplo, o onReboot método de retorno de chamada implementa o método direct no dispositivo. O código é executado quando o método direto "reboot" é chamado de um aplicativo de serviço. A função chama response.send para enviar uma mensagem de confirmação de resposta para o aplicativo de chamada.

var onReboot = function(request, response) {

    // Respond the cloud app for the direct method
    response.send(200, 'Reboot started', function(err) {
        if (err) {
            console.error('An error occurred when sending a method response:\n' + err.toString());
        } else {
            console.log('Response to method \'' + request.methodName + '\' sent successfully.');
        }
    });

    // Add your device's reboot API for physical restart.
    console.log('Rebooting!');
};

Exemplos de dispositivos SDK

O SDK do Azure IoT para Node.js fornece exemplos funcionais de aplicativos de dispositivo que lidam com tarefas de gerenciamento de dispositivos. Para obter mais informações, consulte:

• Exemplo de método de dispositivo
• Métodos de dispositivo teste E2E
• Dispositivo de reinicialização de padrões DM

Criar um aplicativo de back-end

Esta seção descreve como invocar um método direto em um 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

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 Segurança na nuvem.

Conectar-se usando uma política de acesso compartilhado

Use fromConnectionString para se conectar ao hub IoT.

Para invocar um método direto em um dispositivo por meio do Hub IoT, seu serviço precisa da permissão de conexão de serviço. Por padrão, cada Hub IoT é criado com uma política de acesso compartilhado chamada serviço que concede essa permissão.

Como parâmetro para CreateFromConnectionString, forneça a cadeia de conexão da política de acesso compartilhado do serviço . Para obter mais informações sobre políticas de acesso compartilhado, consulte Controlar o acesso ao Hub IoT com assinaturas de acesso compartilhado.

var Client = require('azure-iothub').Client;
var connectionString = '{IoT hub shared access policy connection string}';
var client = Client.fromConnectionString(connectionString);

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 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. Por exemplo, o Colaborador Gêmeo do Hub IoT é necessário para habilitar o acesso de leitura e gravação a um dispositivo do Hub IoT e 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 um aplicativo 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 ChainedTokenCredentialreduzido. 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 DefaultAzureCredentialdo , 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 uma ordem até encontrar uma credencial de trabalho.

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 Hub IoT.

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

Neste exemplo, a credencial do Azure é obtida usando DefaultAzureCredentialo . 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.

Invocar um método num dispositivo

Use invokeDeviceMethod para invocar um método direto pelo nome em um dispositivo. O parâmetro method name identifica o método direct.

Este exemplo chama o método "reboot" para iniciar uma reinicialização no dispositivo. O método "reboot" é mapeado para uma função de manipulador de retorno de chamada no dispositivo, conforme descrito na seção Criar um retorno de chamada de método direto deste artigo.

var startRebootDevice = function(deviceToReboot) {

    var methodName = "reboot";

    var methodParams = {
        methodName: methodName,
        payload: null,
        timeoutInSeconds: 30
    };

    client.invokeDeviceMethod(deviceToReboot, methodParams, function(err, result) {
        if (err) {
            console.error("Direct method error: "+err.message);
        } else {
            console.log("Successfully invoked the device to reboot.");  
        }
    });
};

Exemplos de serviço SDK

O SDK do Azure IoT para Node.js fornece exemplos funcionais de aplicativos de serviço que lidam com tarefas de gerenciamento de dispositivos. Para obter mais informações, consulte:

• Métodos do módulo
• Testes de método de dispositivo
• Testes do método do dispositivo E2E
• Desconexão do método