Partilhar via

Como agendar e transmitir trabalhos

Este artigo mostra como criar código de aplicativo back-end para agendar e transmitir trabalhos.

Use o Hub IoT do Azure para agendar e rastrear trabalhos que atualizam até milhões de dispositivos para estas operações:

  • Invocar métodos diretos
  • Gêmeos de dispositivo atualizados

Um trabalho encapsula uma dessas ações e rastreia a execução em relação a um conjunto de dispositivos definido por uma consulta gêmea de dispositivo. Por exemplo, uma aplicação back-end pode utilizar uma tarefa para invocar um método direto em 10.000 dispositivos que reinicie os dispositivos. Você especifica o conjunto de dispositivos com uma consulta gêmea de dispositivo e agenda o trabalho para ser executado em um momento futuro. O trabalho monitora o progresso à medida que cada um dos dispositivos recebe e executa o método direto de reinicialização.

Para saber mais sobre cada um desses recursos, consulte:

Nota

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

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 aplicação de serviço de back-end para agendar uma tarefa para invocar um método direto ou executar uma atualização do gêmeo de dispositivo em um ou mais dispositivos.

Adicionar pacote NuGet de serviço

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

Usando declarações

Adicione usando as seguintes instruções.

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

using System.Threading;
using System.Threading.Tasks;

Conectar-se ao hub IoT

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

  • Política de acesso partilhado
  • Microsoft Entra

Importante

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

Conectar-se usando uma política de acesso compartilhado

Conecte um aplicativo back-end a um dispositivo usando CreateFromConnectionString.

Este artigo descreve o código back-end que pode agendar um trabalho para invocar um método direto, agendar um trabalho para atualizar um dispositivo gêmeo e monitora o progresso de um trabalho para um ou mais dispositivos. Para executar essas operações, o seu serviço precisa das permissões de leitura do registo e permissões de escrita no registo. Por padrão, cada hub IoT é criado com uma política de acesso compartilhado chamada registryReadWrite que concede essas permissões.

Para obter mais informações sobre políticas de acesso compartilhado, consulte Controlar o acesso ao Hub IoT com assinaturas de acesso compartilhado.

static JobClient jobClient;
static string connectionString = "{Shared access policy connection string}";
jobClient = JobClient.CreateFromConnectionString(connString);

Conectar-se usando o Microsoft Entra

Um aplicativo de back-end que usa Microsoft Entra deve autenticar-se e obter uma credencial de token de segurança com sucesso 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, Colaborador de Gêmeos do Hub IoT é necessário para habilitar o acesso de leitura e gravação a um dispositivo do Hub IoT e aos gêmeos de módulo. Para obter mais informações, consulte Gerenciar o acesso ao Hub IoT usando a atribuição de função RBAC do Azure.

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

Autenticar usando DefaultAzureCredential

A maneira mais fácil de usar o Microsoft Entra para autenticar uma aplicação de back-end é usar DefaultAzureCredential, mas recomenda-se usar um método diferente num ambiente de produção, incluindo um método específico TokenCredential ou uma versão mais reduzida ChainedTokenCredential. Para simplificar, esta seção descreve o uso da DefaultAzureCredential autenticação e o segredo do cliente. Para obter mais informações sobre os prós e contras do uso do DefaultAzureCredential, consulte Orientações de utilização 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 determinada ordem até encontrar uma credencial válida.

O Microsoft Entra requer os seguintes pacotes NuGet e as correspondentes instruções 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 é transmitida para um método de ligação do IoT Hub.

string clientSecretValue = "xxxxxxxxxxxxxxx";
string clientID = "xxxxxxxxxxxxxx";
string tenantID = "xxxxxxxxxxxxx";

Environment.SetEnvironmentVariable("AZURE_CLIENT_SECRET", clientSecretValue);
Environment.SetEnvironmentVariable("AZURE_CLIENT_ID", clientID);
Environment.SetEnvironmentVariable("AZURE_TENANT_ID", tenantID);

TokenCredential tokenCredential = new DefaultAzureCredential();

O TokenCredential resultante pode então ser passado para um método de ligação ao Hub IoT, compatível com qualquer cliente SDK que aceite credenciais do Microsoft Entra:

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

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

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

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

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

Agendar uma tarefa de método direto

Use ScheduleDeviceMethodAsync para agendar um trabalho para executar um método direto em um ou vários dispositivos.

Use o objeto CloudToDeviceMethod para especificar o nome do método direto e os valores de tempo limite de conexão do dispositivo.

Por exemplo:

// The CloudToDeviceMethod record specifies the direct method name and device connection time-out
CloudToDeviceMethod directMethod = 
new CloudToDeviceMethod("LockDoor", TimeSpan.FromSeconds(5), 
TimeSpan.FromSeconds(5));

Este exemplo agenda uma tarefa para um método direto chamado "LockDoor" num dispositivo chamado "Device-1". Os dispositivos incluídos no trabalho agendado estão contidos no segundo parâmetro como uma condição de consulta. Para obter mais informações sobre condições de consulta, consulte Linguagem de consulta do Hub IoT para gêmeos de dispositivo e módulo, trabalhos e roteamento de mensagens.

string methodJobId = Guid.NewGuid().ToString();  // a unique job ID
static string deviceId = "Device-1";             // In this example, there is only one device affected
JobResponse result = await jobClient.ScheduleDeviceMethodAsync(methodJobId,
   $"DeviceId IN ['{deviceId}']",
   directMethod,
   DateTime.UtcNow,
   (long)TimeSpan.FromMinutes(2).TotalSeconds);

Agendar uma tarefa de atualização do gémeo de dispositivo

Use ScheduleTwinUpdateAsync para agendar um novo trabalho de atualização de tags e propriedades desejadas de gémeos de dispositivo para execução em um ou mais dispositivos.

Primeiro, crie e preencha um objeto Twin de dispositivo para a atualização. Por exemplo:

static string deviceId = "Device-1";

Twin twin = new Twin(deviceId);
twin.Tags = new TwinCollection();
twin.Tags["Building"] = "43";
twin.Tags["Floor"] = "3";
twin.ETag = "*";
twin.Properties.Desired["LocationUpdate"] = DateTime.UtcNow;

Em seguida, ligue para ScheduleTwinUpdateAsync. Especifique os dispositivos a serem atualizados como uma consulta no segundo parâmetro. Para obter mais informações sobre condições de consulta, consulte Linguagem de consulta do Hub IoT para gêmeos de dispositivo e módulo, trabalhos e roteamento de mensagens.

string twinJobId = Guid.NewGuid().ToString();

JobResponse createJobResponse = jobClient.ScheduleTwinUpdateAsync(
   twinJobId,
   $"DeviceId IN ['{deviceId}']", 
   twin, 
   DateTime.UtcNow, 
   (long)TimeSpan.FromMinutes(2).TotalSeconds).Result;

Monitorizar uma tarefa

Use GetJobAsync para monitorar o status do trabalho para uma ID de trabalho específica.

Este exemplo verifica o status do trabalho para um ID de trabalho periodicamente até que o status do trabalho seja concluído ou tenha falhado. Por exemplo:

JobResponse result;
do
{
   result = await jobClient.GetJobAsync(jobId);
   Console.WriteLine("Job Status : " + result.Status.ToString());
   Thread.Sleep(2000);
} while ((result.Status != JobStatus.Completed) && (result.Status != JobStatus.Failed));

Exemplos de tarefas agendadas no SDK

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

  • Requer Java SE Development Kit 8. Certifique-se de selecionar Java 8 em Suporte de longo prazo para aceder aos downloads do JDK 8.

Descrição geral

Este artigo descreve como usar o SDK do Azure IoT para Java para criar o código da aplicação de serviço de backend para agendar uma tarefa para invocar um método direto ou realizar uma atualização do gêmeo de dispositivos em um ou mais dispositivos.

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

A classe JobClient contém métodos que os serviços podem usar para agendar trabalhos.

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

import com.microsoft.azure.sdk.iot.service.devicetwin.DeviceTwinDevice;
import com.microsoft.azure.sdk.iot.service.devicetwin.Pair;
import com.microsoft.azure.sdk.iot.service.devicetwin.Query;
import com.microsoft.azure.sdk.iot.service.devicetwin.SqlQuery;
import com.microsoft.azure.sdk.iot.service.jobs.JobClient;
import com.microsoft.azure.sdk.iot.service.jobs.JobResult;
import com.microsoft.azure.sdk.iot.service.jobs.JobStatus;

import java.util.Date;
import java.time.Instant;
import java.util.HashSet;
import java.util.Set;
import java.util.UUID;

Conectar-se ao Hub IoT

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

  • Política de acesso partilhado
  • Microsoft Entra

Importante

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

Conectar-se usando uma política de acesso compartilhado

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

Este artigo descreve o código back-end que pode agendar um trabalho para invocar um método direto, agendar um trabalho para atualizar um dispositivo gêmeo e monitora o progresso de um trabalho para um ou mais dispositivos. Para executar essas operações, o seu serviço precisa das permissões de leitura do registo e permissões de escrita no registo. Por padrão, cada hub IoT é criado com uma política de acesso compartilhado chamada registryReadWrite que concede essas permissões.

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:

public static final String iotHubConnectionString = "{Shared access policy connection string}";
JobClient jobClient = new JobClient(iotHubConnectionString);

Conectar-se usando o Microsoft Entra

Um aplicativo de back-end que usa Microsoft Entra deve autenticar-se e obter uma credencial de token de segurança com sucesso 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 Azure Identity.

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

Configurar o aplicativo Microsoft Entra

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, Colaborador de Gêmeos do Hub IoT é necessário para habilitar o acesso de leitura e gravação a um dispositivo do Hub IoT e aos gêmeos de módulo. Para obter mais informações, consulte Gerenciar o acesso ao Hub IoT usando a atribuição de função RBAC do Azure.

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

Autenticar usando DefaultAzureCredential

A maneira mais fácil de usar o Microsoft Entra para autenticar uma aplicação de back-end é usar DefaultAzureCredential, mas recomenda-se usar um método diferente num ambiente de produção, incluindo um método específico TokenCredential ou uma versão mais reduzida ChainedTokenCredential. Para obter mais informações sobre os prós e contras do uso de DefaultAzureCredential, consulte Cadeias de credenciais na biblioteca de cliente do Azure Identity para 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 determinada ordem até encontrar uma credencial válida.

Você pode autenticar as credenciais do aplicativo Microsoft Entra usando DefaultAzureCredentialBuilder. Salve parâmetros de conexão, como tenantID secreto do cliente, clientID e valores de segredo do cliente como variáveis ambientais. Uma vez que o TokenCredential é criado, passe-o para o 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 do Microsoft Entra bem-sucedida é 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 por 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 Java SDK também inclui estas classes que autenticam um aplicativo de back-end com o Microsoft Entra:

Amostras de código

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

Agendar uma tarefa direta de atualização de método

Use scheduleDeviceMethod para executar um método direto em um ou vários dispositivos.

Este método de exemplo agenda um trabalho para um método direto chamado "lockDoor" em um dispositivo chamado "Device-1".

// Schedule a job now to call the lockDoor direct method
// against a single device. Response and connection
// timeouts are set to 5 seconds.
String deviceId = "Device-1";
String jobId = "DMCMD" + UUID.randomUUID();  //Job ID must be unique

// How long the job is permitted to run without
// completing its work on the set of devices
private static final long maxExecutionTimeInSeconds = 30;

System.out.println("Schedule job " + jobId + " for device " + deviceId);
try {
  JobResult jobResult = jobClient.scheduleDeviceMethod(jobId,
    "deviceId='" + deviceId + "'",
    "lockDoor",
    5L, 5L, null,
    new Date(),
    maxExecutionTimeInSeconds);
} catch (Exception e) {
  System.out.println("Exception scheduling direct method job: " + jobId);
  System.out.println(e.getMessage());
}

Agendar uma tarefa de atualização do gémeo de dispositivo

Use scheduleUpdateTwin para agendar um trabalho para executar uma atualização de gêmeo de dispositivo em um ou vários dispositivos.

Primeiro, prepare um registo DeviceTwinDevice para a atualização do gémeo digital do dispositivo. Por exemplo:

String deviceId = "Device-1";

//Create a device twin desired properties update object
DeviceTwinDevice twin = new DeviceTwinDevice(deviceId);
Set<Pair> desiredProperties = new HashSet<Pair>();
desiredProperties.add(new Pair("Building", 43));
desiredProperties.add(new Pair("Floor", 3));
twin.setDesiredProperties(desiredProperties);
// Optimistic concurrency control
twin.setETag("*");

Em seguida, ligue scheduleUpdateTwin para agendar o trabalho de atualização. Por exemplo:

String jobId = "DPCMD" + UUID.randomUUID();  //Unique job ID

// How long the job is permitted to run without
// completing its work on the set of devices
private static final long maxExecutionTimeInSeconds = 30;

// Schedule the update twin job to run now for a single device
System.out.println("Schedule job " + jobId + " for device " + deviceId);
try {
  JobResult jobResult = jobClient.scheduleUpdateTwin(jobId, 
    "deviceId='" + deviceId + "'",
    twin,
    new Date(),
    maxExecutionTimeInSeconds);
} catch (Exception e) {
  System.out.println("Exception scheduling desired properties job: " + jobId);
  System.out.println(e.getMessage());
}

Monitorizar uma tarefa

Use getJob para buscar informações de trabalho com base em um ID de trabalho específico. getJob retorna um objeto JobResult que contém métodos e propriedades que você pode usar para verificar as informações do trabalho, incluindo o status da execução.

Por exemplo:

try {
  JobResult jobResult = jobClient.getJob(jobId);
  if(jobResult == null)
  {
    System.out.println("No JobResult for: " + jobId);
    return;
  }
  // Check the job result until it's completed
  while(jobResult.getJobStatus() != JobStatus.completed)
  {
    Thread.sleep(100);
    jobResult = jobClient.getJob(jobId);
    System.out.println("Status " + jobResult.getJobStatus() + " for job " + jobId);
  }
  System.out.println("Final status " + jobResult.getJobStatus() + " for job " + jobId);
} catch (Exception e) {
  System.out.println("Exception monitoring job: " + jobId);
  System.out.println(e.getMessage());
  return;
}

Consultar o status de um trabalho

Use queryDeviceJob para consultar o status do trabalho para um ou mais trabalhos.

Por exemplo:

private static void queryDeviceJobs(JobClient jobClient, String start) throws Exception {
  System.out.println("\nQuery device jobs since " + start);

  // Create a jobs query using the time the jobs started
  Query deviceJobQuery = jobClient
      .queryDeviceJob(SqlQuery.createSqlQuery("*", SqlQuery.FromType.JOBS, "devices.jobs.startTimeUtc > '" + start + "'", null).getQuery());

  // Iterate over the list of jobs and print the details
  while (jobClient.hasNextJob(deviceJobQuery)) {
    System.out.println(jobClient.getNextJob(deviceJobQuery));
  }
}

Exemplo de tarefa agendada do SDK

O SDK do Azure IoT para Java fornece um exemplo de trabalho de um aplicativo de serviço que lida com tarefas de agendamento de trabalho. Para obter mais informações, consulte Amostra de Cliente de Trabalho.

  • 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 para agendar um trabalho para invocar um método direto ou realizar uma atualização da propriedade desejada do twin do dispositivo em um ou mais dispositivos.

Instalar pacote

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

pip install azure-iot-hub

Declarações de importação

A classe IoTHubJobManager expõe todos os métodos necessários para criar um aplicativo de back-end para agendar trabalhos do serviço.

Adicione as seguintes instruções import.

import os
import sys
import datetime
import time
import threading
import uuid
import msrest

from azure.iot.hub import IoTHubJobManager
from azure.iot.hub.models import JobProperties, JobRequest, Twin, TwinProperties, CloudToDeviceMethod

Conectar-se ao hub IoT

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

  • Política de acesso partilhado
  • Microsoft Entra

Importante

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

Conectar-se usando uma política de acesso compartilhado

Conecte-se ao hub IoT usando from_connection_string.

Este artigo descreve o código back-end que pode agendar um trabalho para invocar um método direto, agendar um trabalho para atualizar um dispositivo gêmeo e monitora o progresso de um trabalho para um ou mais dispositivos. Para executar essas operações, o seu serviço precisa das permissões de leitura do registo e permissões de escrita no registo. Por padrão, cada hub IoT é criado com uma política de acesso compartilhado chamada registryReadWrite que concede essas permissões.

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:

IoTHubConnectionString = "{Shared access policy connection string}"
iothub_job_manager = IoTHubJobManager.from_connection_string(IoTHubConnectionString)

Conectar-se usando o Microsoft Entra

Um aplicativo de back-end que usa Microsoft Entra deve autenticar-se e obter uma credencial de token de segurança com sucesso 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, Colaborador de Gêmeos do Hub IoT é necessário para habilitar o acesso de leitura e gravação a um dispositivo do Hub IoT e aos gêmeos de módulo. Para obter mais informações, consulte Gerenciar o acesso ao Hub IoT usando a atribuição de função RBAC do Azure.

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

Autenticar usando DefaultAzureCredential

A maneira mais fácil de usar o Microsoft Entra para autenticar uma aplicação de back-end é usar DefaultAzureCredential, mas recomenda-se usar um método diferente num ambiente de produção, incluindo um método específico TokenCredential ou uma versão mais reduzida ChainedTokenCredential. Para simplificar, esta seção descreve o uso da DefaultAzureCredential autenticação e o segredo do cliente. Para obter mais informações sobre os prós e contras do uso do DefaultAzureCredential, consulte Orientações de utilização 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 determinada ordem até encontrar uma credencial válida.

O Microsoft Entra requer os seguintes pacotes NuGet e as correspondentes instruções 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 é transmitida para um método de ligação do IoT Hub.

string clientSecretValue = "xxxxxxxxxxxxxxx";
string clientID = "xxxxxxxxxxxxxx";
string tenantID = "xxxxxxxxxxxxx";

Environment.SetEnvironmentVariable("AZURE_CLIENT_SECRET", clientSecretValue);
Environment.SetEnvironmentVariable("AZURE_CLIENT_ID", clientID);
Environment.SetEnvironmentVariable("AZURE_TENANT_ID", tenantID);

TokenCredential tokenCredential = new DefaultAzureCredential();

O TokenCredential resultante pode então ser passado para um método de ligação ao Hub IoT, compatível com qualquer cliente SDK que aceite credenciais do Microsoft Entra:

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

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

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

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

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

Agendar uma tarefa de método direto

Use create_scheduled_job para agendar um novo método direto para executar um método direto em um ou vários dispositivos:

create_scheduled_job Notas de parâmetro:

Por exemplo:

METHOD_NAME = "lockDoor"
METHOD_PAYLOAD = "{\"lockTime\":\"10m\"}"
job_id = uuid.uuid4()
DEVICE_ID = "Device-1"
TIMEOUT = 60

job_request = JobRequest()
job_request.job_id = job_id
job_request.type = "scheduleDeviceMethod"
job_request.start_time = datetime.datetime.utcnow().isoformat()
job_request.cloud_to_device_method = CloudToDeviceMethod(method_name=METHOD_NAME, payload=METHOD_PAYLOAD)
job_request.max_execution_time_in_seconds = TIMEOUT
job_request.query_condition = "DeviceId in ['{}']".format(device_id)

new_job_response = iothub_job_manager.create_scheduled_job(job_id, job_request)

Agendar uma tarefa de atualização do gémeo de dispositivo

Use create_scheduled_job para criar uma nova tarefa que execute uma atualização das propriedades desejadas de um twin de dispositivo em um ou vários dispositivos.

create_scheduled_job Notas de parâmetro:

Por exemplo:

UPDATE_PATCH = {"building":43,"floor":3}
job_id = uuid.uuid4()
TIMEOUT = 60

job_request = JobRequest()
job_request.job_id = job_id
job_request.type = "scheduleUpdateTwin"
job_request.start_time = datetime.datetime.utcnow().isoformat()
job_request.update_twin = Twin(etag="*", properties=TwinProperties(desired=UPDATE_PATCH))
job_request.max_execution_time_in_seconds = TIMEOUT
job_request.query_condition = "DeviceId in ['{}']".format(device_id)

new_job_response = iothub_job_manager.create_scheduled_job(job_id, job_request)

Monitorizar uma tarefa

Use get_scheduled_job para recuperar os detalhes de um trabalho específico em um Hub IoT.

Este exemplo verifica o status do trabalho para um ID de trabalho específico a cada cinco segundos até que o trabalho seja concluído.

while True:
    get_job_response = iothub_job_manager.get_scheduled_job(job_request.job_id)
    print_job_response("Get job response: ", get_job_response)
    if get_job_response.status == "completed":
      print ( "Job is completed." )
    time.sleep(5)

Exemplos de tarefas agendadas no SDK

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

  • 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 aplicação de serviço de back-end que agende tarefas para invocar um método direto ou realizar uma atualização do gêmeo de dispositivo em um ou mais dispositivos.

Instalar pacote SDK de serviço

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

npm install azure-iothub --save

A classe JobClient expõe todos os métodos necessários para interagir com o agendamento de tarefas a partir de um aplicativo de back-end.

Conectar-se ao hub IoT

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

  • Política de acesso partilhado
  • Microsoft Entra

Importante

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

Conectar-se usando uma política de acesso compartilhado

Utilize fromConnectionString para se conectar ao IoT Hub.

Este artigo descreve o código back-end que pode agendar um trabalho para invocar um método direto, agendar um trabalho para atualizar um dispositivo gêmeo e monitora o progresso de um trabalho para um ou mais dispositivos. Para executar essas operações, o seu serviço precisa das permissões de leitura do registo e permissões de escrita no registo. Por padrão, cada hub IoT é criado com uma política de acesso compartilhado chamada registryReadWrite que concede essas permissões.

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:

'use strict';
var JobClient = require('azure-iothub').JobClient;
var connectionString = '{Shared access policy connection string}';
var jobClient = JobClient.fromConnectionString(connectionString);

Conectar-se usando o Microsoft Entra

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

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

Configurar o aplicativo Microsoft Entra

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, Colaborador de Gêmeos do Hub IoT é necessário para habilitar o acesso de leitura e gravação a um dispositivo do Hub IoT e aos gêmeos de módulo. Para obter mais informações, consulte Gerenciar o acesso ao Hub IoT usando a atribuição de função RBAC do Azure.

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

Autenticar usando DefaultAzureCredential

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

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

O Microsoft Entra requer este pacote:

npm install --save @azure/identity

Neste exemplo, o segredo do cliente de registro do aplicativo Microsoft Entra, a ID do cliente e a ID do locatário foram adicionados às variáveis de ambiente. Essas variáveis de ambiente são usadas por DefaultAzureCredential para autenticar o aplicativo. O resultado de uma autenticação bem-sucedida do Microsoft Entra é uma credencial de token de segurança que é transmitida para um método de ligação do IoT Hub.

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

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

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

fromTokenCredential requer dois parâmetros:

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

Neste exemplo, a credencial do Azure é obtida usando DefaultAzureCredential. A URL e as credenciais do domínio Azure são fornecidas a Registry.fromTokenCredential para estabelecer a ligação ao IoT Hub.

const { DefaultAzureCredential } = require("@azure/identity");

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

// Define the client secret values
clientSecretValue = 'xxxxxxxxxxxxxxx'
clientID = 'xxxxxxxxxxxxxx'
tenantID = 'xxxxxxxxxxxxx'

// Set environment variables
process.env['AZURE_CLIENT_SECRET'] = clientSecretValue;
process.env['AZURE_CLIENT_ID'] = clientID;
process.env['AZURE_TENANT_ID'] = tenantID;

// Acquire a credential object
const credential = new DefaultAzureCredential()

// Create an instance of the IoTHub registry
hostName = 'MyAzureDomain.azure-devices.net';
let registry = Registry.fromTokenCredential(hostName,credential);
Amostras de código

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

Criar um método direto de trabalho

Use scheduleDeviceMethod para agendar um trabalho para executar um método direto em um ou vários dispositivos.

Primeiro, crie uma variável de atualização direta do método com informações de nome do método, carga útil e tempo limite de resposta. Por exemplo:

var methodParams = {
    methodName: 'lockDoor',
    payload: null,
    responseTimeoutInSeconds: 15 // Time-out after 15 seconds if device is unable to process method
};

Em seguida, ligue scheduleDeviceMethod para agendar a tarefa de chamada direta do método.

  • Cada trabalho deve ter um ID de trabalho exclusivo. Você pode usar essa ID de trabalho para monitorar um trabalho conforme descrito na seção Monitorar um trabalho deste artigo.
  • Especifique um queryCondition parâmetro para avaliar em quais dispositivos executar o trabalho. Para obter mais informações sobre condições de consulta, consulte Linguagem de consulta do Hub IoT para gêmeos de dispositivo e módulo, trabalhos e roteamento de mensagens.
  • Verifique o retorno de chamada de jobResult para o resultado do agendamento de trabalho. Se o trabalho foi agendado com êxito, você pode monitorar o status do trabalho, conforme mostrado na seção Monitorar um trabalho deste artigo.

Por exemplo:

var methodJobId = uuid.v4();
var queryCondition = "deviceId IN ['myDeviceId']";
var startTime = new Date();
var maxExecutionTimeInSeconds =  300;

jobClient.scheduleDeviceMethod(methodJobId,
                            queryCondition,
                            methodParams,
                            startTime,
                            maxExecutionTimeInSeconds,
                            function(err) {
    if (err) {
        console.error('Could not schedule direct method job: ' + err.message);
    } else {
        monitorJob(methodJobId, function(err, result) {
            if (err) {
                console.error('Could not monitor direct method job: ' + err.message);
            } else {
                console.log(JSON.stringify(result, null, 2));
            }
        });
    }
});

Agendar uma tarefa de atualização do gémeo de dispositivo

Use scheduleTwinUpdate para criar um novo trabalho para executar uma atualização gêmea de dispositivo em um ou vários dispositivos.

Primeiro, crie uma variável de atualização de propriedade desejada do gêmeo do dispositivo.

var twinPatch = {
   etag: '*',
   properties: {
       desired: {
           building: '43',
           floor: 3
       }
   }
};

Em seguida, ligue scheduleTwinUpdate para agendar a tarefa de atualização da propriedade desejada do gémeo do dispositivo.

  • Cada trabalho deve ter um ID de trabalho exclusivo. Você pode usar essa ID de trabalho para monitorar um trabalho conforme descrito na seção Monitorar um trabalho deste artigo.
  • Especifique um queryCondition parâmetro para avaliar em quais dispositivos executar o trabalho. Para obter mais informações sobre condições de consulta, consulte Linguagem de consulta do Hub IoT para gêmeos de dispositivo e módulo, trabalhos e roteamento de mensagens.
  • Verifique o retorno de chamada de jobResult para o resultado do agendamento de trabalho. Se o trabalho foi agendado com êxito, você pode monitorar o status do trabalho, conforme mostrado na seção Monitorar um trabalho deste artigo.

Por exemplo:

var twinJobId = uuid.v4();
var queryCondition = "deviceId IN ['myDeviceId']";
var startTime = new Date();
var maxExecutionTimeInSeconds =  300;

console.log('scheduling Twin Update job with id: ' + twinJobId);
jobClient.scheduleTwinUpdate(twinJobId,
                            queryCondition,
                            twinPatch,
                            startTime,
                            maxExecutionTimeInSeconds,
                            function(err) {
    if (err) {
        console.error('Could not schedule twin update job: ' + err.message);
    } else {
        monitorJob(twinJobId, function(err, result) {
            if (err) {
                console.error('Could not monitor twin update job: ' + err.message);
            } else {
                console.log(JSON.stringify(result, null, 2));
            }
        });
    }
});

Monitorizar uma tarefa

Use getJob para monitorar o status do trabalho para um ID de trabalho específico.

Esta função de exemplo verifica o estado da tarefa para um ID de tarefa específico periodicamente até que a tarefa esteja concluída ou falhe.

function monitorJob (jobId, callback) {
    var jobMonitorInterval = setInterval(function() {
        jobClient.getJob(jobId, function(err, result) {
        if (err) {
            console.error('Could not get job status: ' + err.message);
        } else {
            console.log('Job: ' + jobId + ' - status: ' + result.status);
            if (result.status === 'completed' || result.status === 'failed' || result.status === 'cancelled') {
            clearInterval(jobMonitorInterval);
            callback(null, result);
            }
        }
        });
    }, 5000);
}

Exemplo de tarefa agendada do SDK

O SDK do Azure IoT para Node.js fornece uma amostra de trabalho de um aplicativo de serviço que lida com tarefas de agendamento de trabalho. Para obter mais informações, consulte Teste E2E do cliente de trabalho.