Udostępnij za pośrednictwem

Protokół magazynu stanów brokera MQTT

  • Artykuł

Ważne

Usługa Azure IoT Operations Preview — włączona przez usługę Azure Arc jest obecnie dostępna w wersji zapoznawczej. Nie należy używać tego oprogramowania w wersji zapoznawczej w środowiskach produkcyjnych.

Po udostępnieniu ogólnie dostępnej wersji należy wdrożyć nową instalację operacji usługi Azure IoT. Nie będzie można uaktualnić instalacji w wersji zapoznawczej.

Zobacz Dodatkowe warunki użytkowania wersji zapoznawczych platformy Microsoft Azure, aby zapoznać się z postanowieniami prawnymi dotyczącymi funkcji platformy Azure, które są w wersji beta lub wersji zapoznawczej albo w inny sposób nie zostały jeszcze wydane jako ogólnie dostępne.

Magazyn stanów MQ jest rozproszonym systemem magazynu w klastrze operacji usługi Azure IoT. Magazyn stanów oferuje te same gwarancje wysokiej dostępności co komunikaty MQTT w brokerze MQTT. Zgodnie z wytycznymi protokołu MQTT5/RPC klienci powinni korzystać z MQTT5 do interakcji z magazynem stanów MQQ. Ten artykuł zawiera wskazówki dotyczące protokołu dla deweloperów, którzy muszą zaimplementować własnych klientów magazynu stanów brokera MQTT.

Omówienie protokołu magazynu stanów

Magazyn stanów MQ obsługuje następujące polecenia:

  • SET<keyName><keyValue><setOptions>
  • GET<keyName>
  • DEL<keyName>
  • VDEL<keyName keyValue> ## Usuwa daną <wartość keyName>><, jeśli i tylko wtedy, gdy jej wartość to <keyValue>

Protokół używa następującego modelu odpowiedzi na żądanie:

  • Żądanie. Klienci publikują żądanie w dobrze zdefiniowanym temacie systemu magazynu stanów. Aby opublikować żądanie, klienci używają wymaganych właściwości i ładunku opisanego w poniższych sekcjach.
  • Response. Magazyn stanów asynchronicznie przetwarza żądanie i odpowiada na temat odpowiedzi, który początkowo podał klient.

Na poniższym diagramie przedstawiono podstawowy widok żądania i odpowiedzi:

Diagram podstawowego procesu żądania i odpowiedzi magazynu stanów.

Temat systemu magazynu stanów, QoS i wymagane właściwości MQTT5

Aby komunikować się z magazynem stanów, klienci muszą spełniać następujące wymagania:

  • Użyj MQTT5. Aby uzyskać więcej informacji, zobacz specyfikację MQTT 5.
  • Użyj funkcji QoS 1 (poziom jakości usług 1). QoS 1 jest opisany w specyfikacji MQTT 5.
  • Zegar, który znajduje się w ciągu jednej minuty od zegara brokera MQTT.

Aby komunikować się z magazynem stanów, klienci muszą żądać PUBLISH do tematu statestore/v1/FA9AE35F-2F64-47CD-9BFF-08E2B32A0FE8/command/invokesystemowego . Ponieważ magazyn stanów jest częścią operacji usługi Azure IoT, jest niejawny SUBSCRIBE w tym temacie podczas uruchamiania.

Aby utworzyć żądanie, wymagane są następujące właściwości MQTT5. Jeśli te właściwości nie są obecne lub żądanie nie jest typu QoS 1, żądanie kończy się niepowodzeniem.

  • Temat odpowiedzi. Magazyn stanów odpowiada na początkowe żądanie przy użyciu tej wartości. Najlepszym rozwiązaniem jest sformatowanie tematu odpowiedzi jako clients/{clientId}/services/statestore/_any_/command/invoke/response. Ustawienie tematu odpowiedzi jako statestore/v1/FA9AE35F-2F64-47CD-9BFF-08E2B32A0FE8/command/invoke lub jako tematu rozpoczynającego się od clients/statestore/v1/FA9AE35F-2F64-47CD-9BFF-08E2B32A0FE8 jest niedozwolone w żądaniu magazynu stanów. Magazyn stanów rozłącza klientów MQTT, którzy używają nieprawidłowego tematu odpowiedzi.
  • Dane korelacji. Gdy magazyn stanów wysyła odpowiedź, zawiera dane korelacji początkowego żądania.

Na poniższym diagramie przedstawiono rozszerzony widok żądania i odpowiedzi:

Diagram rozszerzonego procesu żądania i odpowiedzi magazynu stanów.

Obsługiwane polecenia

Polecenia SET, GETi DEL zachowują się zgodnie z oczekiwaniami.

Wartości SET ustawiane przez polecenia i GET pobierane przez polecenie są dowolnymi danymi binarnymi. Rozmiar wartości jest ograniczony tylko przez maksymalny rozmiar ładunku MQTT oraz ograniczenia zasobów MQQ i klienta.

SET Opcje

Polecenie SET udostępnia więcej opcjonalnych flag poza podstawowymi keyValue i keyName:

  • NX. Umożliwia ustawienie klucza tylko wtedy, gdy jeszcze nie istnieje.
  • NEX <value>. Umożliwia ustawienie klucza tylko wtedy, gdy klucz nie istnieje lub jeśli wartość klucza jest już ustawiona na <wartość>. Flaga NEX jest zwykle używana dla klienta odnawiającego wygaśnięcie (PX) na kluczu.
  • PX. Jak długo klucz powinien być utrwalany przed jego wygaśnięciem, w milisekundach.

VDEL Opcje

Polecenie VDEL jest specjalnym przypadkiem DEL polecenia . DEL bezwarunkowo usuwa daną keyNamewartość . VDEL wymaga innego argumentu o nazwie keyValue. VDEL usuwa dane tylko wtedy keyName , gdy ma ten sam keyValueelement .

Format ładunku

Format ładunku magazynu PUBLISH stanów jest inspirowany przez reSP3, który jest podstawowym protokołem używanym przez usługę Redis. RESP3 koduje zarówno czasownik, jak lub , oraz parametry, takie jak SET keyName i keyValue.GET

Uwzględnij wielkość liter

Klient musi wysłać zarówno czasowniki, jak i opcje w wielkim przypadku.

Format żądania

Żądania są formatowane tak jak w poniższym przykładzie. Po reSP3 reprezentuje * liczbę elementów w tablicy. Znak $ jest liczbą znaków w następującym wierszu, z wyłączeniem końcowego znaku CRLF.

Obsługiwane polecenia w formacie RESP3 to GET, SET, DELi 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>

W poniższych przykładowych danych wyjściowych przedstawiono ładunki RESP3 magazynu stanów:

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

Uwaga

Należy pamiętać, że SET wymaga dodatkowych właściwości MQTT5, jak wyjaśniono w sekcji Przechowywanie wersji i hybrydowych zegarów logicznych.

Format odpowiedzi

Gdy magazyn stanów wykryje nieprawidłowy ładunek RESP3, nadal zwraca odpowiedź na Response Topicżądanie . Przykłady nieprawidłowych ładunków obejmują nieprawidłowe polecenie, niedozwolony przepełnienie RESP3 lub liczba całkowita. Nieprawidłowy ładunek rozpoczyna się od ciągu -ERR i zawiera więcej szczegółów.

Uwaga

Żądanie GET, DELlub VDEL dla nieistniejących kluczy nie jest uznawane za błąd.

Jeśli klient wysyła nieprawidłowy ładunek, magazyn stanów wysyła ładunek podobny do następującego przykładu:

-ERR syntax error

SET odpowiedź

SET Gdy żądanie zakończy się pomyślnie, magazyn stanów zwraca następujący ładunek:

+OK<CR><LF>

Jeśli żądanie SET zakończy się niepowodzeniem, ponieważ sprawdzanie warunku określonego w opcjach zestawu NX lub NEX, co oznacza, że nie można ustawić klucza, magazyn stanów zwraca następujący ładunek:

-1<CR><LF>

GET odpowiedź

GET Gdy żądanie zostanie wykonane na nieistnienym kluczu, magazyn stanów zwraca następujący ładunek:

$-1<CR><LF>

Po znalezieniu klucza magazyn stanów zwraca wartość w następującym formacie:

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

Dane wyjściowe magazynu stanów zwracającego wartość 1234 wyglądają podobnie do następującego przykładu:

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

DEL i VDEL odpowiedź

Magazyn stanów zwraca liczbę wartości usuniętych w żądaniu usuwania. Obecnie magazyn stanów może usuwać tylko jedną wartość jednocześnie.

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

Następujące dane wyjściowe to przykład pomyślnego DEL polecenia:

:1<CR><LF>

Jeśli żądanie VDEL zakończy się niepowodzeniem, ponieważ określona wartość nie odpowiada wartości skojarzonej z kluczem, magazyn stanów zwraca następujący ładunek:

-1<CR><LF>

-ERR Odpowiedzi

Poniżej znajduje się bieżąca lista ciągów błędów. Aplikacja kliencka powinna obsługiwać nieznane ciągi błędów , aby obsługiwać aktualizacje magazynu stanów.

Ciąg błędu zwrócony z magazynu stanów Wyjaśnienie
znacznik czasu żądania jest zbyt daleko w przyszłości; upewnij się, że zegary systemowe klienta i brokera są zsynchronizowane Nieoczekiwany znacznik czasu żądania spowodowany przez magazyn stanów i zegary klienta nie są zsynchronizowane.
token ogrodzenia jest wymagany dla tego żądania Błąd występuje, jeśli klucz jest oznaczony tokenem ogrodzenia, ale klient nie określa tokenu ogrodzenia.
sygnatura czasowa tokenu ogrodzenia żądania jest zbyt daleko w przyszłości; upewnij się, że zegary systemowe klienta i brokera są zsynchronizowane Nieoczekiwany znacznik czasu tokenu ogrodzenia spowodowany przez magazyn stanów i zegary klienta nie są zsynchronizowane.
token ogrodzenia żądania jest niższą wersją, którą token ogrodzenia chroni zasób Nieprawidłowa wersja tokenu żądania ogrodzenia. Aby uzyskać więcej informacji, zobacz [Przechowywanie wersji i hybrydowe zegary logiczne]. (zegary logiczne #versioning i hybrydowe)
przekroczono limit przydziału Magazyn stanów ma limit przydziału liczby kluczy, które może przechowywać, co jest oparte na profilu pamięci określonego brokera MQTT.
błąd składniowy Wysłany ładunek nie jest zgodny z definicją magazynu stanów.
brak autoryzacji Błąd autoryzacji
nieznane polecenie Polecenie nie jest rozpoznawane.
nieprawidłowa liczba argumentów Nieprawidłowa liczba oczekiwanych argumentów.
brak znacznika czasu Gdy klienci wykonują zestaw, muszą ustawić właściwość użytkownika MQTT5 __ts jako znacznik czasu HLC.
źle sformułowany znacznik czasu Sygnatura czasowa w __ts lub token ogrodzenia nie jest legalny.
długość klucza wynosi zero Klucze nie mogą mieć zerowej długości w magazynie stanów.

Przechowywanie wersji i hybrydowych zegarów logicznych

W tej sekcji opisano sposób obsługi przechowywania wersji przez magazyn stanów.

Wersje jako hybrydowe zegary logiczne

Magazyn stanów przechowuje wersję dla każdej przechowywanej przez nią wartości. Magazyn stanów może używać monotonicznie rosnącej licznika do obsługi wersji. Zamiast tego magazyn stanów używa hybrydowego zegara logicznego (HLC) do reprezentowania wersji. Aby uzyskać więcej informacji, zobacz artykuły dotyczące oryginalnego projektu HLC i intencji HLCs.

Magazyn stanów używa następującego formatu do zdefiniowania kontrolerów HLC:

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

Jest wallClock to liczba milisekund od epoki Unix. counter i node-Id działają ogólnie jako HLC.

Gdy klienci wykonują SETpolecenie , muszą ustawić właściwość __ts użytkownika MQTT5 jako HLC reprezentującą jego sygnaturę czasową na podstawie bieżącego zegara klienta. Magazyn stanów zwraca wersję wartości w komunikacie odpowiedzi. Odpowiedź jest również określana jako HLC, a także używa __ts właściwości użytkownika MQTT5. Zwrócony HLC jest zawsze większy niż HLC początkowego żądania.

Przykład ustawiania i pobierania wersji wartości

W tej sekcji przedstawiono przykład ustawienia i pobrania wersji dla wartości.

Klient ustawia wartość keyName=value. Zegar klienta to 3 października, 11:07:05 GMT. Wartość zegara to 1696374425000 milisekundy od epoki Unix. Załóżmy, że zegar systemowy magazynu stanów jest identyczny z zegarem systemowym klienta. Klient wykonuje polecenie zgodnie z SET wcześniejszym opisem.

Na poniższym diagramie przedstawiono SET polecenie :

Diagram polecenia magazynu stanów, aby ustawić wersję dla wartości.

Właściwość (sygnatura __ts czasowa) w zestawie początkowym zawiera 1696374425000 jako zegar ścienny klienta, licznik jako 0, i jego identyfikator węzła jako CLIENT. W odpowiedzi właściwość zwracana __ts przez magazyn stanów zawiera wallClocklicznik przyrostowy o jeden i identyfikator węzła jako StateStore. Magazyn stanów może zwrócić wyższą wallClock wartość, jeśli zegar był z wyprzedzeniem, na podstawie sposobu działania aktualizacji HLC.

Ta wersja jest również zwracana w przypadku pomyślnych GETżądań , DELi VDEL . W przypadku tych żądań klient nie określa elementu __ts.

Na poniższym diagramie przedstawiono GET polecenie :

Diagram przedstawiający magazyn stanów uzyskujący wersję wartości.

Uwaga

Sygnatura czasowa __ts zwracana przez magazyn stanów jest taka sama jak wartość zwrócona w początkowym SET żądaniu.

Jeśli dany klucz zostanie później zaktualizowany o nowy SET, proces będzie podobny. Klient powinien ustawić swoje żądanie __ts na podstawie bieżącego zegara. Magazyn stanów aktualizuje wersję wartości i zwraca __tswartość , postępując zgodnie z regułami aktualizacji HLC.

Niedokładność zegara

Magazyn stanów odrzuca __ts (a także __ft) , który jest ponad minutę przed zegarem lokalnym magazynu stanów.

Magazyn stanów akceptuje wartość, __ts która znajduje się za zegarem lokalnym magazynu stanów. Jak określono w algorytmie HLC, magazyn stanów ustawia wersję klucza na zegar lokalny, ponieważ jest większy.

Tokeny blokujące i ogrodzeniowe

W tej sekcji opisano przeznaczenie i użycie tokenów blokady i ogrodzenia.

Tło

Załóżmy, że istnieje co najmniej dwóch klientów MQTT korzystających z magazynu stanów. Obaj klienci chcą zapisywać dane w danym kluczu. Klienci magazynu stanów muszą mieć mechanizm blokowania klucza, tak aby tylko jeden klient naraz mógł zmodyfikować dany klucz.

Przykład tego scenariusza występuje w systemach aktywnych i rezerwowych. Mogą istnieć dwa klienci, którzy wykonują tę samą operację, a operacja może zawierać ten sam zestaw kluczy magazynu stanów. W danym momencie jeden z klientów jest aktywny, a drugi stoi, aby natychmiast przejąć, jeśli aktywny system zawiesza się lub ulega awarii. W idealnym przypadku tylko jeden klient powinien zapisywać dane w magazynie stanów w danym momencie. Jednak w systemach rozproszonych możliwe, że obaj klienci mogą zachowywać się tak, jakby byli aktywni, i mogą jednocześnie próbować zapisywać w tych samych kluczach. Ten scenariusz tworzy warunek wyścigu.

Magazyn stanów zapewnia mechanizmy zapobiegania temu stanowi wyścigu przy użyciu tokenów ogrodzeniowych. Aby uzyskać więcej informacji na temat tokenów ogrodzeniowych i klasy warunków wyścigu, które są przeznaczone do ochrony przed, zobacz ten artykuł.

Uzyskiwanie tokenu ogrodzeniowego

W tym przykładzie przyjęto założenie, że mamy następujące elementy:

  • Client1 i Client2. Ci klienci są klientami magazynu stanów, którzy działają jako aktywna i rezerwowa para.
  • LockName. Nazwa klucza w magazynie stanów, który działa jako blokada.
  • ProtectedKey. Klucz, który musi być chroniony przed wieloma składnikami zapisywania.

Klienci próbują uzyskać blokadę jako pierwszy krok. Otrzymują blokadę, wykonując polecenie SET LockName {CLIENT-NAME} NEX PX {TIMEOUT-IN-MILLISECONDS}. Przypomnij sobie z opcji zestawu , że flaga NEX oznacza, że powodzenie zakończy się powodzeniem tylko wtedy, SET gdy zostanie spełniony jeden z następujących warunków:

  • Klucz był pusty
  • Wartość klucza jest już ustawiona na <wartość> i PX określa limit czasu w milisekundach.

Załóżmy, że Client1 najpierw jest to żądanie .SET LockName Client1 NEX PX 10000 To żądanie daje mu własność LockName 10 000 milisekund. Jeśli Client2 próbujesz chwilę Client1 SET LockName Client2 NEX ... posiadać blokadę, flaga NEX oznaczaClient2, że żądanie zakończy się niepowodzeniem. Client1 musi odnowić tę blokadę, wysyłając to samo SET polecenie użyte do uzyskania blokady, jeśli Client1 chce kontynuować własność.

Uwaga

Element A SET NX jest koncepcyjnie odpowiednikiem elementu AcquireLock().

Używanie tokenów ogrodzenia w żądaniach SET

Po Client1 pomyślnym zakończeniu SET działania elementu ("AquireLock") w LockNamemagazynie stanów jest zwracana wersja LockName hybrydowego zegara logicznego (HLC) we właściwości __tsużytkownika MQTT5 .

Gdy klient wykonuje SET żądanie, może opcjonalnie dołączyć właściwość __ft użytkownika MQTT5 do reprezentowania "tokenu ogrodzenia". Element __ft jest reprezentowany jako HLC. Token ogrodzenia skojarzony z daną parą klucz-wartość zapewnia kontrolę własności blokady. Token ogrodzenia może pochodzić z dowolnego miejsca. W tym scenariuszu powinna pochodzić z wersji .LockName

Na poniższym diagramie przedstawiono proces Client1 wykonywania SET żądania w witrynie LockName:

Diagram przedstawiający klienta wykonującego żądanie ustawione we właściwości nazwa blokady.

Client1 Następnie użyje __ts właściwości (Property=1696374425000:1:StateStore) niezmodyfikowanej jako podstawy __ft właściwości w żądaniu, aby zmodyfikować ProtectedKeyelement . Podobnie jak wszystkie SET żądania, klient musi ustawić __ts właściwość ProtectedKey.

Na poniższym diagramie przedstawiono proces Client1 wykonywania SET żądania w witrynie ProtectedKey:

Diagram przedstawiający klienta wykonującego żądanie zestawu we właściwości klucza chronionego.

Jeśli żądanie zakończy się powodzeniem, od tego momentu ProtectedKey żądanie wymaga tokenu ogrodzenia równego lub większego niż określony w żądaniu SET .

Algorytm tokenu ogrodzenia

Magazyn stanów akceptuje dowolny klucz HLC dla __ts pary klucz-wartość, jeśli wartość mieści się w maksymalnej niesymetryczności zegara. Jednak to samo nie dotyczy tokenów ogrodzenia.

Algorytm magazynu stanów dla tokenów ogrodzenia jest następujący:

  • Jeśli para klucz-wartość nie ma skojarzonego z nim tokenu ogrodzenia i SET zestaw żądań __ft, magazyn stanów przechowuje skojarzone __ft z parą klucz-wartość.
  • Jeśli para klucz-wartość ma skojarzony token ogrodzenia:
    • SET Jeśli żądanie nie zostało określone__ft, odrzuć żądanie.
    • SET Jeśli żądanie określiło__ft, że ma starszą wartość HLC niż token ogrodzenia skojarzony z parą klucz-wartość, odrzuć żądanie.
    • SET Jeśli żądanie określiło __ft wartość HLC równą lub nowszą niż token ogrodzenia skojarzony z parą klucz-wartość, zaakceptuj żądanie. Magazyn stanów aktualizuje token ogrodzenia pary klucz-wartość tak, aby był ustawiony w żądaniu, jeśli jest nowszy.

Po oznaczeniu klucza tokenem ogrodzenia, aby żądanie powiodło się, DEL a VDEL żądania również wymagają __ft dołączenia właściwości. Algorytm jest identyczny z poprzednim, z tą różnicą, że token ogrodzenia nie jest przechowywany, ponieważ klucz jest usuwany.

Zachowanie klienta

Te mechanizmy blokowania polegają na zachowaniu klientów. W poprzednim przykładzie niewłaściwe zachowanie Client2 nie może być właścicielem LockName elementu i nadal pomyślnie wykonać SET ProtectedKey , wybierając token ogrodzenia, który jest nowszy niż ProtectedKey token. Magazyn stanów nie zdaje sobie sprawy, że LockName i ProtectedKey nie ma żadnej relacji. W związku z tym magazyn stanów nie wykonuje walidacji, która Client2 faktycznie jest właścicielem wartości.

Klienci mogą zapisywać klucze, dla których nie są właścicielami blokady, jest niepożądanym zachowaniem. Ochronę przed takimi błędami klienta można chronić, poprawnie implementując klientów i używając uwierzytelniania, aby ograniczyć dostęp do kluczy tylko do zaufanych klientów.

Notifications

Klienci mogą rejestrować się w magazynie stanów w celu otrzymywania powiadomień o modyfikowanych kluczach. Rozważmy scenariusz, w którym termostat używa klucza {thermostatName}\setPointmagazynu stanów . Inni klienci magazynu stanów mogą zmienić wartość tego klucza, aby zmienić punkt setPoint termostatu. Zamiast sondować zmiany, termostat może zarejestrować się w magazynie stanów w celu odbierania komunikatów po {thermostatName}\setPoint zmodyfikowaniu.

KOMUNIKATY ŻĄDANIA KEYNOTIFY

Klienci magazynu stanów żądają, aby magazyn stanów monitorował dane keyName zmiany, wysyłając KEYNOTIFY komunikat. Podobnie jak wszystkie żądania magazynu stanów, klienci publikują komunikat QoS1 z tym komunikatem za pośrednictwem MQTT5 do tematu statestore/v1/FA9AE35F-2F64-47CD-9BFF-08E2B32A0FE8/command/invokesystemu magazynu stanów .

Ładunek żądania ma następującą postać:

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

Gdzie:

  • KEYNOTIFY to literał ciągu określający polecenie.
  • {keyName} to nazwa klucza do nasłuchiwania powiadomień. Symbole wieloznaczne nie są obecnie obsługiwane.
  • {optionalFields} Obecnie obsługiwane wartości pól opcjonalnych to:
    • {STOP} Jeśli istnieje powiadomienie o tym samym keyName żądaniu i clientId co to żądanie, magazyn stanów go usunie.

W poniższych przykładowych danych wyjściowych przedstawiono KEYNOTIFY żądanie monitorowania klucza SOMEKEY:

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

KOMUNIKAT ODPOWIEDZI KEYNOTIFY

Podobnie jak wszystkie żądania RPC magazynu stanów, magazyn stanów zwraca odpowiedź na Response Topic i używa Correlation Data właściwości określonych w początkowym żądaniu. W przypadku KEYNOTIFYelementu odpowiedź zakończona powodzeniem wskazuje, że magazyn stanów przetworzył żądanie. Gdy magazyn stanów pomyślnie przetworzy żądanie, monitoruje klucz bieżącego klienta lub zatrzymuje monitorowanie.

Po pomyślnym zakończeniu odpowiedź magazynu stanów jest taka sama jak pomyślna SET.

+OK<CR><LF>

Jeśli klient wysyła KEYNOTIFY SOMEKEY STOP żądanie, ale magazyn stanów nie monitoruje tego klucza, odpowiedź magazynu stanów jest taka sama jak próba usunięcia klucza, który nie istnieje.

:0<CR><LF>

Wszelkie inne błędy są zgodne z ogólnym wzorcem raportowania błędów magazynu stanów:

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

TEMATY powiadomień KEYNOTIFY i cykl życia

keyName Gdy monitorowany za pośrednictwem KEYNOTIFY programu jest modyfikowany lub usuwany, magazyn stanów wysyła powiadomienie do klienta. Temat jest określany zgodnie z konwencją — klient nie określa tematu KEYNOTIFY podczas procesu.

Temat jest zdefiniowany w poniższym przykładzie. Jest clientId to kodowana wielkimi literami reprezentacja szesnastkowego identyfikatora ClientId klienta MQTT, który zainicjował KEYNOTIFY żądanie i keyName jest zakodowaną szesnastką reprezentacją zmienionego klucza. Magazyn stanów jest zgodny z regułami kodowania Base 16 RFC 4648 — Base16, Base32 i Base64 Data Encodings dla tego kodowania.

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

Na przykład MQ publikuje NOTIFY komunikat wysyłany do client-id1 programu o zmodyfikowanej nazwie SOMEKEY klucza do tematu:

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

Klient korzystający z powiadomień powinien SUBSCRIBE być wysyłany do tego tematu SUBACK i czekać na odebranie żądania przed wysłaniem żądań KEYNOTIFY , aby żadne komunikaty nie zostały utracone.

Jeśli klient rozłącza się, musi ponownie przypisać KEYNOTIFY temat powiadomienia i ponownie wysłać KEYNOTIFY polecenie dla wszystkich kluczy, które musi kontynuować monitorowanie. W przeciwieństwie do subskrypcji MQTT, które mogą być utrwalane w sesji nieczystej, magazyn stanów wewnętrznie usuwa wszelkie KEYNOTIFY komunikaty, gdy dany klient rozłącza się.

FORMAT KOMUNIKATU POWIADOMIENIA KEYNOTIFY

Gdy klucz monitorowany za pośrednictwem KEYNOTIFY jest modyfikowany, magazyn stanów będzie PUBLISH komunikatem do tematu powiadomień w formacie dla klientów magazynu stanów zarejestrowanych w celu zmiany.

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

W komunikacie znajdują się następujące szczegóły:

  • NOTIFY jest literałem ciągu dołączonym jako pierwszy argument w ładunku, co wskazuje na przybycie powiadomienia.
  • {operation} to zdarzenie, które miało miejsce. Obecnie są to następujące operacje:
    • SET wartość została zmodyfikowana. Ta operacja może wystąpić tylko w wyniku SET polecenia z klienta magazynu stanów.
    • DEL wartość została usunięta. Ta operacja może wystąpić z DEL powodu polecenia lub VDEL z klienta magazynu stanów.
  • optionalFields
    • VALUE i {MODIFIED-VALUE}. VALUE to literał ciągu wskazujący, że następne pole , {MODIFIED-VALUE}zawiera wartość, na którą został zmieniony klucz. Ta wartość jest wysyłana tylko w odpowiedzi na zmodyfikowane klucze z powodu elementu SET.

Następujące przykładowe dane wyjściowe pokazują komunikat powiadomienia wysyłany po zmodyfikowaniu klucza SOMEKEY do wartości abc, z VALUE dołączonym żądaniem, ponieważ początkowe żądanie określiło GET opcję:

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

Powiązana zawartość