Compartilhar via

Agendar e transmitir trabalhos (.NET)

  • Artigo

Use o Hub IoT do Azure para agendar e controlar os trabalhos que atualizam milhões de dispositivos. Use trabalhos para:

  • Atualizar as propriedades desejadas

  • Marcas de atualização

  • Chamar métodos diretos

Um trabalho encapsula uma dessas ações e controla a execução em um conjunto de dispositivos definido por uma consulta de dispositivo gêmeo. Por exemplo, um aplicativo de back-end pode usar um trabalho para invocar um método direto em 10.000 dispositivos que reinicie os dispositivos. Você especifica o conjunto de dispositivos com uma consulta de dispositivo gêmeo e agenda o trabalho para execução futura. O trabalho controla o andamento conforme cada um dos dispositivos recebe e executa o método direto de reinicialização.

Para saber mais sobre cada uma dessas capacidades, consulte:

Observação

Os recursos descritos neste artigo estão disponíveis apenas na camada padrão do Hub IoT. Para saber mais sobre as camadas Básico e Standard/Gratuita do Hub IoT, confira Escolher a camada ideal do Hub IoT para sua solução.

Este artigo mostra como criar dois aplicativos de console do .NET (C#):

  • Um aplicativo de dispositivo, SimulateDeviceMethods, que implementa um método direto chamado LockDoor, que pode ser chamado pelo aplicativo de back-end.

  • Um aplicativo de back-end, ScheduleJob, que cria dois trabalhos. Um trabalho chama o método direto lockDoor e outro envia atualizações de propriedade desejadas para vários dispositivos.

Observação

Consulte os SDKs da IoT do Azure para obter mais informações sobre as ferramentas do SDK disponíveis para compilar aplicativos de dispositivo e back-end.

Pré-requisitos

  • Visual Studio.

  • Um Hub IoT na assinatura do Azure. Caso você ainda não tenha um hub, poderá seguir as etapas em Criar um hub IoT.

  • Um dispositivo registrado em seu hub IoT. Se você não tiver um dispositivo em seu hub IoT, siga as etapas em Registrar um dispositivo.

  • Verifique se a porta 8883 está aberta no firewall. O exemplo de dispositivo deste artigo usa o protocolo MQTT, que 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).

Criar um aplicativo de dispositivo simulado

Nesta seção, você cria um aplicativo de console .NET que responde a um método direto chamado pelo back-end da solução.

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.

  1. No Visual Studio, selecione Criar um projeto e, em seguida, escolha o modelo de projeto Aplicativo de console (.NET Framework) . Selecione Avançar para continuar.

  2. Em Configurar seu novo projeto, nomeie o projeto como SimulateDeviceMethods e, em seguida, selecione Avançar.

    Captura de tela do pop-up 'Configurar novo projeto' no Visual Studio.

  3. Aceite a versão padrão do .NET Framework e selecione Criar para criar o projeto.

  4. No Gerenciador de Soluções, clique com o botão direito do mouse no projeto SimulateDeviceMethods e selecione Gerenciar Pacotes NuGet.

  5. No Gerenciador de Pacotes NuGet, selecione Procurar para pesquisar e escolher Microsoft.Azure.Devices.Client. Selecione Instalar.

    Captura de tela do Gerenciador de pacotes do NuGet no Visual Studio.

    Esta etapa baixa, instala e adiciona uma referência ao pacote NuGet do SDK do dispositivo IoT do Azure e as dependências dele.

  6. Adicione as instruções using abaixo na parte superior do arquivo Program.cs :

    using Microsoft.Azure.Devices.Client;
using Microsoft.Azure.Devices.Shared;
using Newtonsoft.Json;
using System.Threading.Tasks;
using System.Text;

  7. Adicione os seguintes campos à classe Program . Substitua o valor de espaço reservado pela cadeia de conexão do dispositivo que você anotou na seção anterior:

    static string DeviceConnectionString = "<yourDeviceConnectionString>";
static DeviceClient Client = null;

  8. Adicione o seguinte código para implementar o método direto no dispositivo:

    static Task<MethodResponse> LockDoor(MethodRequest methodRequest, object userContext)
{
    Console.WriteLine();
    Console.WriteLine("Locking Door!");
    Console.WriteLine("\nReturning response for method {0}", methodRequest.Name);

    string result = "'Door was locked.'";
    return Task.FromResult(new MethodResponse(Encoding.UTF8.GetBytes(result), 200));
}

  9. Adicione o seguinte método para implementar o ouvinte de dispositivo gêmeo no dispositivo:

    private static async Task OnDesiredPropertyChanged(TwinCollection desiredProperties, 
  object userContext)
{
    Console.WriteLine("Desired property change:");
    Console.WriteLine(JsonConvert.SerializeObject(desiredProperties));
}

  10. Por fim, adicione o seguinte código ao método Principal para abrir a conexão para o hub IoT e inicializar o ouvinte do método:

    try
{
    Console.WriteLine("Connecting to hub");
    Client = DeviceClient.CreateFromConnectionString(DeviceConnectionString, 
      TransportType.Mqtt);

    Client.SetMethodHandlerAsync("LockDoor", LockDoor, null);
    Client.SetDesiredPropertyUpdateCallbackAsync(OnDesiredPropertyChanged, null);

    Console.WriteLine("Waiting for direct method call and device twin update\n Press enter to exit.");
    Console.ReadLine();

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

    Client.SetMethodHandlerAsync("LockDoor", null, null);
    Client.CloseAsync().Wait();
}
catch (Exception ex)
{
    Console.WriteLine();
    Console.WriteLine("Error in sample: {0}", ex.Message);
}

  11. Salve seu trabalho e compile sua solução.

Observação

Para simplificar, este artigo não implementa nenhuma política de repetição. No código de produção, implemente políticas de repetição (como repetição de conexão), conforme sugerido em Tratamento de falhas transitórias.

Obter a cadeia de conexão do hub IoT

Neste artigo, você cria um serviço de back-end que agenda um trabalho para invocar um método direto em um dispositivo, agenda um trabalho para atualizar o dispositivo gêmeo e monitora o progresso de cada trabalho. 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 a cadeia de conexão do Hub IoT para a política registryReadWrite, siga estas etapas:

  1. No portal do Azure, selecione Grupos de recursos. Selecione o grupo de recursos em que o Hub está localizado e, em seguida, selecione o seu hub na lista de recursos.

  2. No painel do lado esquerdo do hub, selecione Políticas de acesso compartilhado.

  3. Na lista de políticas, selecione a política registryReadWrite.

  4. Copie a Cadeia de conexão primária e salve o valor.

    Captura de tela que mostra como recuperar a cadeia de conexão

Para obter mais informações sobre permissões e políticas de acesso compartilhado do Hub IoT, consulte Controle de acesso e permissões.

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.

Agendar trabalhos para chamar um método direto e enviar atualizações ao dispositivo gêmeo

Nesta seção, você cria um aplicativo de console .NET (usando C#) que usa trabalhos para chamar o método direto LockDoor e enviar as atualizações de propriedade desejadas para vários dispositivos.

  1. No Visual Studio, selecione Arquivo>Novo>Projeto. Em Criar um projeto, escolha Aplicativo de Console (.NET Framework) e, em seguida, selecione Próximo.

  2. Em Configurar novo projeto, nomeie o projeto como ScheduleJob e selecione Criar.

    Nomear e configurar o projeto ScheduleJob

    Captura de tela do pop-up 'Configurar novo projeto' no Visual Studio, na qual você adiciona um nome.

  3. Aceite a versão padrão do .NET Framework e selecione Criar para criar o projeto.

  4. No Gerenciador de Soluções, clique com o botão direito do mouse no projeto ScheduleJob e, em seguida, selecione Gerenciar Pacotes NuGet.

  5. No Gerenciador de Pacotes NuGet, selecione Procurar, pesquise e escolha Microsoft.Azure.Devices e, em seguida, selecione Instalar.

    Esta etapa baixa, instala e adiciona uma referência ao pacote NuGet do SDK do serviço IoT do Azure e suas dependências.

  6. Adicione as instruções using abaixo na parte superior do arquivo Program.cs :

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

  7. Adicione a instrução using a seguir caso ela não esteja presente nas instruções padrão.

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

  8. Adicione os seguintes campos à classe Program . Substitua o valor do espaço reservado pela cadeia de conexão do Hub IoT que você copiou anteriormente em Obter a cadeia de conexão do hub IoT e o nome do seu dispositivo.

    static JobClient jobClient;
static string connString = "<yourIotHubConnectionString>";
static string deviceId = "<yourDeviceId>";

  9. Adicione o seguinte método à classe Programa :

    public static async Task MonitorJob(string jobId)
{
    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));
}

  10. Adicione o seguinte método à classe Programa :

    public static async Task StartMethodJob(string jobId)
{
    CloudToDeviceMethod directMethod = 
      new CloudToDeviceMethod("LockDoor", TimeSpan.FromSeconds(5), 
      TimeSpan.FromSeconds(5));

    JobResponse result = await jobClient.ScheduleDeviceMethodAsync(jobId,
        $"DeviceId IN ['{deviceId}']",
        directMethod,
        DateTime.UtcNow,
        (long)TimeSpan.FromMinutes(2).TotalSeconds);

    Console.WriteLine("Started Method Job");
}

  11. Adicione outro método à classe Programa:

    public static async Task StartTwinUpdateJob(string jobId)
{
    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;

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

    Console.WriteLine("Started Twin Update Job");
}

    Observação

    Para obter mais informações sobre a sintaxe de consulta, consulte linguagem de consulta do Hub IoT.

  12. Por fim, adicione as seguintes linhas ao método Principal :

    Console.WriteLine("Press ENTER to start running jobs.");
Console.ReadLine();

jobClient = JobClient.CreateFromConnectionString(connString);

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

StartMethodJob(methodJobId);
MonitorJob(methodJobId).Wait();
Console.WriteLine("Press ENTER to run the next job.");
Console.ReadLine();

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

StartTwinUpdateJob(twinUpdateJobId);
MonitorJob(twinUpdateJobId).Wait();
Console.WriteLine("Press ENTER to exit.");
Console.ReadLine();

  13. Salve seu trabalho e compile sua solução.

Executar os aplicativos

Agora você está pronto para executar os aplicativos.

  1. No Gerenciador de Soluções do Visual Studio, clique com o botão direito do mouse na solução e selecione Definir Projetos de Inicialização.

  2. Selecione Propriedades Comuns>Projeto de Inicialização e, em seguida, selecione Vários projetos de inicialização.

  3. Certifique-se de que SimulateDeviceMethods está no topo da lista, seguido por ScheduleJob. Defina ambas as suas ações como Iniciar e selecione OK.

  4. Execute os projetos clicando em Iniciar ou vá para o menu Depurar e clique em Iniciar depuração.

    Você verá a saída do dispositivo e dos aplicativos back-end.

    Executar os aplicativos para agendar trabalhos

Próximas etapas

Neste artigo, você agendou trabalhos para executar um método direto e atualizar as propriedades do dispositivo gêmeo.

Para continuar explorando os padrões de Hub IoT e de gerenciamento de dispositivo, atualize uma imagem no tutorial Atualização de dispositivo para o Hub IoT do Azure usando a imagem de referência do Raspberry Pi 3 B +.