Como agendar e transmitir trabalhos

• Requer o Visual Studio

Visão geral

Este artigo descreve como usar o SDK da Internet das Coisas do Azure para .NET para criar código de aplicativo de serviço back-end que um agende trabalho para invocar um método direto ou realizar uma atualização de dispositivo gêmeo em um ou mais dispositivos.

Adicionar um pacote NuGet de serviço

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

Como usar instruções

Adicionar as seguintes instruções de uso.

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 compartilhado
• Microsoft Entra

Conectar-se usando a política de acesso compartilhado

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

Este artigo descreve o código back-end necessário para agendar um trabalho que invoque um método direto, programe uma atualização de dispositivo gêmeo e monitore o andamento do trabalho em um ou mais dispositivos. Para executar essas operações, o seu serviço precisa das permissões leitura de registro e gravação de registro. Por padrão, todo hub IoT é criado com uma política de acesso compartilhado chamada registryReadWrite que concede essas permissões.

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.

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

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

Agendar um trabalho de método direto

Use ScheduleDeviceMethodAsync para agendar um trabalho que execute um método direto em um ou mais 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 um trabalho para um método direto chamado "LockDoor" em um dispositivo chamado "Device-1". Os dispositivos incluídos no trabalho agendado são especificados no segundo parâmetro, que corresponde a uma condição de consulta. Para obter mais informações sobre condições de consulta, confira a página A linguagem de consulta do Hub IoT para dispositivos e módulos gêmeos, 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 um trabalho de atualização de dispositivo gêmeo

Use ScheduleTwinUpdateAsync para agendar um novo trabalho que atualize marcas e propriedades desejadas do dispositivo gêmeo para ser executado em um ou mais dispositivos.

Primeiro, crie e preencha um objeto Gêmeo 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, chame ScheduleTwinUpdateAsync. Especifique os dispositivos a serem atualizados como uma consulta no segundo parâmetro. Para obter mais informações sobre condições de consulta, confira a página A linguagem de consulta do Hub IoT para dispositivos e módulos gêmeos, 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;

Monitorar um trabalho

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

Este exemplo verifica periodicamente o status de uma ID de trabalho específica, até que o status indique "concluído" ou "falhou". 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 agendamento de trabalhos no SDK

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

• Exemplo de agendamento de atualização de gêmeo
• Exemplo de agendamento de atualização de gêmeo E2E.

• 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

Este artigo descreve como usar o SDK da Internet das Coisas do Azure para Java para criar código de aplicativo de serviço back-end que agende trabalhos para invocar um método direto ou realizar uma atualização de dispositivo gêmeo em um ou mais dispositivos.

Instruçõ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 da Internet das Coisas do Azure 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;

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

Conectar-se usando a política de acesso compartilhado

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

Este artigo descreve o código back-end necessário para agendar um trabalho que invoque um método direto, programe uma atualização de dispositivo gêmeo e monitore o andamento do trabalho em um ou mais dispositivos. Para executar essas operações, o seu serviço precisa das permissões leitura de registro e gravação de registro. Por padrão, todo hub IoT é criado com uma política de acesso compartilhado chamada registryReadWrite que concede essas permissões.

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:

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

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

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.

Agendar um trabalho atualização via método direto

Use scheduleDeviceMethod para executar um método direto em um ou mais dispositivos.

Este 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 um trabalho de atualização de dispositivo gêmeo

Use scheduleUpdateTwin para agendar um trabalho que execute a atualização do dispositivo gêmeo em um ou mais dispositivos.

Primeiro, prepare um registro DeviceTwinDevice para atualizar o dispositivo gêmeo. 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, chame 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());
}

Monitorar um trabalho

Use getJob para obter informações de trabalhos com base em uma ID de trabalho específica. getJob retorna um objeto JobResult que contém métodos e propriedades para verificar as informações do trabalho, incluindo o status de 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 de 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 agendamento de trabalhos no SDK

O SDK da Internet das Coisas do Azure para Java fornece um exemplo funcional de um aplicativo de serviço que lida com as tarefas de agendamento de trabalhos. Para obter mais informações, confira a página Amostra de Cliente de Trabalho.

• 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

Este artigo descreve como usar o SDK da Internet das Coisas do Azure para Python para criar código de aplicativo de serviço back-end que agende trabalhos para invocar um método direto ou realizar uma atualização das propriedades desejadas do dispositivo gêmeo 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

Importar instruções

A classe IoTHubJobManager expõe todos os métodos necessários para criar um aplicativo back-end que agende tarefas a partir do serviço.

Adicione as seguintes declarações de 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 compartilhado
• Microsoft Entra

Conectar-se usando a política de acesso compartilhado

Conecte-se ao hub IoT usando from_connection_string.

Este artigo descreve o código back-end necessário para agendar um trabalho que invoque um método direto, programe uma atualização de dispositivo gêmeo e monitore o andamento do trabalho em um ou mais dispositivos. Para executar essas operações, o seu serviço precisa das permissões leitura de registro e gravação de registro. Por padrão, todo hub IoT é criado com uma política de acesso compartilhado chamada registryReadWrite que concede essas permissões.

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:

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

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

Agendar um trabalho de método direto

Use create_scheduled_job para agendar um novo método direto em um ou mais dispositivos:

Notas do parâmetro create_scheduled_job:

• job_id deve ser exclusivo
• Defina type como scheduleDeviceMethod
• Use cloud_to_device_method para definir o nome do método direto e o conteúdo
• Use max_execution_time_in_seconds para especificar o tempo de execução em segundos
• Use query_condition para especificar os dispositivos a serem incluídos na chamada de método direto. Para obter mais informações sobre condições de consulta, confira a página A linguagem de consulta do Hub IoT para dispositivos e módulos gêmeos, trabalhos e roteamento de mensagens.

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 um trabalho de atualização de dispositivo gêmeo

Use create_scheduled_job para criar um novo trabalho que realize uma atualização das propriedades desejadas do dispositivo gêmeo em um ou mais dispositivos.

Notas do parâmetro create_scheduled_job:

• job_id deve ser exclusivo
• Defina type como scheduleUpdateTwin
• Use update_twin para definir o nome do método direto e o conteúdo
• Use max_execution_time_in_seconds para especificar o tempo de execução em segundos
• Use query_condition para especificar uma condição para um ou mais dispositivos que tenham a chamada de método direto. Para obter mais informações sobre condições de consulta, confira a página A linguagem de consulta do Hub IoT para dispositivos e módulos gêmeos, trabalhos e roteamento de mensagens.

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)

Monitorar um trabalho

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

Este exemplo verifica o status do trabalho de uma ID de trabalho específica a cada cinco segundos até que o trabalho termine.

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 agendamento de trabalhos no SDK

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

• Agendar um trabalho de método direto
• Agende uma atualização do dispositivo gêmeo.

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

Visão geral

Este artigo descreve como usar o SDK da Internet das Coisas do Azure para Node.js para criar código de aplicativo de serviço back-end que agende trabalhos para invocar um método direto ou realizar uma atualização de dispositivo gêmeo em um ou mais dispositivos.

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

A classe JobClient expõe todos os métodos necessários para interagir com o agendamento de trabalhos 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 compartilhado
• Microsoft Entra

Conectar-se usando a política de acesso compartilhado

Use fromConnectionString para se conectar ao hub IoT.

Este artigo descreve o código back-end necessário para agendar um trabalho que invoque um método direto, programe uma atualização de dispositivo gêmeo e monitore o andamento do trabalho em um ou mais dispositivos. Para executar essas operações, o seu serviço precisa das permissões leitura de registro e gravação de registro. Por padrão, todo hub IoT é criado com uma política de acesso compartilhado chamada registryReadWrite que concede essas permissões.

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:

'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 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:

• Introdução à autenticação do usuário no Azure
• Biblioteca de clientes da Identidade do Azure para JavaScript

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:

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

Criar um trabalho de método direto

Use scheduleDeviceMethod para agendar um trabalho que execute um método direto em um ou mais dispositivos.

Primeiro, crie uma variável de atualização de método direto com informações como: nome do método, conteúdo 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, chame scheduleDeviceMethod para agendar o trabalho de chamada de método direto:

• Cada trabalho deve ter uma ID de trabalho exclusiva. Você pode usar essa ID de trabalho para monitorar o trabalho, conforme descrito na seção Monitorar um trabalho deste artigo.
• Especifique um parâmetro queryCondition para avaliar em quais dispositivos o trabalho será executado. Para obter mais informações sobre condições de consulta, confira a página A linguagem de consulta do Hub IoT para dispositivos e módulos gêmeos, trabalhos e roteamento de mensagens.
• Verifique o retorno de chamada jobResult para conferir o resultado do agendamento do trabalho. Se o trabalho for agendado sucesso, você poderá monitorar o status dele, 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 um trabalho de atualização de dispositivo gêmeo

Use scheduleTwinUpdate para criar um novo trabalho que execute uma atualização de dispositivo gêmeo em um ou mais dispositivos.

Primeiro, crie uma variável de atualização com as propriedades desejadas do dispositivo gêmeo.

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

Em seguida, chame scheduleTwinUpdate para agendar o trabalho de atualização das propriedades desejadas do dispositivo gêmeo:

• Cada trabalho deve ter uma ID de trabalho exclusiva. Você pode usar essa ID de trabalho para monitorar o trabalho, conforme descrito na seção Monitorar um trabalho deste artigo.
• Especifique um parâmetro queryCondition para avaliar em quais dispositivos o trabalho será executado. Para obter mais informações sobre condições de consulta, confira a página A linguagem de consulta do Hub IoT para dispositivos e módulos gêmeos, trabalhos e roteamento de mensagens.
• Verifique o retorno de chamada jobResult para conferir o resultado do agendamento do trabalho. Se o trabalho for agendado sucesso, você poderá monitorar o status dele, 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));
            }
        });
    }
});

Monitorar um trabalho

Use getJob para monitorar o status do trabalho com base em uma ID de trabalho específica.

Este exemplo de função verifica periodicamente o status de uma ID de trabalho específica, até que o status indique "concluído" ou "falhou".

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 agendamento de trabalhos no SDK

O SDK da Internet das Coisas do Azure para Node.js fornece um exemplo funcional de um aplicativo de serviço que lida com as tarefas de agendamento de trabalhos. Para obter mais informações, confira a página Teste de cliente de trabalho E2E.