Enviar mensagens da cloud para o dispositivo a partir de um hub IoT
Para enviar notificações unidirecionais para uma aplicação de dispositivo a partir do back-end da sua solução, envie mensagens da cloud para o dispositivo a partir do hub IoT para o seu dispositivo. Para uma discussão sobre outras opções de cloud para dispositivo suportadas pelo Hub IoT do Azure, veja Orientações de comunicações da cloud para o dispositivo.
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.
Envia mensagens da cloud para o dispositivo através de um ponto final com acesso ao serviço, /mensagens/dispositivos. Em seguida, um dispositivo recebe as mensagens através de um ponto final específico do dispositivo, /devices/{deviceId}/messages/devicebound.
Para direcionar cada mensagem da cloud para o dispositivo num único dispositivo, o hub IoT define a propriedade para/devices/{deviceId}/messages/devicebound.
Cada fila de dispositivos contém, no máximo, 50 mensagens da cloud para o dispositivo. Ocorre um erro se tentar enviar mais mensagens para o mesmo dispositivo.
O ciclo de vida da mensagem da cloud para o dispositivo
Para garantir a entrega de mensagens pelo menos uma vez, o hub IoT mantém as mensagens da cloud para o dispositivo em filas por dispositivo. Os dispositivos têm de reconhecer explicitamente a conclusão de uma mensagem antes de o hub IoT remover a mensagem da fila. Esta abordagem garante resiliência contra falhas de conectividade e dispositivos.
O gráfico de estado do ciclo de vida é apresentado no seguinte diagrama:
Quando o serviço hub IoT envia uma mensagem para um dispositivo, o serviço define o estado da mensagem como Enqueued. Quando um dispositivo quer receber uma mensagem, o hub IoT bloqueia a mensagem ao definir o estado como Invisível. Este estado permite que outros threads no dispositivo comecem a receber outras mensagens. Quando um thread de dispositivo conclui o processamento de uma mensagem, notifica o hub IoT ao concluir 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 como o estado com letra Dead . Os dispositivos que se ligam através do protocolo MQTT (Message Queuing Telemetry Transport) não podem rejeitar mensagens da cloud para o dispositivo.
Abandone a mensagem, o que faz com que o hub IoT volte a colocar a mensagem na fila, com o estado definido como Enqueued. Os dispositivos que se ligam através do protocolo MQTT não podem abandonar mensagens da cloud para o dispositivo.
Um thread pode não conseguir processar uma mensagem sem notificar o hub IoT. Neste caso, as mensagens transitam automaticamente do estado Invisível para o estado Enqueued após um tempo limite de visibilidade (ou tempo limite de bloqueio). O valor deste tempo limite é de um minuto e não pode ser alterado.
A propriedade contagem de entrega máxima no hub IoT determina o número máximo de vezes que uma mensagem pode fazer a transição entre os estados Enqueued e Invisible . Após esse número de transições, o hub IoT define o estado da mensagem como Sem letra. Da mesma forma, o hub IoT define o estado de uma mensagem para Dead lettered após o tempo de expiração. Para obter mais informações, veja Expiração da mensagem (tempo de vida).
O artigo Como enviar mensagens da cloud para o dispositivo com Hub IoT mostra-lhe como enviar mensagens da cloud para o dispositivo e recebê-las num dispositivo.
Normalmente, um dispositivo conclui uma mensagem da cloud para o dispositivo quando a perda da mensagem não afeta a lógica da aplicação. Um exemplo desta conclusão pode ser quando o dispositivo persiste no conteúdo da mensagem localmente ou executou uma operação com êxito. A mensagem também pode conter informações transitórias, cuja perda não afetaria a funcionalidade da aplicação. Por vezes, para tarefas de execução prolongada, pode:
Conclua a mensagem da cloud para o dispositivo depois de o dispositivo ter mantido a descrição da tarefa no armazenamento local.
Notifique o back-end da solução com uma ou mais mensagens do dispositivo para a cloud em várias fases de progresso da tarefa.
Expiração da mensagem (tempo de vida)
Cada mensagem da cloud para o dispositivo tem um tempo de expiração. Esta hora é definida por uma das seguintes opções:
- A propriedade ExpiryTimeUtc no serviço
- O hub IoT, ao utilizar a hora predefinida para viver especificada como uma propriedade do hub IoT
Para obter mais informações sobre a expiração da mensagem, veja Opções de configuração da cloud para o dispositivo.
Uma forma comum de tirar partido da expiração de uma mensagem e evitar o envio de mensagens para dispositivos desligados é definir o tempo curto para valores dinâmicos . Esta abordagem obtém o mesmo resultado que manter o estado de ligação do dispositivo, mas é mais eficiente. Quando pede confirmações de mensagens, o hub IoT notifica-o de que dispositivos são:
- Capaz de receber mensagens.
- Não estão online ou falharam.
Comentários de mensagens
Quando envia uma mensagem da cloud para o dispositivo, o serviço pode pedir a entrega de comentários por mensagem sobre o estado final dessa mensagem. Pode configurar o feedback de mensagens ao definir a propriedade da aplicação iothub-ack na mensagem cloud para dispositivo que está a ser enviada para um dos quatro valores seguintes:
| Valor da propriedade Ack | Comportamento |
|---|---|
| nenhum | Predefinição. O hub IoT não gera uma mensagem de feedback. |
| positivo | Se a mensagem da cloud para o dispositivo atingir o estado Concluído , o hub IoT gera uma mensagem de feedback. |
| negativo | Se a mensagem da cloud para o dispositivo atingir o estado Com letras não entregues , o hub IoT gera uma mensagem de feedback. |
| cheio | O hub IoT gera uma mensagem de feedback em ambos os casos. |
Se o valor da propriedade Ack estiver definido como completo e não receber uma mensagem de feedback, significa que a mensagem de feedback expirou. O serviço não consegue saber o que aconteceu à mensagem original. Na prática, um serviço deve garantir que pode processar os comentários antes de expirar. O tempo máximo de expiração é de dois dias, o que deixa tempo para que o serviço seja executado novamente se ocorrer uma falha.
Conforme explicado em Pontos Finais, o hub IoT fornece feedback através de um ponto final com acesso ao serviço, /mensagens/servicebound/feedback, como mensagens. A semântica para receber comentários é a mesma que para mensagens da cloud para o dispositivo. Sempre que possível, os comentários das mensagens são colocados em lotes numa única mensagem, com o seguinte formato:
| Propriedade | Descrição |
|---|---|
| EnqueuedTime | Um carimbo de data/hora que indica quando a mensagem de feedback foi recebida pelo hub. |
| IDUtilizador | {iot hub name} |
| ContentType | application/vnd.microsoft.iothub.feedback.json |
O sistema enviará o feedback quando o lote chegar a 64 mensagens ou em 15 segundos a partir do último envio, o que ocorrer primeiro.
O corpo é uma matriz de registos serializada por JSON, cada uma com as seguintes propriedades:
| Propriedade | Descrição |
|---|---|
| enqueuedTimeUtc | Um carimbo de data/hora que indica quando ocorreu o resultado da mensagem. 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 cloud para o dispositivo à qual estas informações de feedback estão relacionadas. |
| statusCode | Uma cadeia necessária, utilizada em mensagens de feedback geradas pelo hub IoT: Com êxito Expirada DeliveryCountExceeded Rejeitado Removido |
| descrição | Valores de cadeia para StatusCode. |
| deviceId | O DeviceId do dispositivo de destino da mensagem cloud-to-device à qual este feedback está relacionado. |
| deviceGenerationId | O DeviceGenerationId do dispositivo de destino da mensagem cloud-to-device à qual este feedback está relacionado. |
O serviço tem de especificar um MessageId para que a mensagem da cloud para o dispositivo possa correlacionar o respetivo feedback com a mensagem original.
O corpo de uma mensagem de feedback é apresentado no seguinte exemplo de código:
[
{
"originalMessageId": "0987654321",
"enqueuedTimeUtc": "2015-07-28T16:24:48.789Z",
"statusCode": "Success",
"description": "Success",
"deviceId": "123",
"deviceGenerationId": "abcdefghijklmnopqrstuvwxyz"
},
{
...
},
...
]
Comentários pendentes para dispositivos eliminados
Quando um dispositivo é eliminado, os comentários pendentes também são eliminados. O feedback do dispositivo é enviado em lotes. Uma janela estreita, muitas vezes inferior a um segundo, pode ocorrer entre quando um dispositivo confirma a receção da mensagem e quando o lote de comentários seguinte é preparado. Se um dispositivo for eliminado nessa janela estreita, o feedback não ocorrerá.
Pode resolver este comportamento ao aguardar um período de tempo para que os comentários pendentes cheguem antes de eliminar o seu dispositivo. Os comentários de mensagens relacionadas devem ser assumidos como perdidos quando um dispositivo é eliminado.
Opções de configuração da cloud para o dispositivo
Cada hub IoT expõe as seguintes opções de configuração para mensagens da cloud para o dispositivo:
| Propriedade | Descrição | Intervalo e predefinição |
|---|---|---|
| defaultTtlAsIso8601 | TTL predefinido para mensagens da cloud para o dispositivo | ISO_8601 intervalo até dois dias (mínimo de um minuto); predefinição: uma hora |
| maxDeliveryCount | Contagem máxima de entrega para filas de cloud para dispositivo por dispositivo | 1 a 100; predefinição: 10 |
| feedback.ttlAsIso8601 | Retenção para mensagens de comentários vinculadas ao serviço | ISO_8601 intervalo até dois dias (mínimo de um minuto); predefinição: uma hora |
| feedback.maxDeliveryCount | Número máximo de entrega para a fila de comentários | 1 a 100; predefinição: 10 |
| feedback.lockDurationAsIso8601 | Duração do bloqueio da fila de comentários | ISO_8601 intervalo de 5 a 300 segundos (mínimo de cinco segundos); predefinição: 60 segundos. |
Pode definir as opções de configuração de uma das seguintes formas:
- portal do Azure: em Definições do hub no hub IoT, selecione Pontos finais incorporados e aceda a Mensagens da Cloud para o dispositivo. (A definição das propriedades feedback.maxDeliveryCount e feedback.lockDurationAsIso8601 não é atualmente suportada no portal do Azure.)
CLI do Azure: utilize 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
Passos seguintes
Para obter informações sobre os SDKs que pode utilizar para receber mensagens da cloud para o dispositivo, consulte Hub IoT do Azure SDKs.
Para experimentar a receção de mensagens da cloud para o dispositivo, veja o tutorial Enviar nuvem para dispositivo .