Cloud-naar-apparaat-berichten verzenden vanuit een IoT-hub
Als u meldingen in één richting naar een apparaat-app wilt verzenden vanuit de back-end van uw oplossing, verzendt u cloud-naar-apparaat-berichten van uw IoT-hub naar uw apparaat. Zie Richtlijnen voor cloud-naar-apparaatcommunicatie voor een bespreking van andere cloud-naar-apparaat-opties die door Azure IoT Hub worden ondersteund.
Notitie
De functies die in dit artikel worden beschreven, zijn alleen beschikbaar in de standaardlaag van de IoT Hub. Zie Choose the right IoT Hub tier for your solution (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 de berichten vervolgens 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 to 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.
De levenscyclus van cloud-naar-apparaat-berichten
Uw IoT-hub bewaart cloud-naar-apparaat-berichten in wachtrijen per apparaat om de levering van ten minste één bericht te garanderen. Apparaten moeten expliciet bevestigen dat een bericht is voltooid voordat de IoT-hub het bericht uit de wachtrij verwijdert. Deze benadering garandeert tolerantie tegen connectiviteits- en apparaatfouten.
De grafiek met de levenscyclusstatus 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 apparaat een bericht wil ontvangen , 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 gewaarschuwd door het bericht te voltooien . De IoT-hub stelt vervolgens de status in op Voltooid.
Een apparaat kan ook:
Weiger het bericht, waardoor de IoT-hub het instelt op de status Dead lettered . Apparaten die verbinding maken via het MQTT-protocol (Message Queuing Telemetry Transport), kunnen cloud-naar-apparaat-berichten niet weigeren.
Verlaat het bericht, waardoor de IoT-hub het bericht weer in de wachtrij plaatst, met de status ingesteld op Enqueued. Apparaten die verbinding maken via het MQTT-protocol, kunnen cloud-naar-apparaat-berichten niet verlaten.
Een thread kan een bericht niet verwerken zonder de IoT-hub op de hoogte te stellen. In dit geval gaan berichten automatisch over van de status Onzichtbare naar de status Enqueued na een zichtbaarheidstime-out (of vergrendelingstime-out). De waarde 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 Onzichtbare . Na dat aantal overgangen stelt de IoT-hub de status van het bericht in op Onbestelbaar. Op dezelfde manier stelt de IoT-hub de status van een bericht in op Dead lettered na de verlooptijd. Zie Berichtverloop (time to live) voor meer informatie.
In het artikel Cloud-naar-apparaat-berichten verzenden met IoT Hub wordt beschreven hoe u cloud-naar-apparaat-berichten verzendt vanuit de cloud en deze ontvangt op een apparaat.
Een apparaat voltooit normaal gesproken 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 berichtinhoud 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:
Vul het cloud-naar-apparaat-bericht in 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.
Bericht verloopt (time to live)
Elk cloud-naar-apparaat-bericht heeft een verlooptijd. Deze tijd wordt ingesteld door een van de volgende opties:
- De eigenschap ExpiryTimeUtc in de service
- De IoT-hub, met behulp van de standaard time to live die is opgegeven als een IoT-hub-eigenschap
Zie Configuratieopties voor cloud-naar-apparaat voor meer informatie over het verlopen van berichten.
Een veelgebruikte manier om te profiteren van het verlopen van een bericht en om te voorkomen dat berichten worden verzonden naar niet-verbonden apparaten, is door korte time-to-live-waarden in te stellen. Met deze aanpak wordt hetzelfde resultaat bereikt als het handhaven van de verbindingsstatus van het apparaat, maar het is efficiënter. Wanneer u bevestigingen van berichten aanvraagt, meldt de IoT-hub u welke apparaten het volgende zijn:
- Kan berichten ontvangen.
- Zijn niet online of zijn mislukt.
Feedback van berichten
Wanneer u een cloud-naar-apparaat-bericht verzendt, kan de service vragen om feedback per bericht over de uiteindelijke status van dat bericht. U kunt feedback van berichten configureren door de toepassingseigenschap iothub-ack in het cloud-naar-apparaat-bericht dat wordt verzonden in te stellen op een van de volgende vier waarden:
| Ack-eigenschapswaarde | 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 Onbestelbaar bereikt, genereert de IoT-hub een feedbackbericht. |
| Volledige | De IoT-hub genereert in beide gevallen een feedbackbericht. |
Als de waarde van de eigenschap Ack is ingesteld op vol 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, wat tijd overlaat om de service weer 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. Indien mogelijk wordt de feedback van berichten in een batch in één bericht verwerkt, met de volgende indeling:
| Eigenschap | Beschrijving |
|---|---|
| EnqueuedTime | Een tijdstempel die aangeeft wanneer het feedbackbericht is ontvangen door de hub. |
| UserId | {iot hub name} |
| Contenttype | application/vnd.microsoft.iothub.feedback.json |
Het systeem verzendt de feedback wanneer de batch 64 berichten bereikt of binnen 15 seconden na de laatste verzending, afhankelijk van wat zich het eerst voordoet.
De hoofdtekst is een JSON-geserialiseerde matrix van records, elk met de volgende eigenschappen:
| Eigenschap | 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 feedback-informatie betrekking heeft. |
| statuscode | Een vereiste tekenreeks die wordt gebruikt in feedbackberichten die worden gegenereerd door de IoT-hub: Geslaagd Verlopen DeliveryCountExceeded Afgewezen Verwijderd |
| beschrijving | Tekenreekswaarden voor StatusCode. |
| deviceId | De DeviceId van het doelapparaat van het cloud-naar-apparaat-bericht waarop dit feedbackbericht betrekking heeft. |
| deviceGenerationId | De DeviceGenerationId van het doelapparaat van het cloud-naar-apparaat-bericht waarop dit feedbackbericht 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, wordt alle in behandeling zijnde feedback ook verwijderd. Feedback over apparaten wordt in batches verzonden. Een smal venster, vaak minder dan één seconde, kan optreden tussen het moment waarop een apparaat de ontvangst van het bericht bevestigt en het moment waarop de volgende feedbackbatch wordt voorbereid. Als een apparaat in dat smalle venster wordt verwijderd, treedt de feedback niet op.
U kunt dit gedrag aanpakken door een bepaalde periode te wachten totdat er feedback in behandeling is voordat u uw apparaat verwijdert. Feedback over gerelateerde berichten moet verloren gaan zodra een apparaat is verwijderd.
Configuratieopties voor cloud-naar-apparaat
Elke IoT-hub biedt de volgende configuratieopties voor cloud-naar-apparaat-berichten:
| Eigenschap | Beschrijving | Bereik en standaard |
|---|---|---|
| defaultTtlAsIso8601 | Standaard-TTL voor cloud-naar-apparaat-berichten | ISO_8601 interval van maximaal twee dagen (minimaal één minuut); standaardinstelling: één uur |
| maxDeliveryCount | Maximum aantal leveringen voor cloud-naar-apparaat wachtrijen per apparaat | 1 tot 100; standaardinstelling: 10 |
| feedback.ttlAsIso8601 | Retentie voor servicegebonden feedbackberichten | ISO_8601 interval van maximaal twee dagen (minimaal één minuut); standaardinstelling: één uur |
| feedback.maxDeliveryCount | Maximum aantal leveringen voor de feedbackwachtrij | 1 tot 100; standaardinstelling: 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 op een van de volgende manieren instellen:
- Azure Portal: selecteer onder Hub-instellingen op uw IoT-hub de optie 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 SDK's Azure IoT Hub voor informatie over de SDK's die u kunt gebruiken om cloud-naar-apparaat-berichten te ontvangen.
Als u het ontvangen van cloud-naar-apparaat-berichten wilt proberen, raadpleegt u de zelfstudie Cloud-naar-apparaat verzenden .