Informatie over 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 richtlijnen voor cloud-naar-apparaat voor een bespreking van andere cloud-naar-apparaatopties die worden ondersteund door Azure IoT Hub.
Notitie
De functies die in dit artikel worden beschreven, zijn alleen beschikbaar in de standaardlaag van de IoT Hub. Zie De juiste IoT Hub-laag voor uw oplossing kiezen voor meer informatie over de Basic- en Standard-/gratis IoT Hub-lagen.
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.
Als u elk cloud-naar-apparaat-bericht op één apparaat wilt richten, stelt uw IoT-hub de 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 door het bericht te voltooien. 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 wachtrij voor dode berichten voor het herstellen van deze berichten. 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 heeft behouden 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 (time to live)
Elk cloud-naar-apparaat-bericht heeft een verlooptijd. Deze keer wordt ingesteld door een van de volgende opties:
- De eigenschap ExpiryTimeUtc in de service
- De IoT-hub, met behulp van de standaardtijd voor live die is opgegeven als een IoT-hubeigenschap
Zie De configuratieopties voor cloud-naar-apparaat voor meer informatie over het verlopen van berichten.
Een veelvoorkomende manier om te profiteren van een verlooptijd van een bericht en om te voorkomen dat berichten worden verzonden naar niet-verbonden apparaten, is het instellen van korte tijd op live-waarden . Deze methode bereikt hetzelfde resultaat als het onderhouden van de verbindingsstatus van het apparaat, maar het is efficiënter. Wanneer u bevestigingen van berichten aanvraagt, ontvangt u van de IoT-hub een melding over de volgende apparaten:
- Kan berichten ontvangen.
- Zijn niet online of zijn mislukt.
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 eigenschap iothub-ack-toepassing in het cloud-naar-apparaat-bericht in te stellen dat naar een van de volgende vier waarden wordt verzonden:
| Waarde van Ack-eigenschap | Gedrag |
|---|---|
| Geen | Standaard. De IoT-hub genereert geen feedbackbericht. |
| positief | Als het cloud-naar-apparaat-bericht de status Voltooid bereikt, genereert de IoT-hub een feedbackbericht. |
| negatief | Als het cloud-naar-apparaat-bericht de status Dead lettered bereikt, genereert de IoT-hub een feedbackbericht. |
| volledig | De IoT-hub genereert in beide gevallen een feedbackbericht. |
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 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:
| Eigenschappen | Beschrijving |
|---|---|
| EnqueuedTime | Een tijdstempel die aangeeft wanneer het feedbackbericht is ontvangen door de hub. |
| Gebruikers-id | {iot hub name} |
| ContentType | application/vnd.microsoft.iothub.feedback.json |
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.
De hoofdtekst is een JSON-geserialiseerde matrix met records, elk met de volgende eigenschappen:
| Eigenschappen | Beschrijving |
|---|---|
| enqueuedTimeUtc | Een tijdstempel die aangeeft wanneer het resultaat van het bericht is opgetreden. Bijvoorbeeld een tijdstempel die aangeeft wanneer de hub het feedbackbericht heeft ontvangen of het oorspronkelijke bericht is verlopen. |
| originalMessageId | De MessageId van het cloud-naar-apparaat-bericht waarop deze feedbackinformatie betrekking heeft. |
| statuscode | Een vereiste tekenreeks die wordt gebruikt in feedbackberichten die worden gegenereerd door de IoT-hub: Succes Verlopen DeliveryCountExceeded Afgekeurd Verwijderd |
| beschrijving | Tekenreekswaarden voor StatusCode. |
| deviceId | De DeviceId van het doelapparaat van het cloud-naar-apparaat-bericht waarop dit deel van feedback betrekking heeft. |
| deviceGenerationId | De DeviceGenerationId van het doelapparaat van het cloud-naar-apparaat-bericht waarop dit deel van feedback betrekking heeft. |
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 in behandeling voor verwijderde apparaten
Wanneer een apparaat wordt verwijderd, worden alle feedback die in behandeling is ook 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. Gerelateerde berichtfeedback wordt ervan uitgegaan dat deze verloren gaan zodra een apparaat is verwijderd.
Configuratieopties voor cloud-naar-apparaat
Elke IoT-hub bevat de volgende configuratieopties voor cloud-naar-apparaat-berichten:
| Eigenschappen | Beschrijving | Bereik en standaard |
|---|---|---|
| defaultTtlAsIso8601 | Standaard-TTL voor cloud-naar-apparaat-berichten | ISO_8601 interval tot twee dagen (minimaal één minuut); standaard: één uur |
| maxDeliveryCount | Maximum aantal leveringen voor cloud-naar-apparaat-wachtrijen per apparaat | 1 tot 100; standaard: 10 |
| feedback.ttlAsIso8601 | Retentie voor servicegebonden feedbackberichten | ISO_8601 interval tot twee dagen (minimaal één minuut); standaard: één uur |
| feedback.maxDeliveryCount | Maximumaantal leveringen voor de feedbackwachtrij | 1 tot 100; standaard: 10 |
| feedback.lockDurationAsIso8601 | Vergrendelingsduur voor de feedbackwachtrij | ISO_8601 interval van 5 tot 300 seconden (minimaal vijf seconden); standaard: 60 seconden. |
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 eigenschappen feedback.maxDeliveryCount en feedback.lockDurationAsIso8601 wordt momenteel niet ondersteund in 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.