Partilhar via

Agendar e transmitir trabalhos (.NET)

  • Artigo

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

  • Atualizar as propriedades pretendidas

  • Atualizar tags

  • Invocar métodos diretos

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, um aplicativo back-end pode usar um trabalho para invocar um método direto em 10.000 dispositivos que reinicializa 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 acompanha 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 certa do Hub IoT para sua solução.

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

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

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

Nota

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

Pré-requisitos

  • Visual Studio.

  • Um hub IoT em sua assinatura do Azure. Se você ainda não tiver um hub, siga 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 neste artigo usa o protocolo MQTT, que 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).

Criar uma aplicação de dispositivo simulada

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 testes e avaliações, mas autenticar um dispositivo usando certificados X.509 é uma abordagem mais segura. Para saber mais, consulte Práticas > recomendadas de segurança Segurança de conexão.

  1. No Visual Studio, selecione Criar um novo projeto e escolha o modelo de projeto Aplicativo de Console (.NET Framework ). Selecione Seguinte para continuar.

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

    Captura de tela do pop-up 'Configurar seu 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 , procure e escolha Microsoft.Azure.Devices.Client. Selecione Instalar.

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

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

  6. Adicione as seguinte declarações using na parte superior do ficheiro 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 Programa. Substitua o valor do 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 direct 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 gêmeos de dispositivo no dispositivo:

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

  10. Finalmente, adicione o seguinte código ao método Main para abrir a conexão com seu 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 crie sua solução.

Nota

Para simplificar, este artigo não implementa políticas de nova tentativa. No código de produção, você deve implementar 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 gêmeo do dispositivo e monitora o progresso de cada trabalho. Para executar essas operações, seu serviço precisa das permissões de leitura e gravação do Registro. Por padrão, cada 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 onde o hub está localizado e, em seguida, selecione o hub na lista de recursos.

  2. No painel 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 políticas e permissões 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 autenticar em um serviço com ID do Microsoft Entra ou identidades gerenciadas é uma abordagem mais segura. Para saber mais, consulte Práticas > recomendadas de segurança Segurança na nuvem.

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

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

  1. No Visual Studio, selecione Arquivo>Novo>Projeto. Em Criar um novo projeto, escolha Aplicativo de Console (.NET Framework) e selecione Avançar.

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

    Nomeie e configure seu projeto ScheduleJob

    Captura de tela do pop-up 'Configurar seu novo projeto' no Visual Studio, onde 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 selecione Gerenciar Pacotes NuGet.

  5. No Gerenciador de Pacotes NuGet, selecione Procurar, procure 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 Azure IoT e suas dependências.

  6. Adicione as seguinte declarações using na parte superior do ficheiro Program.cs:

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

  7. Adicione a seguinte using instrução se ainda não estiver presente nas instruções padrão.

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

  8. Adicione os seguintes campos à classe Programa. Substitua os espaços reservados 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 Program :

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

    Nota

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

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

    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 crie sua solução.

Executar as aplicações

Já está pronto para executar as aplicações.

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

  2. Selecione Projeto de inicialização de propriedades>comuns e, em seguida, selecione Vários projetos de inicialização.

  3. Certifique-se de que SimulateDeviceMethods está no topo da lista, seguido de ScheduleJob. Defina ambas as 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ê vê a saída de aplicativos de dispositivo e back-end.

    Execute os aplicativos para agendar trabalhos

Próximos passos

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

Para continuar explorando o Hub IoT e os padrões de gerenciamento de dispositivos, 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+.