Compartilhar via

Introdução ao gerenciamento de dispositivos

  • Artigo

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

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

O dispositivo é responsável por:

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

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

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

Observação

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

Observação

Esse artigo tem como objetivo complementar os exemplos de SDKs da Internet das Coisas do Azure referenciados nesse artigo. Você pode usar as ferramentas do SDK para criar aplicativos de dispositivo e de back-end.

Pré-requisitos

  • Um hub IoT

  • Um dispositivo registrado

  • Se o seu aplicativo usar o protocolo MQTT, certifique-se de que a porta 8883 está aberta no firewall. O protocolo MQTT se comunica pela porta 8883. Essa porta poderá ser bloqueada em alguns ambientes de rede corporativos e educacionais. Para obter mais informações e maneiras de resolver esse problema, confira Como se conectar ao Hub IoT (MQTT).

  • Requer o Visual Studio

Visão geral

Esse artigo descreve como usar o SDK da Internet das Coisas do Azure para .NET para criar o código de aplicativo de dispositivo e serviço de back-end para mensagens diretas de dispositivo.

Criar um aplicativo de dispositivo

Esta seção descreve como usar o código de 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 teste e avaliação, mas a autenticação em um dispositivo que usa certificados X.509 é uma abordagem mais segura. Para saber mais, consulte Melhores práticas de segurança> em Conexão de segurança.

Pacote NuGet do dispositivo necessário

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

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

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

Conecte a um dispositivo

A classe DeviceClient expõe todos os métodos necessários para interagir com as mensagens do dispositivos a partir 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 da conexão.

O parâmetro de protocolo de transporte CreateFromConnectionString TransportType dá suporte aos seguintes protocolos de transporte:

  • Mqtt
  • Mqtt_WebSocket_Only
  • Mqtt_Tcp_Only
  • Amqp
  • Amqp_WebSocket_Only
  • Amqp_Tcp_Only
  • Http1

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

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 é associado a uma palavra-chave do nome do 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á disparado 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 método de retorno de chamada onReboot implementa o método direto no dispositivo.

A função de manipulador chama o MethodResponse para enviar um reconhecimento 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));
}

Observação

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

Exemplos de dispositivo do SDK

O SDK da Internet das Coisas do Azure para .NET fornece exemplos funcionais de aplicativos de dispositivo que manipulam tarefas de método direto. Para saber mais, veja:

Criar um aplicativo de back-end

Esta seção descreve como disparar 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 de método direto 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 instruções using 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 compartilhado
  • 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 a autenticação em um serviço com o Microsoft Entra ID ou identidades gerenciadas é uma abordagem mais segura. Para saber mais, consulte Melhores Práticas de Segurança > Segurança da Nuvem.

Conectar-se usando a política de acesso compartilhado

Conecte um aplicativo de back-end usando CreateFromConnectionString.

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

Como um parâmetro para CreateFromConnectionString, forneça a política de acesso compartilhado do serviço. Para obter mais informações sobre as políticas de acesso compartilhado, confira Controlar o acesso ao Hub IoT com as 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 ser autenticado 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, confira Controlar o acesso ao Hub IoT usando o Microsoft Entra ID.

Configurar o aplicativo Microsoft Entra

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

  • Segredo do cliente
  • Certificado
  • Credencial de identidade federada

Os aplicativos do 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 a módulos gêmeos. Para obter mais informações, confira 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 do Microsoft Entra, confira 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 TokenCredential específico ou ChainedTokenCredential reduzido. Para simplificar, esta seção descreve a autenticação usando DefaultAzureCredential e um segredo do cliente. Para obter mais informações sobre os prós e contras do uso de DefaultAzureCredential, confira as Diretrizes de uso para DefaultAzureCredential.

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 credencial em uma ordem até encontrar uma credencial em funcionamento.

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

  • Azure.Core
  • Azure.Identity
using Azure.Core;
using Azure.Identity;

Neste exemplo, o segredo do cliente de registro do aplicativo do 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 pelo 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 então ser passado para um método de conexão com o Hub IoT para um cliente do SDK que aceite as 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, TokenCredential é passado para RegistryManager.Create para criar um objeto RegistryManager.

string hostname = "xxxxxxxxxx.azure-devices.net";
registryManager = RegistryManager.Create(hostname, tokenCredential);
Exemplo de código

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

Chamar um método em um 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 do SDK

O SDK da Internet das Coisas do Azure para .NET fornece exemplos funcionais de aplicativos de serviço que manipulam tarefas de mensagens. Para saber mais, veja:

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

Visão geral

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

Criar um aplicativo de dispositivo

Esta seção descreve como usar o código de 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 teste e avaliação, mas a autenticação em um dispositivo que usa certificados X.509 é uma abordagem mais segura. Para saber mais, consulte Melhores práticas de segurança> em Conexão de segurança.

Instrução de importação de dispositivo

Use as seguintes instruções de importação de dispositivo para acessar o SDK da Internet das Coisas do Azure 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;

Conecte a um dispositivo

A classe DeviceClient expõe todos os métodos que você precisa para interagir com métodos diretos no dispositivo.

Para se conectar a um dispositivo:

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

    IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;

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

    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 por métodos diretos de entrada até que a conexão seja encerrada. O nome do método e o conteúdo são recebidos para cada chamada de método direto.

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

Observação

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

Exemplos de dispositivo do SDK

O SDK da Internet das Coisas do Azure para Java inclui um exemplo de trabalho para testar os conceitos do aplicativo de dispositivo descritos nesse artigo. Para obter mais informações, consulte Exemplo de método direto.

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 classe ServiceClient DeviceMethod contém métodos que os serviços podem usar para acessar dispositivos gêmeos.

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

Use as seguintes instruções de importação de serviço para acessar o SDK da Internet das Coisas do Azure 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 compartilhado
  • 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 a autenticação em um serviço com o Microsoft Entra ID ou identidades gerenciadas é uma abordagem mais segura. Para saber mais, consulte Melhores Práticas de Segurança > Segurança da Nuvem.

Conectar-se usando a 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, o seu serviço precisa da permissão conexão de serviço. Por padrão, todo Hub IoT é criado com uma política de acesso compartilhado chamada serviço que concede essa permissão.

Como parâmetro para o construtor DeviceMethod, forneça a política de acesso compartilhado do serviço. Para obter mais informações sobre as políticas de acesso compartilhado, confira Controlar o acesso ao Hub IoT com as 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 ser autenticado 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, confira Controlar o acesso ao Hub IoT usando o Microsoft Entra ID.

Para obter uma visão geral da autenticação do SDK do Java, confira a autenticação do Azure com o Java e a Identidade do Azure.

Para simplificar, esta seção se concentra em descrever a autenticação usando o segredo do cliente.

Configurar o aplicativo Microsoft Entra

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

  • Segredo do cliente
  • Certificado
  • Credencial de identidade federada

Os aplicativos do 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 a módulos gêmeos. Para obter mais informações, confira 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 do Microsoft Entra, confira 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 TokenCredential específico ou ChainedTokenCredential reduzido. Para obter mais informações sobre os prós e contras do uso de DefaultAzureCredential, confira Cadeias de credenciais na biblioteca de clientes da Identidade do Azure para Java.

O 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 credencial em uma ordem até encontrar uma credencial em funcionamento.

Você pode autenticar as credenciais do aplicativo do Microsoft Entra usando DefaultAzureCredentialBuilder. Salve os parâmetros de conexão, como o tenantID do segredo do cliente, clientID e valores do segredo do cliente como variáveis ambientais. Depois que o TokenCredential for 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 para um construtor, como ServiceClient.

TokenCredential defaultAzureCredential = new DefaultAzureCredentialBuilder().build();
Autenticar usando o ClientSecretCredentialBuilder

Você pode usar ClientSecretCredentialBuilder para criar uma credencial usando informações do 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, o segredo do cliente de registro do aplicativo do Microsoft Entra, a ID do cliente e os valores da ID do locatário foram adicionados a variáveis de ambiente. Essas variáveis de ambiente são usadas pelo ClientSecretCredentialBuilder para 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 SDK do Java também inclui estas classes que autenticam um aplicativo de back-end com o Microsoft Entra:

Exemplos de código

Para obter exemplos práticos da autenticação de serviço do Microsoft Entra, confira o Exemplo de autenticação baseada em função.

Chamar um método em um dispositivo

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

O parâmetro de conteúdo invoke é opcional. Use null se nenhum conteúdo for fornecido. O parâmetro de conteúdo pode usar diferentes formulários de dados, incluindo cadeia de caracteres, 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 do SDK

O SDK da Internet das Coisas do Azure para Java fornece uma amostra funcional de aplicativos de serviço que manipulam tarefas de método direto. Para saber mais, veja:

  • SDK do Python – é recomendado o Python versão 3.7 ou posterior. Certifique-se de usar a instalação de 32 bits ou 64 bits conforme exigido pelo seu programa de instalação. Quando solicitado durante a instalação, certifique-se de adicionar Python à variável de ambiente específica da plataforma.

Visão geral

Esse artigo descreve como usar o SDK da Internet das Coisas do Azure para Python para criar o código de aplicativo de dispositivo e serviço de back-end 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 de 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 teste e avaliação, mas a autenticação em um dispositivo que usa certificados X.509 é uma abordagem mais segura. Para saber mais, consulte Melhores práticas de segurança> em Conexão de segurança.

Instruções de importação do dispositivo

Adicione esta instrução de importação para acessar IoTHubDeviceClient e MethodResponse.

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

Conecte a um dispositivo

A classe IoTHubDeviceClient 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 manipuladora ou corrotina que será chamada quando um método direto for recebido. O ouvinte é associado a uma palavra-chave do nome do 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 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 de chamada.

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 método de retorno de chamada method_request_handler implementa o método direto 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 de método direto 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 dispositivo do SDK

O SDK da Internet das Coisas do Azure para Python fornece um exemplo funcional de um aplicativo de dispositivo que manipula as tarefas de método direto. Para obter mais informações, consulte Receber método direto.

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 a um dispositivo.

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

Adicione essas instruções de importação para se conectar ao Hub Iot, enviar métodos diretos de nuvem para dispositivo e receber respostas de método direto 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 compartilhado
  • 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 a autenticação em um serviço com o Microsoft Entra ID ou identidades gerenciadas é uma abordagem mais segura. Para saber mais, consulte Melhores Práticas de Segurança > Segurança da Nuvem.

Conectar-se usando a 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, o seu serviço precisa da permissão conexão de serviço. Por padrão, todo Hub IoT é criado com uma política de acesso compartilhado chamada serviço que concede essa permissão.

Como um parâmetro para from_connection_string, forneça a política de acesso compartilhado do serviço. Para obter mais informações sobre as políticas de acesso compartilhado, confira Controlar o acesso ao Hub IoT com as 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 ser autenticado 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, confira Controlar o acesso ao Hub IoT usando o Microsoft Entra ID.

Para obter uma visão geral da autenticação do SDK do Python, confira 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 do Microsoft Entra configurado para sua credencial de autenticação preferencial. O aplicativo contém parâmetros como o segredo do cliente que são usados pelo aplicativo de back-end para autenticação. As configurações de autenticação do aplicativo disponíveis são:

  • Segredo do cliente
  • Certificado
  • Credencial de identidade federada

Os aplicativos do 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 a módulos gêmeos. Para obter mais informações, confira 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 do Microsoft Entra, confira 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 TokenCredential específico ou ChainedTokenCredential reduzido. Para simplificar, esta seção descreve a autenticação usando DefaultAzureCredential e um segredo do cliente. Para obter mais informações sobre os prós e contras do uso de DefaultAzureCredential, confira Cadeias de credenciais na biblioteca de clientes da Identidade do Azure para Python.

O 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 credencial em uma ordem até encontrar uma credencial em funcionamento.

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

pip install azure-identity

from azure.identity import DefaultAzureCredential

Nesse exemplo, o segredo do cliente de registro do aplicativo do Microsoft Entra, a ID do cliente e a ID do locatário foram adicionados a variáveis de ambiente. Essas variáveis de ambiente são usadas pelo 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 então ser passado para from_token_credential para se conectar com o Hub IoT para um cliente do SDK que aceite as credenciais do Microsoft Entra:

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 prefixo https://. Por exemplo, MyAzureDomain.azure-devices.net.
  • O token de credencial do Azure

Nesse exemplo, a credencial do Azure é obtida usando DefaultAzureCredential. A URL e a credencial do serviço do Azure são fornecidas para 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)
Exemplos de código

Para obter exemplos de trabalho da autenticação de serviço do Microsoft Entra, confira a MSAL (Biblioteca de Autenticação da Microsoft) para Python.

Chamar um método em um 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 no exemplo 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 o conteúdo como parâmetros.
  2. Chame invoke_device_method para invocar um método direto em um dispositivo. Forneça a ID do dispositivo e o objeto de conteúdo CloudToDeviceMethod como parâmetros.

Este exemplo chama CloudToDeviceMethod para invocar um método direto chamado "rebootDevice" em um dispositivo. Depois que o método direto tiver sido invocado com êxito, o conteúdo da resposta do método direto 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 do SDK

O SDK da Internet das Coisas do Azure para Python fornece exemplos funcionais de aplicativos de serviço que manipulam tarefas de método direto. Para saber mais, veja:

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

Visão geral

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

Criar um aplicativo de dispositivo

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

Instalar pacotes do SDK

O pacote azure-iot-device contém objetos que fazem interface com os dispositivos IoT. Execute esse comando para instalar o SDK do dispositivo azure-iot-device em seu computador de desenvolvimento:

npm install azure-iot-device --save

Escolher um protocolo de transporte

O objeto Client dá suporte a esses protocolos:

  • Amqp
  • Http - ao usar Http, a instância Client verifica as mensagens do Hub IoT com pouca frequência (um mínimo a cada 25 minutos).
  • Mqtt
  • MqttWs
  • AmqpWs

Instale os protocolos de transporte necessários em seu computador de desenvolvimento.

Por exemplo, esse comando instala o protocolo Amqp:

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

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

Criar um objeto cliente

Crie um objeto Client usando o pacote instalado.

Por exemplo:

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

Criar um objeto de protocolo

Crie um objeto Protocol 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 – protocolo de transporte.

Esse exemplo usa o protocolo de transporte Amqp:

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

Abrir a conexão com o Hub IoT

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

Por exemplo:

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

Criar um retorno de chamada de método direto

Chame onDeviceMethod para criar uma função manipuladora de retorno de chamada ou corrotina que será chamada quando um método direto for recebido. O ouvinte é associado a uma palavra-chave do nome do 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 manipuladora 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 método de retorno de chamada onReboot implementa o método direto no dispositivo. O código é executado quando o método direto de "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 dispositivo do SDK

O SDK da Internet das Coisas do Azure para Node.js fornece exemplos funcionais de aplicativos de dispositivos que manipulam tarefas de gerenciamento de dispositivos. Para saber mais, veja:

Criar um aplicativo de back-end

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

Instalar o pacote do SDK de serviço

Execute esse comando para instalar azure-iothub em seu computador 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 compartilhado
  • 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 a autenticação em um serviço com o Microsoft Entra ID ou identidades gerenciadas é uma abordagem mais segura. Para saber mais, consulte Melhores Práticas de Segurança > Segurança da Nuvem.

Conectar-se usando a 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, o seu serviço precisa da permissão conexão de serviço. Por padrão, todo Hub IoT é criado com uma política de acesso compartilhado chamada serviço que concede essa permissão.

Como um 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 as políticas de acesso compartilhado, confira Controlar o acesso ao Hub IoT com as 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 ser autenticado 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, confira Controlar o acesso ao Hub IoT usando o Microsoft Entra ID.

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

Configurar o aplicativo Microsoft Entra

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

  • Segredo do cliente
  • Certificado
  • Credencial de identidade federada

Os aplicativos do 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 a módulos gêmeos. Para obter mais informações, confira 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 do Microsoft Entra, confira 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 TokenCredential específico ou ChainedTokenCredential reduzido. Para simplificar, esta seção descreve a autenticação usando DefaultAzureCredential e um segredo do cliente. Para obter mais informações sobre os prós e contras do uso de DefaultAzureCredential, confira Cadeias de credenciais na biblioteca de clientes da Identidade do Azure para JavaScript

O 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 credencial em uma ordem até encontrar uma credencial em funcionamento.

O Microsoft Entra requer este pacote:

npm install --save @azure/identity

Nesse exemplo, o segredo do cliente de registro do aplicativo do Microsoft Entra, a ID do cliente e a ID do locatário foram adicionados a variáveis de ambiente. Essas variáveis de ambiente são usadas pelo 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 então ser passado para fromTokenCredential para se conectar ao Hub IoT para um cliente do SDK que aceite as 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 prefixo https://. Por exemplo, MyAzureDomain.azure-devices.net.
  • O token de credencial do Azure

Nesse exemplo, a credencial do Azure é obtida usando DefaultAzureCredential. A URL de domínio e a credencial do Azure são fornecidas para Registry.fromTokenCredential para 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);
Exemplos de código

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

Chamar um método em um dispositivo

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

Este exemplo chama o método "reboot" para iniciar uma reinicialização no dispositivo. O método "reboot" é mapeado para uma função manipuladora de retorno de chamada no dispositivo, conforme descrito na seção Criar um método direto de retorno de chamada 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 do SDK

O SDK da Internet das Coisas do Azure para Node.js fornece exemplos funcionais de aplicativos de serviço que manipulam tarefas de gerenciamento de dispositivos. Para saber mais, veja: