Partilhar via

Compreender as mensagens da nuvem para o dispositivo a partir de um hub IoT

  • Artigo

As mensagens da nuvem para o dispositivo são notificações unidirecionais do back-end da sua solução para um aplicativo de dispositivo. Para obter uma discussão sobre outras opções de nuvem para dispositivo suportadas pelo Hub IoT do Azure, consulte Diretrizes de comunicações de nuvem para dispositivo.

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.

Você envia mensagens da nuvem para o dispositivo por meio de um ponto de extremidade voltado para o serviço, /messages/devicebound. Em seguida, um dispositivo recebe as mensagens através de um ponto de extremidade específico do dispositivo, /devices/{deviceId}/messages/devicebound.

Para direcionar cada mensagem da nuvem para o dispositivo em um único dispositivo, o hub IoT define a propriedade to como /devices/{deviceId}/messages/devicebound.

Cada fila de dispositivos armazena, no máximo, 50 mensagens da nuvem para o dispositivo. Ocorre um erro se tentar enviar mais mensagens para o mesmo dispositivo.

Este artigo discute os conceitos e processos em torno de mensagens da nuvem para o dispositivo. Para obter orientação sobre o desenvolvimento de aplicativos que lidam com mensagens da nuvem para o dispositivo, consulte Enviar e receber mensagens da nuvem para o dispositivo.

O ciclo de vida da mensagem da nuvem para o dispositivo

Para garantir a entrega de mensagens pelo menos uma vez, seu hub IoT persiste mensagens da nuvem para o dispositivo em filas por dispositivo. Os dispositivos devem confirmar explicitamente a conclusão de uma mensagem antes que o hub IoT remova a mensagem da fila. Essa abordagem garante resiliência contra falhas de conectividade e dispositivos.

O gráfico do estado do ciclo de vida é exibido no diagrama a seguir:

Diagrama mostrando o gráfico do estado do ciclo de vida das mensagens da nuvem para o dispositivo.

Quando o serviço hub IoT envia uma mensagem para um dispositivo, o serviço define o estado da mensagem como Enfileirado. Quando um thread de dispositivo está pronto para receber uma mensagem, o hub IoT bloqueia a mensagem definindo o estado como Invisível. Esse estado permite que outros threads no dispositivo comecem a receber outras mensagens. Quando um thread de dispositivo conclui o processamento de uma mensagem, ele notifica o hub IoT completando a mensagem. Em seguida, o hub IoT define o estado como Concluído.

Um dispositivo também pode:

  • Rejeite a mensagem, o que faz com que o hub IoT a defina para o estado com letras mortas . Não há fila de letra morta para recuperar essas mensagens. Os dispositivos que se conectam pelo protocolo MQTT (Transporte de Telemetria de Enfileiramento de Mensagens) não podem rejeitar mensagens da nuvem para o dispositivo.

  • Abandone a mensagem, o que faz com que o hub IoT coloque a mensagem de volta na fila, com o estado definido como Enfileirado. Os dispositivos que se conectam pelo protocolo MQTT não podem abandonar mensagens de nuvem para dispositivo.

Um thread pode falhar ao processar uma mensagem sem notificar o hub IoT. Nesse caso, as mensagens transitam automaticamente do estado Invisível de volta para o estado Enfileirado após um tempo limite de visibilidade (ou tempo limite de bloqueio). A duração deste tempo limite é de um minuto e não pode ser alterada.

A propriedade max delivery count no hub IoT determina o número máximo de vezes que uma mensagem pode transitar entre os estados Enfileirado e Invisível . Após esse número de transições, o hub IoT define o estado da mensagem como letra morta. Da mesma forma, o hub IoT define o estado de uma mensagem como Letra morta após seu tempo de expiração.

Normalmente, um dispositivo conclui uma mensagem de nuvem para dispositivo quando a perda da mensagem não afeta a lógica do aplicativo. Um exemplo dessa conclusão pode ser quando o dispositivo persistiu o conteúdo da mensagem localmente ou executou com êxito uma operação. A mensagem também pode conter informações transitórias, cuja perda não afetaria a funcionalidade do aplicativo. Às vezes, para tarefas de longa duração, você pode:

  • Conclua a mensagem da nuvem para o dispositivo depois que o dispositivo tiver persistido a descrição da tarefa no armazenamento local.

  • Notifique o back-end da solução com uma ou mais mensagens do dispositivo para a nuvem em vários estágios de progresso da tarefa.

Expiração da mensagem (tempo de vida)

Cada mensagem da nuvem para o dispositivo tem um tempo de expiração. Este tempo é definido por uma das seguintes opções:

  • A propriedade ExpiryTimeUtc no serviço
  • O hub IoT, usando o tempo de vida padrão especificado como uma propriedade de hub IoT

Para obter mais informações sobre a expiração de mensagens, consulte Opções de configuração da nuvem para o dispositivo.

Uma maneira comum de aproveitar a expiração de uma mensagem e evitar o envio de mensagens para dispositivos desconectados é definir valores curtos de tempo de vida . Essa abordagem alcança o mesmo resultado que manter o estado de conexão do dispositivo, mas é mais eficiente. Quando você solicita confirmações de mensagens, o hub IoT notifica quais dispositivos são:

  • Capaz de receber mensagens.
  • Não estão online ou falharam.

Feedback da mensagem

Quando você envia uma mensagem da nuvem para o dispositivo, o serviço pode solicitar a entrega de feedback por mensagem sobre o estado final dessa mensagem. Você pode configurar o feedback da mensagem definindo a propriedade do aplicativo iothub-ack na mensagem da nuvem para o dispositivo que está sendo enviada para um dos quatro valores a seguir:

Valor da propriedade Ack Comportamento
nenhum Predefinição. O hub IoT não gera uma mensagem de feedback.
positivo Se a mensagem da nuvem para o dispositivo atingir o estado Concluído , o hub IoT gerará uma mensagem de feedback.
negativo Se a mensagem nuvem-para-dispositivo atingir o estado com letras mortas , o hub IoT gerará uma mensagem de feedback.
completo O hub IoT gera uma mensagem de feedback em ambos os casos.

Se o valor da propriedade Ack estiver definido como completo e você não receber uma mensagem de feedback, isso significa que a mensagem de feedback expirou. O serviço não pode saber o que aconteceu com a mensagem original. Na prática, um serviço deve garantir que pode processar o feedback antes que ele expire. O tempo máximo de expiração é de dois dias, o que deixa tempo para executar o serviço novamente se ocorrer uma falha.

Conforme explicado em Endpoints, o hub IoT fornece feedback por meio de um endpoint voltado para o serviço, /messages/servicebound/feedback, como mensagens. A semântica para receber feedback é a mesma que para mensagens da nuvem para o dispositivo. Sempre que possível, o feedback da mensagem é agrupado em uma única mensagem, com o seguinte formato:

Property Description
EnqueuedTime Um carimbo de data/hora que indica quando a mensagem de feedback foi recebida pelo hub.
UserId {iot hub name}
Tipo de conteúdo application/vnd.microsoft.iothub.feedback.json

O sistema enviará o feedback quando o lote atingir 64 mensagens ou em 15 segundos a partir do último envio, o que ocorrer primeiro.

O corpo é uma matriz serializada por JSON de registros, cada um com as seguintes propriedades:

Property Description
enqueuedTimeUtc Um carimbo de data/hora que indica quando o resultado da mensagem aconteceu. Por exemplo, um carimbo de data/hora que indica quando o hub recebeu a mensagem de feedback ou a mensagem original expirou.
originalMessageId O MessageId da mensagem da nuvem para o dispositivo à qual essas informações de feedback se referem.
statusCode Uma cadeia de caracteres necessária, usada em mensagens de feedback geradas pelo hub IoT:
Sucesso
Expirada
DeliveryCountExceeded
Rejeitado
Expurgado
descrição Valores de cadeia de caracteres para StatusCode.
deviceId O DeviceId do dispositivo de destino da mensagem cloud-to-device à qual este feedback se relaciona.
deviceGenerationId O DeviceGenerationId do dispositivo de destino da mensagem nuvem-para-dispositivo à qual esta parte do feedback se relaciona.

O serviço deve especificar um MessageId para que a mensagem da nuvem para o dispositivo possa correlacionar seus comentários com a mensagem original.

O corpo de uma mensagem de feedback é mostrado no exemplo de código a seguir:

[
  {
    "originalMessageId": "0987654321",
    "enqueuedTimeUtc": "2015-07-28T16:24:48.789Z",
    "statusCode": "Success",
    "description": "Success",
    "deviceId": "123",
    "deviceGenerationId": "abcdefghijklmnopqrstuvwxyz"
  },
  {
    ...
  },
  ...
]

Comentários pendentes para dispositivos excluídos

Quando um dispositivo é excluído, qualquer feedback pendente também é excluído. Os comentários do dispositivo são enviados em lotes. Uma janela estreita, geralmente inferior a um segundo, pode ocorrer entre quando um dispositivo confirma o recebimento da mensagem e quando o próximo lote de feedback é preparado. Se um dispositivo for excluído nessa janela estreita, o feedback não ocorrerá.

Você pode resolver esse comportamento aguardando um período de tempo para que os comentários pendentes cheguem antes de excluir seu dispositivo. O feedback da mensagem relacionada deve ser presumido perdido quando um dispositivo é excluído.

Opções de configuração da nuvem para o dispositivo

Cada hub IoT expõe as seguintes opções de configuração para mensagens da nuvem para o dispositivo:

Property Description Intervalo e padrão
padrãoTtlAsIso8601 TTL padrão para mensagens da nuvem para o dispositivo ISO_8601 intervalo de até dois dias (mínimo de um minuto); Padrão: uma hora
maxDeliveryCount Contagem máxima de entrega para filas de nuvem para dispositivo por dispositivo 1 a 100; padrão: 10
feedback.ttlAsIso8601 Retenção para mensagens de feedback vinculadas ao serviço ISO_8601 intervalo de até dois dias (mínimo de um minuto); Padrão: uma hora
feedback.maxDeliveryCount Contagem máxima de entrega para a fila de comentários 1 a 100; padrão: 10
feedback.lockDurationAsIso8601 Duração do bloqueio para a fila de comentários ISO_8601 intervalo de 5 a 300 segundos (mínimo de cinco segundos); padrão: 60 segundos.

Você pode definir as opções de configuração no portal do Azure ou na CLI do Azure:

  • Portal do Azure: em Configurações de Hub em seu hub IoT, selecione Pontos de extremidade internos e vá para Nuvem para mensagens do dispositivo. (A definição das propriedades feedback.maxDeliveryCount e feedback.lockDurationAsIso8601 não é suportada atualmente no portal do Azure.)

    Definir opções de configuração para mensagens da nuvem para o dispositivo no portal

  • CLI do Azure: use o comando az iot hub update :

    az iot hub update --name {your IoT hub name} \
    --set properties.cloudToDevice.defaultTtlAsIso8601=PT1H0M0S

az iot hub update --name {your IoT hub name} \
    --set properties.cloudToDevice.maxDeliveryCount=10

az iot hub update --name {your IoT hub name} \
    --set properties.cloudToDevice.feedback.ttlAsIso8601=PT1H0M0S

az iot hub update --name {your IoT hub name} \
    --set properties.cloudToDevice.feedback.maxDeliveryCount=10

az iot hub update --name {your IoT hub name} \
    --set properties.cloudToDevice.feedback.lockDurationAsIso8601=PT0H1M0S

Próximos passos

Para obter informações sobre os SDKs que você pode usar para manipular mensagens da nuvem para o dispositivo, consulte SDKs do Hub IoT do Azure.

Para obter orientação sobre o desenvolvimento de aplicativos que lidam com mensagens da nuvem para o dispositivo, consulte Enviar e receber mensagens da nuvem para o dispositivo.