Begrijp cloud-naar-apparaat-berichten van een IoT-hub

Cloud-naar-apparaat-berichten zijn eenrichtingsmeldingen van de back-end van uw oplossing naar een apparaattoepassing. Zie de handleiding Communicatie van cloud naar apparaat voor een bespreking van andere cloud-naar-apparaatopties die worden ondersteund door Azure IoT Hub.

U verzendt cloud-naar-apparaat-berichten via een servicegericht eindpunt, /messages/devicebound. Een apparaat ontvangt vervolgens de berichten via een apparaatspecifiek eindpunt, /devices/{deviceId}/messages/devicebound.

Om elk cloud-naar-apparaat-bericht op een enkel apparaat te richten, stelt uw IoT Hub de to-eigenschap in op /devices/{deviceId}/messages/devicebound.

Elke apparaatwachtrij bevat maximaal 50 cloud-naar-apparaat-berichten. Er treedt een fout op als u meer berichten naar hetzelfde apparaat probeert te verzenden.

In dit artikel worden de concepten en processen voor cloud-naar-apparaat-berichten besproken. Zie Cloud-naar-apparaat-berichten verzenden en ontvangen voor hulp bij het ontwikkelen van toepassingen die cloud-naar-apparaat-berichten verwerken.

De levenscyclus van berichten in de cloud naar het apparaat

Uw IoT-hub bewaart cloud-naar-apparaat-berichten in wachtrijen per apparaat om ten minste één keer de bezorging van berichten te garanderen. Apparaten moeten expliciet bevestigen dat een bericht is voltooid voordat de IoT-hub het bericht uit de wachtrij verwijdert. Deze aanpak garandeert tolerantie tegen connectiviteits- en apparaatfouten.

De levenscyclusstatusgrafiek wordt weergegeven in het volgende diagram:

Wanneer de IoT Hub-service een bericht naar een apparaat verzendt, stelt de service de berichtstatus in op Enqueued. Wanneer een apparaatthread gereed is voor het ontvangen van een bericht, vergrendelt de IoT-hub het bericht door de status in te stellen op Onzichtbaar. Met deze status kunnen andere threads op het apparaat andere berichten ontvangen. Wanneer een apparaatthread de verwerking van een bericht voltooit, wordt de IoT-hub op de hoogte gesteld door het bericht af te handelen. De IoT-hub stelt vervolgens de status in op Voltooid.

Een apparaat kan ook:

• Negeer het bericht, waardoor de IoT-hub deze instelt op de status Dead lettered . Er is geen dead-letter queue beschikbaar om deze berichten te herstellen. Apparaten die verbinding maken via het MQTT-protocol (Message Queuing Telemetry Transport) kunnen geen cloud-naar-apparaat-berichten weigeren.

• Laat het bericht af, waardoor de IoT-hub het bericht weer in de wachtrij plaatst, waarbij de status is ingesteld op Enqueued. Apparaten die verbinding maken via het MQTT-protocol kunnen geen cloud-naar-apparaat-berichten verlaten.

Een thread kan een bericht niet verwerken zonder de IoT-hub op de hoogte te stellen. In dit geval worden berichten automatisch van de onzichtbare status teruggezet naar de status Enqueued na een time-out voor zichtbaarheid (of time-out voor vergrendeling). De duur van deze time-out is één minuut en kan niet worden gewijzigd.

De eigenschap max delivery count op de IoT-hub bepaalt het maximum aantal keren dat een bericht kan worden overgezet tussen de status Enqueued en Onzichtbaar . Na dat aantal overgangen stelt de IoT-hub de status van het bericht in op Onbeletterd. Op dezelfde manier stelt de IoT-hub de status van een bericht in op Dead lettered na de verlooptijd.

Een apparaat voltooit gewoonlijk een cloud-naar-apparaat-bericht wanneer het verlies van het bericht geen invloed heeft op de toepassingslogica. Een voorbeeld van deze voltooiing kan zijn wanneer het apparaat de inhoud van het bericht lokaal persistent maakt of een bewerking heeft uitgevoerd. Het bericht kan ook tijdelijke informatie bevatten, waarvan het verlies geen invloed heeft op de functionaliteit van de toepassing. Soms kunt u voor langlopende taken het volgende doen:

• Voltooi het cloud-naar-apparaat-bericht nadat het apparaat de taakbeschrijving in de lokale opslag heeft behouden.

• Informeer de back-end van de oplossing met een of meer apparaat-naar-cloud-berichten in verschillende fasen van de voortgang van de taak.

Verlooptijd van bericht (levensduur)

Elk cloud-naar-apparaat-bericht heeft een verlooptijd. Met een van de volgende opties wordt de verlooptijd ingesteld:

• De eigenschap ExpiryTimeUtc in de service
• De IoT-hub, door de levensduur die als een IoT-hubeigenschap is gespecificeerd te gebruiken.

Voor meer informatie over het verlopen van berichten, zie Configuratieopties voor cloud-naar-apparaat.

Een veelvoorkomende manier om te profiteren van de vervaldatum van een bericht en om te voorkomen dat berichten worden verzonden naar niet-verbonden apparaten, is het instellen van korte waarden voor de levensduur. Met deze methode wordt hetzelfde resultaat bereikt als het onderhouden van de verbindingsstatus van het apparaat, maar dit is efficiënter. Wanneer u bevestigingen van berichten aanvraagt, ontvangt u van de IoT-hub een melding over welke apparaten:

• Kan berichten ontvangen.
• Zijn niet online of hebben gefaald.

Berichtfeedback

Wanneer u een cloud-naar-apparaat-bericht verzendt, kan de service de bezorging van feedback per bericht over de uiteindelijke status van dat bericht aanvragen. U kunt berichtfeedback configureren door de iothub-ack eigenschap van de toepassing in het cloud-naar-apparaat-bericht in te stellen op een van de volgende vier waarden:

Als de waarde van de eigenschap Ack is ingesteld op volledig en u geen feedbackbericht ontvangt, betekent dit dat het feedbackbericht is verlopen. De service kan niet weten wat er is gebeurd met het oorspronkelijke bericht. In de praktijk moet een service ervoor zorgen dat deze de feedback kan verwerken voordat deze verloopt. De maximale verlooptijd is twee dagen, waardoor de tijd overlaat om de service opnieuw uit te voeren als er een fout optreedt.

Zoals uitgelegd in IoT Hub-eindpunten, levert de IoT-hub feedback via een servicegericht eindpunt, /messages/servicebound/feedback, als berichten. De semantiek voor het ontvangen van feedback is hetzelfde als voor cloud-naar-apparaat-berichten. Waar mogelijk wordt berichtfeedback in één bericht gebatcheerd, met de volgende indeling:

Het systeem verzendt de feedback wanneer de batch 64 berichten bereikt, of in 15 seconden na de laatste verzending, afhankelijk van wat het eerst komt.

Het lichaam is een JSON-geserialiseerde reeks van records, elk met de volgende eigenschappen:

De service moet een MessageId opgeven, zodat het cloud-naar-apparaat-bericht de feedback kan correleren met het oorspronkelijke bericht.

De hoofdtekst van een feedbackbericht wordt weergegeven in het volgende codevoorbeeld:

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

Feedback wachtend op goedkeuring voor verwijderde apparaten

Wanneer een apparaat wordt verwijderd, wordt ook alle feedback die in behandeling is verwijderd. Apparaatfeedback wordt verzonden in batches. Een smal venster, vaak minder dan één seconde, kan optreden wanneer een apparaat de ontvangst van het bericht bevestigt en wanneer de volgende feedbackbatch wordt voorbereid. Als een apparaat in dat smalle venster wordt verwijderd, vindt de feedback niet plaats.

U kunt dit gedrag oplossen door te wachten totdat feedback in behandeling is voordat u uw apparaat verwijdert. Men moet ervan uitgaan dat gerelateerde berichtfeedback verloren gaat zodra een apparaat wordt verwijderd.

Configuratieopties van cloud naar apparaat

Elke IoT-hub bevat de volgende configuratieopties voor cloud-naar-apparaat-berichten:

U kunt de configuratieopties instellen in Azure Portal of Azure CLI:

• Azure Portal: selecteer onder Hub-instellingen op uw IoT-hub ingebouwde eindpunten en ga naar Cloud naar apparaatberichten. (Het instellen van de eigenschap feedback.maxDeliveryCount of feedback.lockDurationAsIso8601 wordt momenteel niet ondersteund in de Azure-portal.)

  

• Azure CLI: gebruik de opdracht 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
  

Volgende stappen

Zie Azure IoT Hub SDK's voor informatie over de SDK's die u kunt gebruiken om cloud-naar-apparaat-berichten te verwerken.

Zie Cloud-naar-apparaat-berichten verzenden en ontvangen voor hulp bij het ontwikkelen van toepassingen die cloud-naar-apparaat-berichten verwerken.