Enviar mensagens da cloud para o dispositivo com Hub IoT (Java)

Artigo
06/01/2023

Hub IoT do Azure é um serviço totalmente gerido que ajuda a permitir comunicações bidirecionais fiáveis e seguras entre milhões de dispositivos e uma solução de back-end.

Este artigo mostra-lhe como:

Enviar mensagens de cloud para dispositivo (C2D) a partir do back-end da solução para um único dispositivo através de Hub IoT
Receber mensagens da cloud para o dispositivo num dispositivo
Pedir a confirmação da entrega (feedback), a partir do back-end da solução, para mensagens enviadas para um dispositivo a partir de Hub IoT

Nota

As funcionalidades descritas neste artigo só estão disponíveis no escalão padrão de Hub IoT. Para obter mais informações sobre as camadas de Hub IoT básicas e padrão/gratuitas, consulte Escolher o escalão de Hub IoT adequado para a sua solução.

No final deste artigo, vai executar duas aplicações de consola Java:

HandleMessages: uma aplicação de dispositivo de exemplo incluída com o SDK IoT do Microsoft Azure para Java, que se liga ao hub IoT e recebe mensagens da cloud para o dispositivo.
SendCloudToDevice: envia uma mensagem da cloud para o dispositivo para a aplicação do dispositivo através de Hub IoT e, em seguida, recebe a confirmação da entrega.

Nota

Hub IoT tem suporte do SDK para muitas plataformas e idiomas de dispositivos (C, Java, Python e JavaScript) através dos SDKs de dispositivos IoT do Azure.

Para saber mais sobre as mensagens da cloud para o dispositivo, consulte Enviar mensagens da cloud para o dispositivo a partir de um hub IoT.

Pré-requisitos

Uma subscrição do Azure. Se não tiver uma subscrição do Azure, crie uma conta gratuita antes de começar.
Um hub IoT na sua subscrição do Azure. Se ainda não tiver um hub, pode seguir os passos em Criar um hub IoT.
Um dispositivo registado no hub IoT. Se ainda não registou um dispositivo, registe um no portal do Azure.
Este artigo utiliza código de exemplo do SDK do Azure IoT para Java.
- Transfira ou clone o repositório do SDK do GitHub para o seu computador de desenvolvimento.
- Certifique-se de que o Java SE Development Kit 8 está instalado no seu computador de desenvolvimento. Certifique-se de que seleciona Java 8 em Suporte de longo prazo para aceder às transferências do JDK 8.
Maven 3
Certifique-se de que a porta 8883 está aberta na firewall. O exemplo de dispositivo neste artigo utiliza o protocolo MQTT, que comunica através da porta 8883. Esta porta pode ser bloqueada em alguns ambientes de rede empresarial e educacional. Para obter mais informações e formas de resolver este problema, veja Ligar ao Hub IoT (MQTT).

Obter a cadeia de ligação do dispositivo

Neste artigo, vai executar uma aplicação de exemplo que simula um dispositivo, que recebe mensagens da cloud para o dispositivo enviadas através da sua Hub IoT. A aplicação de exemplo HandleMessages incluída com o SDK IoT do Microsoft Azure para Java liga-se ao seu hub IoT e atua como o seu dispositivo simulado. O exemplo utiliza a cadeia de ligação primária do dispositivo registado no hub IoT.

Para obter a cadeia de ligação primária de um dispositivo registado no hub IoT, siga estes passos:

Na portal do Azure, selecione Grupos de recursos. Selecione o grupo de recursos onde o hub está localizado e, em seguida, selecione o seu hub na lista de recursos.
No painel esquerdo do hub IoT, em Gestão de Dispositivos, selecione Dispositivos.
Na lista de dispositivos, selecione o dispositivo adequado.
Copie a cadeia de ligação Primária e guarde o valor.

Receber mensagens na aplicação do dispositivo

Nesta secção, execute a aplicação de dispositivo de exemplo HandleMessages para receber mensagens C2D enviadas através do hub IoT. Abra uma nova linha de comandos e navegue para a pasta azure-iot-sdk-java\iothub\device\iot-device-samples\handle-messages , na pasta onde expandiu o SDK Java do Azure IoT. Execute os seguintes comandos, substituindo o valor do {Your device connection string} marcador de posição pela cadeia de ligação do dispositivo que copiou do dispositivo registado no hub IoT.

mvn clean package -DskipTests
java -jar ./target/handle-messages-1.0.0-with-deps.jar "{Your device connection string}"

O resultado seguinte é da aplicação de dispositivo de exemplo depois de ter iniciado e ligado com êxito ao seu hub IoT:

5/22/2023 11:13:18 AM> Press Control+C at any time to quit the sample.
     
Starting...
Beginning setup.
Successfully read input parameters.
Using communication protocol MQTT.
2023-05-23 09:51:06,062 INFO (main) [com.microsoft.azure.sdk.iot.device.transport.ExponentialBackoffWithJitter] - NOTE: A new instance of ExponentialBackoffWithJitter has been created with the following properties. Retry Count: 2147483647, Min Backoff Interval: 100, Max Backoff Interval: 10000, Max Time Between Retries: 100, Fast Retry Enabled: true
2023-05-23 09:51:06,187 DEBUG (main) [com.microsoft.azure.sdk.iot.device.ClientConfiguration] - Device configured to use software based SAS authentication provider
2023-05-23 09:51:06,187 INFO (main) [com.microsoft.azure.sdk.iot.device.transport.ExponentialBackoffWithJitter] - NOTE: A new instance of ExponentialBackoffWithJitter has been created with the following properties. Retry Count: 2147483647, Min Backoff Interval: 100, Max Backoff Interval: 10000, Max Time Between Retries: 100, Fast Retry Enabled: true
2023-05-23 09:51:06,202 DEBUG (main) [com.microsoft.azure.sdk.iot.device.DeviceClient] - Initialized a DeviceClient instance using SDK version 2.1.5
Successfully created an IoT Hub client.
Successfully set message callback.
2023-05-23 09:51:06,205 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.mqtt.MqttIotHubConnection] - Opening MQTT connection...
2023-05-23 09:51:06,218 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.mqtt.Mqtt] - Sending MQTT CONNECT packet...
2023-05-23 09:51:07,308 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.mqtt.Mqtt] - Sent MQTT CONNECT packet was acknowledged
2023-05-23 09:51:07,308 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.mqtt.Mqtt] - Sending MQTT SUBSCRIBE packet for topic devices/US60536-device/messages/devicebound/#
2023-05-23 09:51:07,388 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.mqtt.Mqtt] - Sent MQTT SUBSCRIBE packet for topic devices/US60536-device/messages/devicebound/# was acknowledged
2023-05-23 09:51:07,388 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.mqtt.MqttIotHubConnection] - MQTT connection opened successfully
2023-05-23 09:51:07,388 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - The connection to the IoT Hub has been established
2023-05-23 09:51:07,404 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - Updating transport status to new status CONNECTED with reason CONNECTION_OK
2023-05-23 09:51:07,404 DEBUG (main) [com.microsoft.azure.sdk.iot.device.DeviceIO] - Starting worker threads
2023-05-23 09:51:07,408 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - Invoking connection status callbacks with new status details

CONNECTION STATUS UPDATE: CONNECTED
CONNECTION STATUS REASON: CONNECTION_OK
CONNECTION STATUS THROWABLE: null

The connection was successfully established. Can send messages.
2023-05-23 09:51:07,408 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - Client connection opened successfully
2023-05-23 09:51:07,408 INFO (main) [com.microsoft.azure.sdk.iot.device.DeviceClient] - Device client opened successfully
Opened connection to IoT Hub. Messages sent to this device will now be received.
Press any key to exit...

O execute método na AppMessageCallback classe devolve IotHubMessageResult.COMPLETE. Este estado notifica Hub IoT que a mensagem foi processada com êxito e que a mensagem pode ser removida em segurança da fila do dispositivo. O dispositivo deve devolver este valor quando o processamento for concluído com êxito, independentemente do protocolo que estiver a utilizar.

Com AMQP e HTTPS, mas não MQTT, o dispositivo também pode:

Abandone uma mensagem, o que resulta em Hub IoT manter a mensagem na fila do dispositivo para consumo futuro.
Rejeitar uma mensagem, que remove permanentemente a mensagem da fila do dispositivo.

Se ocorrer algo que impeça o dispositivo de concluir, abandonar ou rejeitar a mensagem, Hub IoT colocará a mensagem novamente em fila após um período de tempo limite fixo. Por este motivo, a lógica de processamento de mensagens na aplicação do dispositivo tem de ser idempotente, para que receber a mesma mensagem várias vezes produza o mesmo resultado.

Para obter mais informações sobre o ciclo de vida das mensagens da cloud para o dispositivo e como Hub IoT processa mensagens da cloud para o dispositivo, consulte Enviar mensagens da cloud para o dispositivo a partir de um hub IoT.

Nota

Se utilizar HTTPS em vez de MQTT ou AMQP como transporte, a instância DeviceClient verifica se existem mensagens de Hub IoT com pouca frequência (um mínimo de 25 em 25 minutos). Para obter mais informações sobre as diferenças entre o suporte MQTT, AMQP e HTTPS, veja Orientação de comunicações da cloud para dispositivo e Escolha um protocolo de comunicação.

Obter a cadeia de ligação do hub IoT

Neste artigo, vai criar um serviço de back-end para enviar mensagens da cloud para o dispositivo através do seu Hub IoT. Para enviar mensagens da cloud para o dispositivo, o seu serviço precisa da permissão de ligação do serviço . Por predefinição, todas as Hub IoT são criadas com uma política de acesso partilhado denominada serviço que concede esta permissão.

Para obter a cadeia de ligação Hub IoT para a política de serviço, siga estes passos:

Na portal do Azure, selecione Grupos de recursos. Selecione o grupo de recursos onde o hub está localizado e, em seguida, selecione o seu hub na lista de recursos.
No painel do lado esquerdo do hub IoT, selecione Políticas de acesso partilhado.
Na lista de políticas, selecione a política de serviço .
Copie a cadeia de ligação Primária e guarde o valor.

Para obter mais informações sobre Hub IoT políticas e permissões de acesso partilhado, veja Controlo de acesso e permissões.

Enviar uma mensagem da cloud para o dispositivo

Nesta secção, vai criar uma aplicação de consola Java que envia mensagens da cloud para o dispositivo para a aplicação de dispositivo simulado. Precisa do ID do dispositivo do seu dispositivo e da cadeia de ligação do hub IoT.

Crie um projeto maven denominado send-c2d-messages com o seguinte comando na linha de comandos. Tenha em atenção que este comando é um comando único e longo:
```
mvn archetype:generate -DgroupId=com.mycompany.app -DartifactId=send-c2d-messages -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false
```
Na linha de comandos, navegue para a nova pasta send-c2d-messages.
Com um editor de texto, abra o ficheiro pom.xml na pasta send-c2d-messages e adicione a seguinte dependência ao nó de dependências . Adicionar a dependência permite-lhe utilizar o pacote iothub-java-service-client na sua aplicação para comunicar com o seu serviço hub IoT:
```
<dependency>
  <groupId>com.microsoft.azure.sdk.iot</groupId>
  <artifactId>iot-service-client</artifactId>
  <version>1.7.23</version>
</dependency>
```
Nota

Pode verificar a versão mais recente do iot-service-client utilizando a pesquisa Maven.
Guarde e feche o ficheiro pom.xml.
Com um editor de texto, abra o ficheiro send-c2d-messages\src\main\java\com\mycompany\app\App.java.

Adicione as seguintes declarações de importação ao ficheiro:

import com.microsoft.azure.sdk.iot.service.*;
import java.io.IOException;
import java.net.URISyntaxException;

Adicione as seguintes variáveis de nível de classe à classe App , substituindo {yourhubconnectionstring} e {yourdeviceid} pelos valores que anotou anteriormente:

private static final String connectionString = "{yourhubconnectionstring}";
private static final String deviceId = "{yourdeviceid}";
private static final IotHubServiceClientProtocol protocol =    
    IotHubServiceClientProtocol.AMQPS;

Substitua o método principal pelo seguinte código. Este código liga-se ao seu hub IoT, envia uma mensagem para o seu dispositivo e, em seguida, aguarda uma confirmação de que o dispositivo recebeu e processou a mensagem:

public static void main(String[] args) throws IOException,
    URISyntaxException, Exception {
  ServiceClient serviceClient = ServiceClient.createFromConnectionString(
    connectionString, protocol);

  if (serviceClient != null) {
    serviceClient.open();
    FeedbackReceiver feedbackReceiver = serviceClient
      .getFeedbackReceiver();
    if (feedbackReceiver != null) feedbackReceiver.open();

    Message messageToSend = new Message("Cloud to device message.");
    messageToSend.setDeliveryAcknowledgement(DeliveryAcknowledgement.Full);

    serviceClient.send(deviceId, messageToSend);
    System.out.println("Message sent to device");

    FeedbackBatch feedbackBatch = feedbackReceiver.receive(10000);
    if (feedbackBatch != null) {
      System.out.println("Message feedback received, feedback time: "
        + feedbackBatch.getEnqueuedTimeUtc().toString());
    }

    if (feedbackReceiver != null) feedbackReceiver.close();
    serviceClient.close();
  }
}

Nota

Para simplificar, este artigo não implementa uma política de repetição. No código de produção, deve implementar políticas de repetição (como o backoff exponencial), conforme sugerido no artigo Processamento Transitório de Falhas.

Para criar a aplicação send-c2d-messages com o Maven, execute o seguinte comando na linha de comandos na pasta simulated-device:
```
mvn clean package -DskipTests
```

Executar as aplicações

Está agora pronto para executar as aplicações.

Numa linha de comandos na pasta azure-iot-sdk-java\iothub\device\iot-device-samples\handle-messages , execute os seguintes comandos, substituindo o valor do {Your device connection string} marcador de posição pela cadeia de ligação do dispositivo que copiou do dispositivo registado no seu hub IoT. Este passo inicia a aplicação de dispositivo de exemplo, que envia telemetria para o seu hub IoT e escuta as mensagens da cloud para o dispositivo enviadas a partir do seu hub:
```
java -jar ./target/handle-messages-1.0.0-with-deps.jar "{Your device connection string}"
```
Numa linha de comandos na pasta send-c2d-messages , execute o seguinte comando para enviar uma mensagem da cloud para o dispositivo e aguarde pela confirmação de comentários:
```
mvn exec:java -Dexec.mainClass="com.mycompany.app.App"
```

Passos seguintes

No artigo, aprendeu a enviar e receber mensagens da cloud para o dispositivo.

Para saber mais sobre as mensagens da cloud para o dispositivo, consulte Enviar mensagens da cloud para o dispositivo a partir de um hub IoT.
Para saber mais sobre Hub IoT formatos de mensagens, consulte Criar e ler mensagens Hub IoT.

Enviar mensagens da cloud para o dispositivo com Hub IoT (Java)

Pré-requisitos

Obter a cadeia de ligação do dispositivo

Receber mensagens na aplicação do dispositivo

Obter a cadeia de ligação do hub IoT

Enviar uma mensagem da cloud para o dispositivo

Executar as aplicações

Passos seguintes

Recursos adicionais