Protocollo dell'archivio stati del broker MQTT

L'archivio stati MQ è un sistema di archiviazione distribuito all'interno del cluster Operazioni IoT di Azure. L'archivio stati offre le stesse garanzie di disponibilità elevata dei messaggi MQTT nel broker MQTT. In base alle linee guida del protocollo MQTT5/RPC, i client devono usare MQTT5 per interagire con l'archivio stati MQ. Questo articolo fornisce indicazioni sul protocollo per gli sviluppatori che devono implementare i client dell'archivio stati del broker MQTT.

Panoramica del protocollo dell'archivio stati

L'archivio stati MQ supporta i comandi seguenti:

• SET<keyName><keyValue><setOptions>
• GET<keyName>
• DEL<keyName>
• VDEL<keyName><keyValue> ## Elimina un determinato <keyName> se e solo se il suo valore è <keyValue>

Il protocollo usa il modello richiesta-risposta seguente:

• Richiedi. I client pubblicano una richiesta in un argomento di sistema dell'archivio stati ben definito. Per pubblicare la richiesta, i client usano le proprietà e il payload necessari descritti nelle sezioni seguenti.
• Response. L'archivio stati elabora in modo asincrono la richiesta e risponde all'argomento di risposta fornito inizialmente dal client.

Il diagramma seguente illustra la visualizzazione di base della richiesta e della risposta:

Argomento del sistema di archiviazione stati, QoS e proprietà MQTT5 necessarie

Per comunicare con l'archivio stati, i client devono soddisfare i requisiti seguenti:

• Usare MQTT5. Per altre informazioni, vedere la specifica MQTT 5.
• Usare QoS 1 (qualità del livello di servizio 1). QoS 1 è descritto nella specifica MQTT 5.
• Avere un orologio che si trova entro un minuto dall'orologio del broker MQTT.

Per comunicare con l'archivio stati, i client devono PUBLISH richiedere all'argomento di sistemastatestore/v1/FA9AE35F-2F64-47CD-9BFF-08E2B32A0FE8/command/invoke. Poiché l'archivio stati fa parte di Operazioni IoT di Azure, viene eseguito un SUBSCRIBE implicito in questo argomento all'avvio.

Per compilare una richiesta, sono necessarie le proprietà MQTT5 seguenti. Se queste proprietà non sono presenti o la richiesta non è di tipo QoS 1, la richiesta ha esito negativo.

• Argomento risposta. L'archivio stati risponde alla richiesta iniziale usando questo valore. Come procedura consigliata, formattare l'argomento della risposta come clients/{clientId}/services/statestore/_any_/command/invoke/response. L'impostazione dell'argomento di risposta come statestore/v1/FA9AE35F-2F64-47CD-9BFF-08E2B32A0FE8/command/invoke o come una che inizia con clients/statestore/v1/FA9AE35F-2F64-47CD-9BFF-08E2B32A0FE8 non è consentita in una richiesta dell'archivio stati. L'archivio stati disconnette i client MQTT che usano un argomento di risposta non valido.
• Dati di correlazione. Quando l'archivio stati invia una risposta, include i dati di correlazione della richiesta iniziale.

Il diagramma seguente mostra una visualizzazione espansa della richiesta e della risposta:

Comandi supportati

I comandi SET, GET e DEL si comportano come previsto.

I valori impostati dal comando SET e recuperati dal comando GET sono dati binari arbitrari. Le dimensioni dei valori sono limitate solo dalle dimensioni massime del payload MQTT e dalle limitazioni delle risorse di MQ e del client.

Opzioni SET

Il comando SET fornisce altri flag facoltativi oltre al keyValue e keyName di base:

• NX. Consente di impostare la chiave solo se non esiste già.
• NEX <value>. Consente di impostare la chiave solo se la chiave non esiste o se il valore della chiave è già impostato su <value>. Il flag NEX viene in genere usato per un client che rinnova la scadenza (PX) su una chiave.
• PX. Per quanto tempo la chiave deve rimanere persistente prima della scadenza, espressa in millisecondi.

Opzioni VDEL

Il comando VDEL è un caso speciale del comando DEL. DEL elimina in modo incondizionato il keyName specificato. VDEL richiede un altro argomento denominato keyValue. VDEL elimina solo il keyName specificato se ha lo stesso keyValue.

Formato di payload

Il formato del payload PUBLISH dell'archivio stati è ispirato a RESP3, che è il protocollo sottostante usato daRedis. RESP3 codifica sia il verbo, ad esempio SET o GET, sia i parametri come keyName e keyValue.

Distinzione tra maiuscole e minuscole

Il client deve inviare sia i verbi che le opzioni in lettere maiuscole.

Formato della richiesta

Le richieste vengono formattate come nell'esempio seguente. Dopo RESP3, * rappresenta il numero di elementi un array. Il carattere $ è il numero di caratteri nella riga seguente, escluso il CRLF finale.

I comandi supportati in formato RESP3 sono GET, SET, DEL e VDEL.

*{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>

L'output di esempio seguente mostra i payload RESP3 dell'archivio stati:

*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>

Formato della risposta

Quando l'archivio stati rileva un payload RESP3 non valido, restituisce comunque una risposta a Response Topic del richiedente. Esempi di payload non validi includono un comando non valido, un overflow RESP3 non valido o integer. Un payload non valido inizia con la stringa -ERR e contiene altri dettagli.

Se un client invia un payload non valido, l'archivio stati invia un payload simile all'esempio seguente:

-ERR syntax error

SET risposta

Quando una richiesta di SET ha esito positivo, l'archivio stati restituisce il payload seguente:

+OK<CR><LF>

Se una richiesta SET ha esito negativo perché un controllo della condizione specificato nelle opzioni del set NX o NEX indica che la chiave non può essere impostata, l'archivio stati restituisce il payload seguente:

-1<CR><LF>

GET risposta

Quando viene effettuata una richiesta GET su una chiave inesistente, l'archivio stati restituisce il payload seguente:

$-1<CR><LF>

Quando viene trovata la chiave, l'archivio stati restituisce il valore nel formato seguente:

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

L'output dell'archivio stati che restituisce il valore 1234 è simile all'esempio seguente:

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

Risposta DEL e VDEL

L'archivio stati restituisce il numero di valori eliminati in una richiesta di eliminazione. Attualmente, l'archivio stati può eliminare un solo valore alla volta.

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

L'output seguente è un esempio di comando riuscito DEL:

:1<CR><LF>

Se una richiesta VDEL non riesce perché il valore specificato non corrisponde al valore associato alla chiave, l'archivio stati restituisce il payload seguente:

-1<CR><LF>

-ERR Risposte

Di seguito è riportato l'elenco corrente di stringhe di errore. L'applicazione client deve gestire stringhe di errore sconosciute per supportare gli aggiornamenti dell'archivio stati.

Stringa di errore restituita dall'archivio stati	Spiegazione
il timestamp della richiesta è troppo lontano in futuro; assicurarsi che gli orologi del sistema client e broker siano sincronizzati	Timestamp imprevisto della richiesta causato dall'archivio stati e gli orologi client non sono sincronizzati.
per questa richiesta è necessario un token di isolamento	L'errore si verifica se una chiave è contrassegnata con un token di isolamento, ma il client non specifica il token di isolamento.
il timestamp del token di isolamento della richiesta è troppo lontano in futuro; assicurarsi che gli orologi del sistema client e broker siano sincronizzati	Timestamp imprevisto del token di isolamento causato dall'archivio stati e gli orologi client non sono sincronizzati.
il token di isolamento della richiesta è una versione precedente che il token di isolamento protegge la risorsa	Versione del token di isolamento della richiesta non corretta. Per altre informazioni, vedere [Controllo delle versioni e clock logici ibridi]. (#versioning-and-hybrid-logical-clocks)
la quota è stata superata	L'archivio stati ha una quota del numero di chiavi che può archiviare, che si basa sul profilo di memoria del broker MQTT specificato.
errore di sintassi	Il payload inviato non è conforme alla definizione dell'archivio stati.
non autorizzato	Errore di autorizzazione
comando sconosciuto	Il comando non viene riconosciuto.
numero errato di argomenti	Numero errato di argomenti previsti.
timestamp mancante	Quando i client eseguono un SET, devono impostare la proprietà utente MQTT5 __ts come HLC che rappresenta il timestamp.
timestamp non valido	Il timestamp nel __ts o il token di isolamento non è valido.
la lunghezza della chiave è zero	Le chiavi non possono essere di lunghezza zero nell'archivio stati.

Controllo delle versioni e clock logici ibridi

Questa sezione descrive come l'archivio stati gestisce il controllo delle versioni.

Versioni come orologi logici ibridi

L'archivio stati mantiene una versione per ogni valore archiviato. L'archivio stati potrebbe usare un contatore che aumenta in modo monotonico per gestire le versioni. L'archivio stati usa invece un Clock logico ibrido (HLC) per rappresentare le versioni. Per altre informazioni, vedere gli articoli sulla progettazione originale di HLC e la finalità alla base di HLC.

L'archivio stati usa il formato seguente per definire i HLC:

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

wallClock è il numero di millisecondi dall'epoca Unix. counter e node-Id funzionano come HLC in generale.

Quando i client eseguono un SET, devono impostare la proprietà utente MQTT5 __ts come HLC che rappresenta il timestamp, in base all'orologio corrente del client. L'archivio stati restituisce la versione del valore nel messaggio di risposta. La risposta viene specificata anche come HLC e usa anche la proprietà utente MQTT5 __ts. L'HLC restituito è sempre maggiore dell'HLC della richiesta iniziale.

Esempio di impostazione e recupero della versione di un valore

Questa sezione illustra un esempio di impostazione e recupero della versione per un valore.

Un client imposta keyName=value. L'orologio del client è il 3 ottobre, 11:07:05PM GMT. Il valore dell'orologio è 1696374425000 millisecondi dall'epoca Unix. Si supponga che l'orologio di sistema dell'archivio stati sia identico all'orologio del sistema client. Il client esegue il comando SET come descritto in precedenza.

Il diagramma seguente illustra il comando SET:

La proprietà __ts (timestamp) nel set iniziale contiene 1696374425000 come clock del client, il contatore come 0 e il relativo ID nodo come CLIENT. Nella risposta, la proprietà __ts restituita dall'archivio stati contiene il wallClock, il contatore incrementato di uno e l'ID nodo come StateStore. L'archivio stati potrebbe restituire un valore wallClock superiore se il clock fosse in anticipo, in base al funzionamento degli aggiornamenti HLC.

Questa versione viene restituita anche in caso di richieste GET, DEL, e VDEL con esito positivo. In queste richieste, il client non specifica un __ts.

Il diagramma seguente illustra il comando GET:

Se una determinata chiave viene aggiornata in un secondo momento con un nuovo SET, il processo è simile. Il client deve impostare la richiesta __ts in base al clock corrente. L'archivio stati aggiorna la versione del valore e restituisce __ts, seguendo le regole di aggiornamento HLC.

Asimmetria dell'orologio

L'archivio stati rifiuta un __ts (e anche un __ft) superiore a un minuto prima dell'orologio locale dell'archivio stati.

L'archivio stati accetta un __ts che si trova dietro l'orologio locale dell'archivio stati. Come specificato nell'algoritmo HLC, l'archivio stati imposta la versione della chiave sul clock locale perché è maggiore.

Token di blocco e isolamento

Questa sezione descrive lo scopo e l'utilizzo dei token di blocco e isolamento.

Background

Si supponga che siano presenti due o più client MQTT che usano l'archivio stati. Entrambi i client vogliono scrivere in una determinata chiave. I client dell'archivio stati necessitano di un meccanismo per bloccare la chiave in modo che un solo client alla volta possa modificare una determinata chiave.

Un esempio di questo scenario si verifica nei sistemi attivi e di standby. Potrebbero essere presenti due client che eseguono entrambe la stessa operazione e che l'operazione potrebbe includere lo stesso set di chiavi dell'archivio stati. In un determinato momento, uno dei client è attivo e l'altro è in piedi per assumere immediatamente il controllo se il sistema attivo si blocca o si arresta in modo anomalo. Idealmente, solo un client deve scrivere nell'archivio stati in un determinato momento. Tuttavia, nei sistemi distribuiti è possibile che entrambi i client si comportino come se fossero attivi e potrebbero provare contemporaneamente a scrivere nelle stesse chiavi. Questo scenario crea una race condition.

L'archivio stati fornisce meccanismi per evitare questa race condition usando token di isolamento. Per altre informazioni sui token di isolamento e sulla classe delle race condition progettate per proteggersi, vedere questo articolo.

Ottenere un token di isolamento

In questo esempio si presuppone che siano presenti gli elementi seguenti:

• Client1 e Client2. Questi client sono client dell'archivio stati che fungono da coppia attiva e standby.
• LockName. Nome di una chiave nell'archivio stati che funge da blocco.
• ProtectedKey. Chiave che deve essere protetta da più writer.

I client tentano di ottenere un blocco come primo passaggio. Ottengono un blocco eseguendo un SET LockName {CLIENT-NAME} NEX PX {TIMEOUT-IN-MILLISECONDS}. Richiamare da Set Options che il flag NEX indica che SET ha esito positivo solo se viene soddisfatta una delle condizioni seguenti:

• La chiave era vuota
• Il valore della chiave è già impostato su <value> e PX specifica il timeout in millisecondi.

Si supponga che Client1 vada prima con una richiesta di SET LockName Client1 NEX PX 10000. Questa richiesta concede la proprietà di LockName per 10.000 millisecondi. Se Client2 tenta un SET LockName Client2 NEX ... mentre Client1 è proprietario del blocco, il flag NEX indica che la richiesta di Client2 ha esito negativo. Client1 deve rinnovare questo blocco inviando lo stesso comando SET usato per acquisire il blocco, se Client1 vuole continuare la proprietà.

Usare i token di isolamento nelle richieste SET

Quando Client1 esegue correttamente un SET ("AquireLock") in LockName, l'archivio stati restituisce la versione di LockName come Clock logico ibrido (HLC) nella proprietà utente MQTT5 __ts.

Quando un client esegue una richiesta SET, può includere facoltativamente la proprietà utente MQTT5 __ft per rappresentare un "token di isolamento". __ft è rappresentato come HLC. Il token di isolamento associato a una determinata coppia chiave-valore fornisce il controllo della proprietà dei blocchi. Il token di isolamento può provenire da qualsiasi punto. Per questo scenario, deve provenire dalla versione di LockName.

Il diagramma seguente illustra il processo di Client1 che esegue una richiesta SET in LockName:

Successivamente, Client1 usa la proprietà __ts (Property=1696374425000:1:StateStore) non modificata come base della proprietà __ft nella richiesta di modificare ProtectedKey. Analogamente a tutte le richieste SET, il client deve impostare la proprietà __ts di ProtectedKey.

Il diagramma seguente illustra il processo di Client1 che esegue una richiesta SET in ProtectedKey:

Se la richiesta ha esito positivo, da questo punto in poi ProtectedKey richiede un token di isolamento uguale o maggiore di quello specificato nella richiesta SET.

Algoritmo token di isolamento

L'archivio stati accetta qualsiasi HLC per __ts di una coppia chiave-valore, se il valore si trova all'interno dell'asimmetria massima dell'orologio. Tuttavia, lo stesso non è vero per i token di isolamento.

L'algoritmo di archiviazione degli stati per i token di isolamento è il seguente:

• Se a una coppia chiave-valore non è associato un token di isolamento e una richiesta SET imposta __ft, l'archivio stati archivia il __ft associato alla coppia chiave-valore.
• Se a una coppia chiave-valore è associato un token di isolamento:
  • Se una richiesta SET non ha specificato __ft, rifiutare la richiesta.
  • Se una richiesta SET ha specificato un __ft con un valore HLC precedente rispetto al token di isolamento associato alla coppia chiave-valore, rifiutare la richiesta.
  • Se una richiesta SET ha specificato un __ft che contiene un valore HLC pari o più recente rispetto al token di isolamento associato alla coppia chiave-valore, accettare la richiesta. L'archivio stati aggiorna il token di isolamento della coppia chiave-valore in modo che sia quello impostato nella richiesta, se è più recente.

Dopo che una chiave è contrassegnata con un token di isolamento, affinché una richiesta abbia esito positivo, anche le richieste DEL e VDEL necessitano dell'inserimento della proprietà __ft. L'algoritmo è identico a quello precedente, ad eccezione del fatto che il token di isolamento non è archiviato perché la chiave viene eliminata.

Comportamento del client

Questi meccanismi di blocco si basano sul comportamento corretto dei client. Nell'esempio precedente, un comportamento errato Client2 non è riuscito a possedere il LockName ed eseguire comunque correttamente un SET ProtectedKey scegliendo un token di isolamento più recente del token ProtectedKey. L'archivio stati non è consapevole che LockName e ProtectedKey hanno alcuna relazione. Di conseguenza, l'archivio stati non esegue la convalida che Client2 possiede effettivamente il valore.

I client possono scrivere chiavi per le quali non sono effettivamente proprietari del blocco, è un comportamento indesiderato. È possibile proteggersi da tali comportamenti non corretti del client implementando correttamente i client e usando l'autenticazione per limitare l'accesso alle chiavi solo ai client attendibili.

Notifications

I client possono registrarsi con l'archivio stati per ricevere notifiche di modifica delle chiavi. Si consideri lo scenario in cui un termostato usa la chiave dell'archivio stati {thermostatName}\setPoint. Altri client dell'archivio stati possono modificare il valore di questa chiave per modificare il setPoint del termostato. Invece di eseguire il polling delle modifiche, il termostato può registrarsi con l'archivio stati per ricevere messaggi quando {thermostatName}\setPoint viene modificato.

MESSAGGI di richiesta KEYNOTIFY

I client dell'archivio stati richiedono che l'archivio stati monitori un dato keyName in merito alle modifiche inviando un messaggio KEYNOTIFY. Analogamente a tutte le richieste dell'archivio stati, i client PUBBLICANO un messaggio QoS1 con questo messaggio tramite MQTT5 nell'argomento del sistema dell'archivio stati statestore/v1/FA9AE35F-2F64-47CD-9BFF-08E2B32A0FE8/command/invoke.

Il payload della richiesta ha il formato seguente:

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

Dove:

• KEYNOTIFY è un valore letterale stringa che specifica il comando.
• {keyName} è il nome della chiave in cui restare in ascolto delle notifiche. I caratteri jolly non sono attualmente supportati.
• {optionalFields} I valori dei campi facoltativi attualmente supportati sono:
  • {STOP} Se è presente una notifica esistente con gli stessi keyName e clientId come questa richiesta, l'archivio stati lo rimuove.

L'output di esempio seguente mostra una richiesta KEYNOTIFY per monitorare la chiave SOMEKEY:

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

MESSAGGIO di risposta KEYNOTIFY

Analogamente a tutte le richieste RPC dell'archivio stati, l'archivio stati restituisce la risposta al Response Topic e usa le proprietà Correlation Data specificate dalla richiesta iniziale. Per KEYNOTIFY, una risposta con esito positivo indica che l'archivio stati ha elaborato la richiesta. Dopo che l'archivio stati elabora correttamente la richiesta, monitora la chiave per il client corrente o arresta il monitoraggio.

In caso di esito positivo, la risposta dell'archivio stati equivale a un esito positivo SET.

+OK<CR><LF>

Se un client invia una richiesta KEYNOTIFY SOMEKEY STOP ma l'archivio stati non monitora tale chiave, la risposta dell'archivio stati equivale al tentativo di eliminare una chiave che non esiste.

:0<CR><LF>

Qualsiasi altro errore segue il criterio generale di segnalazione degli errori dell'archivio stati:

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

ARGOMENTI e ciclo di vita delle notifiche KEYNOTIFY

Quando un keyName monitorato tramite KEYNOTIFY viene modificato o eliminato, l'archivio stati invia una notifica al client. L'argomento è determinato per convenzione: il client non specifica l'argomento durante il processo KEYNOTIFY.

L'argomento è definito nell'esempio seguente. Il clientId è una rappresentazione con codifica esadecimale maiuscola del ClientId MQTT del client che ha avviato la richiesta KEYNOTIFY e keyName è una rappresentazione con codifica esadecimale della chiave modificata. L'archivio stati segue le regole di codifica Base 16 di RFC 4648 - Le codifiche dei dati Base16, Base32 e Base64 per questa codifica.

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

Ad esempio, MQ pubblica un messaggio NOTIFY inviato a client-id1 con il nome della chiave modificato SOMEKEY all'argomento:

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

Un client che usa le notifiche deve SUBSCRIBE essere inviato a questo argomento e attendere che il SUBACK venga ricevuto prima di inviare richieste KEYNOTIFY in modo che non vengano persi messaggi.

Se un client si disconnette, deve eseguire di nuovo la sottoscrizione all'argomento di notifica KEYNOTIFY e inviare nuovamente il comando KEYNOTIFY per le chiavi necessarie per continuare il monitoraggio. A differenza delle sottoscrizioni MQTT, che possono essere mantenute in una sessione non pulita, l'archivio stati rimuove internamente tutti i messaggi KEYNOTIFY quando un determinato client si disconnette.

FORMATO del messaggio di notifica KEYNOTIFY

Quando una chiave monitorata tramite KEYNOTIFY viene modificata, l'archivio stati PUBLISH un messaggio all'argomento di notifica seguendo il formato per archiviare i client registrati per la modifica.

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

I dettagli seguenti sono inclusi nel messaggio:

• NOTIFY è un valore letterale stringa incluso come primo argomento nel payload, che indica che è arrivata una notifica.
• {operation} è l'evento che si è verificato. Attualmente queste operazioni sono:
  • SET il valore è stato modificato. Questa operazione può verificarsi solo come risultato di un comando SET da un client dell'archivio stati.
  • DEL il valore è stato eliminato. Questa operazione può verificarsi a causa di un comando DEL o VDEL da un client dell'archivio stati.
• optionalFields
  • VALUE e {MODIFIED-VALUE}. VALUE è un valore letterale stringa che indica che il campo successivo, {MODIFIED-VALUE}, contiene il valore in cui è stata modificata la chiave. Questo valore viene inviato solo in risposta alla modifica delle chiavi a causa di un oggetto SET.

L'output di esempio seguente mostra un messaggio di notifica inviato quando la chiave SOMEKEY viene modificata nel valore abc, con VALUE incluso perché la richiesta iniziale ha specificato l'opzione GET:

*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>

Contenuto correlato

• Panoramica del broker MQTT
• Sviluppare con il broker MQTT