Delen via

Protocol voor statusarchief

  • Artikel

Het statusarchief is een gedistribueerd opslagsysteem binnen het Azure IoT Operations-cluster. De statusopslag biedt dezelfde garanties voor hoge beschikbaarheid als MQTT-berichten in MQTT-broker. Volgens de richtlijnen voor het MQTT5/RPC-protocol moeten clients MQTT5 gebruiken om te communiceren met het statusarchief. Dit artikel bevat protocolrichtlijnen voor ontwikkelaars die hun eigen state store-clients moeten implementeren.

Overzicht

De statusopslag ondersteunt de volgende opdrachten:

  • SET<keyName><keyValue><setOptions>
  • GET<keyName>
  • DEL<keyName>
  • VDEL<keyName><keyValue> ## Hiermee verwijdert u een opgegeven <keyName> als en alleen als de waarde keyValue is <>

Het protocol maakt gebruik van het volgende aanvraag-antwoordmodel:

  • Aanvraag. Clients publiceren een aanvraag naar een goed gedefinieerd systeemonderwerp over het statusarchief. Clients gebruiken de vereiste eigenschappen en nettolading die in de volgende secties worden beschreven om de aanvraag te publiceren.
  • Response. De statusopslag verwerkt de aanvraag asynchroon en reageert op het antwoordonderwerp dat de client aanvankelijk heeft opgegeven.

In het volgende diagram ziet u de basisweergave van de aanvraag en het antwoord:

Diagram van het basisaanvraag- en antwoordproces voor statusopslag.

Statusarchiefsysteemonderwerp, QoS en vereiste MQTT5-eigenschappen

Clients moeten voldoen aan de volgende vereisten om te communiceren met de statusopslag:

  • Gebruik MQTT5. Zie de MQTT 5-specificatie voor meer informatie.
  • QoS 1 (Quality of Service level 1) gebruiken. QoS 1 wordt beschreven in de MQTT 5-specificatie.
  • Een klok hebben die binnen één minuut na de klok van de MQTT-broker ligt.

Om te communiceren met de statusopslag, moeten PUBLISH clients aanvragen voor het systeemonderwerp statestore/v1/FA9AE35F-2F64-47CD-9BFF-08E2B32A0FE8/command/invoke. Omdat het statusarchief deel uitmaakt van Azure IoT-bewerkingen, wordt dit onderwerp impliciet SUBSCRIBE uitgevoerd bij het opstarten.

Als u een aanvraag wilt maken, zijn de volgende MQTT5-eigenschappen vereist. Als deze eigenschappen niet aanwezig zijn of als de aanvraag niet van het type QoS 1 is, mislukt de aanvraag.

  • Antwoordonderwerp. Het statusarchief reageert op de eerste aanvraag met behulp van deze waarde. Als best practice kunt u het antwoordonderwerp opmaken als clients/{clientId}/services/statestore/_any_/command/invoke/response. Het instellen van het antwoordonderwerp als statestore/v1/FA9AE35F-2F64-47CD-9BFF-08E2B32A0FE8/command/invoke of als een onderwerp waarmee wordt begonnen clients/statestore/v1/FA9AE35F-2F64-47CD-9BFF-08E2B32A0FE8 , is niet toegestaan op een statusarchiefaanvraag. De statusopslag verbreekt MQTT-clients die een ongeldig antwoordonderwerp gebruiken.
  • Correlatiegegevens. Wanneer het statusarchief een antwoord verzendt, bevat het de correlatiegegevens van de eerste aanvraag.

In het volgende diagram ziet u een uitgevouwen weergave van de aanvraag en het antwoord:

Diagram van uitgebreid aanvraag- en antwoordproces voor statusopslag.

Ondersteunde opdrachten

De opdrachten SET, GETen DEL gedragen zich zoals verwacht.

De waarden die door de SET opdracht worden ingesteld en de GET opdracht worden opgehaald, zijn willekeurige binaire gegevens. De grootte van de waarden wordt alleen beperkt door de maximale grootte van de MQTT-nettolading en resourcebeperkingen van MQTT-broker en de client.

SET Opties

De SET opdracht biedt meer optionele vlaggen dan de basis keyValue en keyName:

  • NX. Hiermee kan de sleutel alleen worden ingesteld als deze nog niet bestaat.
  • NEX <value>. Hiermee kan de sleutel alleen worden ingesteld als de sleutel niet bestaat of als de waarde van de sleutel al is ingesteld op <waarde>. De NEX vlag wordt doorgaans gebruikt voor een client die de vervaldatum (PX) op een sleutel verlengt.
  • PX. Hoe lang de sleutel moet blijven bestaan voordat deze verloopt, in milliseconden.

VDEL Opties

De VDEL opdracht is een speciaal geval van de DEL opdracht. DEL voorwaardelijke verwijdering van de opgegeven keyName. VDEL vereist een ander argument met de naam keyValue. VDEL verwijdert alleen de opgegeven keyName als deze hetzelfde keyValueheeft.

Payload-indeling

De payload-indeling van het statusarchief PUBLISH is geïnspireerd op RESP3. Dit is het onderliggende protocol dat Redis gebruikt. RESP3 codeert zowel het werkwoord, zoals SET of GET, als de parameters zoals keyName en keyValue.

Hoofdlettergevoelig

De client moet zowel de werkwoorden als de opties in hoofdletters verzenden.

Aanvraagindeling

Aanvragen worden opgemaakt zoals in het volgende voorbeeld. Na RESP3 vertegenwoordigt het * aantal items in een matrix. Het $ teken is het aantal tekens in de volgende regel, met uitzondering van het volgnummer CRLF.

De ondersteunde opdrachten in RESP3-indeling zijn GET, SETen DELVDEL.

*{NUMBER-OF-ARGUMENTS}<CR><LF>
${LENGTH-OF-NEXT-LINE}<CR><LF>
{COMMAND-NAME}<CR><LF>
${LENGTH-OF-NEXT-LINE}<CR><LF> // This is always the keyName with the current supported verbs.
{KEY-NAME}<CR><LF>
// Next lines included only if command has additional arguments
${LENGTH-OF-NEXT-LINE}<CR><LF> // This is always the keyValue for set
{KEY-VALUE}<CR><LF>

In de volgende voorbeelduitvoer ziet u resp3-nettoladingen van statusopslag:

*3<CR><LF>$3<CR><LF>set<CR><LF>$7<CR><LF>SETKEY2<CR><LF>$6<CR><LF>VALUE5<CR><LF>
*2<CR><LF>$3<CR><LF>get<CR><LF>$7<CR><LF>SETKEY2<CR><LF>
*2<CR><LF>$3<CR><LF>del<CR><LF>$7<CR><LF>SETKEY2<CR><LF>
*3<CR><LF>$4<CR><LF>vdel<CR><LF>$7<CR><LF>SETKEY2<CR><LF>$3<CR><LF>ABC<CR><LF>

Notitie

SET vereist aanvullende MQTT5-eigenschappen, zoals wordt uitgelegd in de sectie Versiebeheer en hybride logische klokken.

Antwoordindeling

Wanneer de statusopslag een ongeldige RESP3-nettolading detecteert, retourneert het nog steeds een reactie op de aanvrager Response Topic. Voorbeelden van ongeldige nettoladingen zijn een ongeldige opdracht, een ongeldige RESP3 of een overloop van gehele getallen. Een ongeldige nettolading begint met de tekenreeks -ERR en bevat meer details.

Notitie

Een GET, DELof VDEL aanvraag voor een niet-bestaande sleutel wordt niet beschouwd als een fout.

Als een client een ongeldige nettolading verzendt, verzendt het statusarchief een nettolading zoals in het volgende voorbeeld:

-ERR syntax error

SET antwoord

Wanneer een SET aanvraag slaagt, retourneert het statusarchief de volgende nettolading:

+OK<CR><LF>

Als een SET-aanvraag mislukt omdat een voorwaardecontrole zoals opgegeven in de NX- of NEX-opties die betekenen dat de sleutel niet kan worden ingesteld, retourneert het statusarchief de volgende nettolading:

-1<CR><LF>

GET antwoord

Wanneer een GET aanvraag wordt ingediend op een niet-bestaande sleutel, retourneert het statusarchief de volgende nettolading:

$-1<CR><LF>

Wanneer de sleutel wordt gevonden, retourneert het statusarchief de waarde in de volgende indeling:

${NumberOfBytes}<CR><LF>
{KEY-VALUE}

De uitvoer van het statusarchief dat de waarde 1234 retourneert, ziet er als volgt uit:

$4<CR><LF>1234<CR><LF>

DEL en VDEL antwoord

Het statusarchief retourneert het aantal waarden dat wordt verwijderd in een verwijderaanvraag. Op dit moment kan het statusarchief slechts één waarde tegelijk verwijderen.

:{NumberOfDeletes}<CR><LF> // Will be 1 on successful delete or 0 if the keyName is not present

De volgende uitvoer is een voorbeeld van een geslaagde DEL opdracht:

:1<CR><LF>

Als een VDEL-aanvraag mislukt omdat de opgegeven waarde niet overeenkomt met de waarde die is gekoppeld aan de sleutel, retourneert het statusarchief de volgende nettolading:

-1<CR><LF>

-ERR Reacties

Hier volgt de huidige lijst met fouttekenreeksen. Uw clienttoepassing moet onbekende foutreeksen verwerken ter ondersteuning van updates voor het statusarchief.

Fouttekenreeks die is geretourneerd uit het statusarchief Uitleg
de tijdstempel van de aanvraag is in de toekomst te ver; ervoor zorgen dat de klokken van het client- en brokersysteem worden gesynchroniseerd Onverwachte tijdstempel voor aanvragen die worden veroorzaakt door de statusopslag en clientklokken zijn niet gesynchroniseerd.
een fencing-token is vereist voor deze aanvraag Er treedt een fout op als een sleutel is gemarkeerd met een fencing-token, maar de client geeft het fencing-token niet op.
de tijdstempel van de aanvraagafschermingstoken is in de toekomst te ver; ervoor zorgen dat de klokken van het client- en brokersysteem worden gesynchroniseerd Onverwachte afschermingstokentijdstempel veroorzaakt door de statusopslag en clientklokken zijn niet gesynchroniseerd.
het token voor het afschermen van de aanvraag is een lagere versie die het fencingtoken beschermt tegen de resource Onjuiste versie van het token voor het afschermen van aanvragen. Zie [Versiebeheer en hybride logische klokken] voor meer informatie. (#versioning-en-hybrid-logical-clocks)
het quotum is overschreden Het statusarchief heeft een quotum voor het aantal sleutels dat kan worden opgeslagen. Dit is gebaseerd op het geheugenprofiel van de opgegeven MQTT-broker.
Syntaxisfout De verzonden nettolading voldoet niet aan de definitie van het statusarchief.
niet geautoriseerd Autorisatiefout
onbekende opdracht De opdracht wordt niet herkend.
onjuist aantal argumenten Onjuist aantal verwachte argumenten.
ontbrekende tijdstempel Wanneer clients een SET uitvoeren, moeten ze de MQTT5-gebruikerseigenschap instellen __ts als een HLC die de tijdstempel vertegenwoordigt.
onjuiste tijdstempel De tijdstempel in de __ts of het hekwerktoken is niet legaal.
de sleutellengte nul is Sleutels kunnen niet nul lengte hebben in het statusarchief.

Versiebeheer en hybride logische klokken

In deze sectie wordt beschreven hoe het statusarchief versiebeheer verwerkt.

Versies als hybride logische klokken

Het statusarchief onderhoudt een versie voor elke waarde die wordt opgeslagen. De statusopslag kan een monotonisch toenemend teller gebruiken om versies te onderhouden. In plaats daarvan gebruikt de statusopslag een HLC (Hybrid Logical Clock) om versies weer te geven. Zie de artikelen over het oorspronkelijke ontwerp van HLC's en de intentie achter HLC's voor meer informatie.

In het statusarchief wordt de volgende indeling gebruikt om HLC's te definiëren:

{wallClock}:{counter}:{node-Id}

Het wallClock is het aantal milliseconden sinds het Unix-epoch. counter en node-Id werken als HLC's in het algemeen.

Wanneer clients een SET, moeten ze de MQTT5-gebruikerseigenschap __ts instellen als een HLC die de tijdstempel vertegenwoordigt, op basis van de huidige klok van de client. Het statusarchief retourneert de versie van de waarde in het antwoordbericht. Het antwoord wordt ook opgegeven als een HLC en maakt ook gebruik van de __ts MQTT5-gebruikerseigenschap. De geretourneerde HLC is altijd groter dan de HLC van de eerste aanvraag.

Voorbeeld van het instellen en ophalen van de versie van een waarde

In deze sectie ziet u een voorbeeld van het instellen en ophalen van de versie voor een waarde.

Een clientset keyName=value. De klok van de client is 3 oktober 11:07:05 GMT. De klokwaarde is 1696374425000 milliseconden sinds unix-epoch. Stel dat de systeemklok van het staatsarchief identiek is aan de klok van het clientsysteem. De client voert de SET opdracht uit zoals eerder beschreven.

In het volgende diagram ziet u de SET opdracht:

Diagram van de opdracht State Store om de versie voor een waarde in te stellen.

De __ts eigenschap (tijdstempel) in de eerste set bevat 1696374425000 als de klok van de clientwand, de teller als 0en de knooppunt-id als CLIENT. In het antwoord bevat de __ts eigenschap die door het statusarchief wordt geretourneerd de wallClockteller verhoogd met één en de knooppunt-id als StateStore. De statusopslag kan een hogere wallClock waarde retourneren als de klok vooruit was, op basis van de manier waarop HLC-updates werken.

Deze versie wordt ook geretourneerd bij geslaagde GETaanvragen DELen VDEL aanvragen. Op deze aanvragen geeft de client geen __ts.

In het volgende diagram ziet u de GET opdracht:

Diagram van het statusarchief dat de versie van een waarde ophaalt.

Notitie

De tijdstempel die door het statusarchief wordt geretourneerd, is hetzelfde als de tijdstempel __ts die wordt geretourneerd in de eerste SET aanvraag.

Als een bepaalde sleutel later wordt bijgewerkt met een nieuwe SET, is het proces vergelijkbaar. De client moet de aanvraag __ts instellen op basis van de huidige klok. De statusopslag werkt de versie van de waarde bij en retourneert de __tsHLC-updateregels.

Tijdverschil

Het staatsarchief weigert een __ts (en ook een __ft) die meer dan een minuut voor de lokale klok van de staatswinkel ligt.

Het staatsarchief accepteert een __ts staat achter de lokale klok van het staatsarchief. Zoals opgegeven in het HLC-algoritme, stelt het statusarchief de versie van de sleutel in op de lokale klok omdat deze groter is.

Vergrendelings- en afschermingstokens

In deze sectie worden het doel en het gebruik van vergrendelings- en fencingtokens beschreven.

Achtergrond

Stel dat er twee of meer MQTT-clients zijn die de statusopslag gebruiken. Beide clients willen schrijven naar een bepaalde sleutel. Clients van het statusarchief hebben een mechanisme nodig om de sleutel te vergrendelen, zodat slechts één client tegelijk een bepaalde sleutel kan wijzigen.

Een voorbeeld van dit scenario vindt plaats in actieve en stand-bysystemen. Er kunnen twee clients zijn die dezelfde bewerking uitvoeren en de bewerking kan dezelfde set sleutel voor statusopslag bevatten. Op een bepaald moment is een van de clients actief en staat de andere ervoor om onmiddellijk over te nemen als het actieve systeem vastloopt of vastloopt. In het ideale geval moet slechts één client op een bepaald moment naar het statusarchief schrijven. In gedistribueerde systemen is het echter mogelijk dat beide clients zich kunnen gedragen alsof ze actief zijn en dat ze tegelijkertijd proberen naar dezelfde sleutels te schrijven. In dit scenario wordt een racevoorwaarde gemaakt.

Het statusarchief biedt mechanismen om deze racevoorwaarde te voorkomen door fencingtokens te gebruiken. Zie dit artikel voor meer informatie over fencing tokens en de klasse racevoorwaarden waar ze tegen zijn ontworpen.

Een fencing-token verkrijgen

In dit voorbeeld wordt ervan uitgegaan dat we de volgende elementen hebben:

  • Client1 en Client2. Deze clients zijn statusopslagclients die fungeren als een actief en stand-bypaar.
  • LockName. De naam van een sleutel in het statusarchief dat fungeert als de vergrendeling.
  • ProtectedKey. De sleutel die moet worden beschermd tegen meerdere schrijvers.

De clients proberen een vergrendeling te krijgen als eerste stap. Ze krijgen een slot door een SET LockName {CLIENT-NAME} NEX PX {TIMEOUT-IN-MILLISECONDS}. Zoals u weet uit Opties instellen, betekent de NEX vlag dat de SET vlag alleen slaagt als aan een van de volgende voorwaarden wordt voldaan:

  • De sleutel was leeg
  • De waarde van de sleutel is al ingesteld op <waarde> en PX geeft de time-out in milliseconden op.

Stel dat dat Client1 eerst gaat met een aanvraag van SET LockName Client1 NEX PX 10000. Deze aanvraag geeft het eigendom van LockName 10.000 milliseconden. Als Client2 een SET LockName Client2 NEX ... tijdje Client1 eigenaar is van de vergrendeling, betekent de vlag dat de NEX Client2 aanvraag mislukt. Client1 moet deze vergrendeling vernieuwen door dezelfde SET opdracht te verzenden die wordt gebruikt om de vergrendeling te verkrijgen, als Client1 u het eigendom wilt voortzetten.

Notitie

A SET NX is conceptueel gelijk aan AcquireLock().

De afschermingstokens gebruiken voor SET-aanvragen

Wanneer Client1 de SET statusopslag AquireLock is ingeschakeld LockName, retourneert de statusopslag de versie van LockName als een Hybrid Logical Clock (HLC) in de gebruikerseigenschap __tsMQTT5.

Wanneer een client een SET aanvraag uitvoert, kan deze eventueel de MQTT5-gebruikerseigenschap __ft opnemen om een 'fencing-token' weer te geven. De __ft wordt weergegeven als een HLC. Het fencing-token dat is gekoppeld aan een bepaald sleutel-waardepaar biedt controle van het eigendom van de vergrendeling. Het hekwerktoken kan overal vandaan komen. Voor dit scenario moet het afkomstig zijn van de versie van LockName.

In het volgende diagram ziet u het proces van het uitvoeren van Client1 een SET aanvraag op LockName:

Diagram van een client die een ingestelde aanvraag uitvoert voor de eigenschap Vergrendelingsnaam.

Client1 Vervolgens gebruikt u de __ts eigenschap (Property=1696374425000:1:StateStore) die niet is gewijzigd als de basis van de __ft eigenschap in de aanvraag om te wijzigenProtectedKey. Net als bij alle SET aanvragen moet de client de __ts eigenschap van ProtectedKey.

In het volgende diagram ziet u het proces van het uitvoeren van Client1 een SET aanvraag op ProtectedKey:

Diagram van de client die een ingestelde aanvraag uitvoert voor de eigenschap beveiligde sleutel.

Als de aanvraag slaagt, is vanaf dit punt ProtectedKey een afschermingstoken vereist dat gelijk is aan of groter is dan het token dat is opgegeven in de SET aanvraag.

Tokenalgoritmen voor fencing

Het staatsarchief accepteert een HLC voor het __ts sleutel-waardepaar, als de waarde binnen de maximale scheeftrekken van de klok valt. Hetzelfde geldt echter niet voor fencing tokens.

Het algoritme voor het statusarchief voor fencingtokens is als volgt:

  • Als aan een sleutel-waardepaar geen fencingtoken is gekoppeld en er een SET aanvraagset __ftaan is gekoppeld, slaat het statusarchief de gekoppelde __ft sleutel-waardepaar op.
  • Als er aan een sleutel-waardepaar een fencingtoken is gekoppeld:
    • Als een SET aanvraag niet is opgegeven __ft, negeert u de aanvraag.
    • Als een SET aanvraag een __ft met een oudere HLC-waarde heeft opgegeven dan het fencing-token dat is gekoppeld aan het sleutel-waardepaar, negeert u de aanvraag.
    • Als een SET aanvraag een waarde heeft opgegeven met een __ft gelijke of nieuwere HLC-waarde dan het fencing-token dat is gekoppeld aan het sleutel-waardepaar, accepteert u de aanvraag. In het statusarchief wordt het fencingtoken van het sleutel-waardepaar bijgewerkt naar het token dat is ingesteld in de aanvraag, als het nieuwer is.

Nadat een sleutel is gemarkeerd met een fencing-token, moet de eigenschap ook worden opgenomen voor een aanvraag om te slagen DEL . VDEL Voor aanvragen moet ook de __ft eigenschap worden opgenomen. Het algoritme is identiek aan de vorige, behalve dat het afschermingstoken niet is opgeslagen omdat de sleutel wordt verwijderd.

Clientgedrag

Deze vergrendelingsmechanismen zijn afhankelijk van clients die goed werken. In het vorige voorbeeld kon een onjuist gedrag Client2 niet de eigenaar zijn van de LockName en toch een SET ProtectedKey geslaagde uitvoering uitvoeren door een fencingtoken te kiezen dat nieuwer is dan het ProtectedKey token. Het statusarchief is niet op de hoogte van dat LockName en ProtectedKey hebben een relatie. Als gevolg hiervan voert de statusopslag geen validatie uit die Client2 daadwerkelijk eigenaar is van de waarde.

Clients die sleutels kunnen schrijven waarvoor ze niet daadwerkelijk eigenaar zijn van de vergrendeling, is ongewenst gedrag. U kunt bescherming bieden tegen dergelijke clientfouten door clients correct te implementeren en verificatie te gebruiken om de toegang tot sleutels tot vertrouwde clients alleen te beperken.

Meldingen

Clients kunnen zich registreren bij het statusarchief om meldingen te ontvangen van sleutels die worden gewijzigd. Houd rekening met het scenario waarin een thermostaat gebruikmaakt van de sleutel {thermostatName}\setPointvoor het staatsarchief. Andere statusopslagclients kunnen de waarde van deze sleutel wijzigen om het setPoint van de thermostaat te wijzigen. In plaats van te peilen naar wijzigingen, kan de thermostaat zich registreren bij het statusarchief om berichten te ontvangen wanneer {thermostatName}\setPoint deze wordt gewijzigd.

KEYNOTIFY-aanvraagberichten

Statusopslagclients vragen om een bepaalde keyName statusopslag te controleren op wijzigingen door een KEYNOTIFY bericht te verzenden. Net als alle aanvragen voor statusopslag publiceren clients een QoS1-bericht met dit bericht via MQTT5 naar het systeemonderwerp statestore/v1/FA9AE35F-2F64-47CD-9BFF-08E2B32A0FE8/command/invokevan het statusarchief.

De nettolading van de aanvraag heeft het volgende formulier:

KEYNOTIFY<CR><LF>
{keyName}<CR><LF>
{optionalFields}<CR><LF>

Hierin:

  • KEYNOTIFY is een letterlijke tekenreeks die de opdracht aangeeft.
  • {keyName} is de sleutelnaam voor het luisteren naar meldingen. Jokertekens worden momenteel niet ondersteund.
  • {optionalFields} De momenteel ondersteunde optionele veldwaarden zijn:
    • {STOP} Als er een bestaande melding is met hetzelfde keyName en clientId als deze aanvraag, wordt deze door het statusarchief verwijderd.

In de volgende voorbeelduitvoer ziet u een KEYNOTIFY aanvraag voor het bewaken van de sleutel SOMEKEY:

*2<CR><LF>
$9<CR><LF>
KEYNOTIFY<CR><LF>
$7<CR><LF>
SOMEKEY<CR><LF>

KEYNOTIFY-antwoordbericht

Net als bij alle RPC-aanvragen voor statusopslag retourneert het statusarchief de reactie op de Response Topic statusopslag en worden de Correlation Data eigenschappen gebruikt die zijn opgegeven vanuit de eerste aanvraag. Een KEYNOTIFYgeslaagd antwoord geeft aan dat het statusarchief de aanvraag heeft verwerkt. Nadat het statusarchief de aanvraag heeft verwerkt, controleert deze de sleutel voor de huidige client of stopt de bewaking.

Bij succes is het antwoord van het statusarchief hetzelfde als een geslaagde SET.

+OK<CR><LF>

Als een client een KEYNOTIFY SOMEKEY STOP aanvraag verzendt, maar de statusopslag die sleutel niet bewaakt, is het antwoord van het statusarchief hetzelfde als het verwijderen van een sleutel die niet bestaat.

:0<CR><LF>

Een andere fout volgt het algemene foutenrapportagepatroon van het statusarchief:

-ERR: <DESCRIPTION OF ERROR><CR><LF>

KEYNOTIFY-meldingsonderwerpen en levenscyclus

Wanneer een keyName bewaakt via KEYNOTIFY wordt gewijzigd of verwijderd, verzendt het statusarchief een melding naar de client. Het onderwerp wordt bepaald door de conventie: de client geeft het onderwerp niet op tijdens het KEYNOTIFY proces.

Het onderwerp is gedefinieerd in het volgende voorbeeld. Dit clientId is een hex hex gecodeerde weergave van de MQTT ClientId van de client die de KEYNOTIFY aanvraag heeft geïnitieerd en keyName een hex gecodeerde weergave is van de sleutel die is gewijzigd. Het statusarchief volgt de Base 16-coderingsregels van RFC 4648 - De Base16-, Base32- en Base64-gegevenscoderingen voor deze codering.

clients/statestore/v1/FA9AE35F-2F64-47CD-9BFF-08E2B32A0FE8/{clientId}/command/notify/{keyName}

Als voorbeeld publiceert MQTT-broker een NOTIFY bericht dat is verzonden client-id1 met de gewijzigde sleutelnaam SOMEKEY naar het onderwerp:

clients/statestore/v1/FA9AE35F-2F64-47CD-9BFF-08E2B32A0FE8/636C69656E742D696431/command/notify/534F4D454B4559`

Een client die meldingen gebruikt, moet SUBSCRIBE naar dit onderwerp gaan en wachten totdat de SUBACK ontvangen aanvragen worden verzonden KEYNOTIFY, zodat er geen berichten verloren gaan.

Als een client de verbinding verbreekt, moet deze opnieuw worden ingeschreven bij het KEYNOTIFY meldingsonderwerp en de KEYNOTIFY opdracht opnieuw verzenden voor sleutels die nodig zijn om de bewaking voort te zetten. In tegenstelling tot MQTT-abonnementen, die in een niet-schone sessie kunnen worden bewaard, worden berichten intern verwijderd KEYNOTIFY wanneer een bepaalde client de verbinding verbreekt.

NOTIFY-meldingsberichtindeling

Wanneer een sleutel die wordt bewaakt via KEYNOTIFY wordt gewijzigd, wordt PUBLISH in het statusarchief een bericht naar het meldingsonderwerp verzonden volgens de indeling voor de statusopslagclients die zijn geregistreerd voor de wijziging.

NOTIFY<CR><LF>
{operation}<CR><LF>
{optionalFields}<CR><LF>

De volgende details zijn opgenomen in het bericht:

  • NOTIFY is een letterlijke tekenreeks die is opgenomen als het eerste argument in de nettolading, waarmee wordt aangegeven dat er een melding is ontvangen.
  • {operation} is de gebeurtenis die is opgetreden. Momenteel zijn dit de volgende bewerkingen:
    • SET de waarde is gewijzigd. Deze bewerking kan alleen optreden als gevolg van een SET opdracht van een statusarchiefclient.
    • DEL de waarde is verwijderd. Deze bewerking kan optreden vanwege een DEL of VDEL opdracht van een statusarchiefclient.
  • optionalFields
    • VALUE en {MODIFIED-VALUE}. VALUE is een letterlijke tekenreeks die aangeeft dat het volgende veld {MODIFIED-VALUE}, de waarde bevat waarnaar de sleutel is gewijzigd. Deze waarde wordt alleen verzonden als reactie op sleutels die worden gewijzigd vanwege een SET.

In de volgende voorbeelduitvoer ziet u een meldingsbericht dat wordt verzonden wanneer de sleutel SOMEKEY wordt gewijzigd in de waarde abc, met de VALUE opgenomen waarde omdat de eerste aanvraag de GET optie heeft opgegeven:

*4<CR><LF>
$6<CR><LF>
NOTIFY<CR><LF>
$3<CR><LF>
SET<CR><LF>
$5<CR><LF>
VALUE<CR><LF>
$3<CR><LF>
abc<CR><LF>

Het KEYNOTIFY meldingsbericht bevat de tijdstempel van de waarde bij het melden van een client over een SET-aanvraag (waarde bijgewerkt) of bij het melden van een client over een DEL- of VDEL-aanvraag (waarde verwijderd). De tijdstempel wordt opgenomen als onderdeel van de MQTT v5-gebruikerseigenschap van het bericht __ts. Zie de sectie Versies als hybride logische klokken voor meer informatie.

Gerelateerde inhoud