sgcMQ w pięć minut

W tym pakiecie jest siedem natywnych klientów komunikatów. MQTT to najkrótsza droga do czegoś działającego, więc właśnie to robi ta strona: łączy się z brokerem, subskrybuje temat, publikuje wiadomość i patrzy, jak wraca. AMQP, Kafka i STOMP mają ten sam dwukomponentowy kształt.

MQTT 3.1.1 i 5.0, AMQP 0.9.1 i 1.0, Kafka, STOMP
Bez zewnętrznych bibliotek i bez DLL
Edycja Standard i wyższe
W skrócie

Dwa komponenty, nie jeden

To część, na której ludzie się potykają. Komponent protokołu mówi MQTT, a osobny komponent klienta zarządza gniazdem. Łączysz je jednym przypisaniem.

Komponent protokołu

TsgcWSPClient_MQTT na stronie palety SGC MQ. Zawiera Connect, Subscribe, Publish, UnSubscribe i trzynaście zdarzeń MQTT.

Komponent transportu

TsgcWebSocketClient dla MQTT przez WebSockety lub TsgcTCPClient dla zwykłego MQTT przez TCP. Na tym ustawiasz Host i Port.

Jedna linijka, która je łączy

MQTT.Client := WSClient;. Potem otwierasz połączenie, ustawiając WSClient.Active := True, a nie wywołując metodę protokołu.

Platformy

sgcWebSocket_Protocol_MQTT_Client.pas nie ma warunku platformy, tylko warunkowy import Windows, a komponent jest zarejestrowany z ComponentPlatforms(0). Kompiluje się każdy cel.

Zanim zaczniesz

Wymagania i edycje

Kolumna edycji to define, który ogranicza każdy protokół, wraz z linią w Source/sgcVer.inc, w której się znajduje.

Co Wartość
IDE Od Delphi 7 do RAD Studio 13 oraz od C++Builder 2007 do 13.
Klauzula uses sgcWebSocket_Protocols dla TsgcWSPClient_MQTT, sgcWebSocket dla klienta, sgcWebSocket_Classes dla TsgcWSConnection oraz sgcWebSocket_Types dla TmqttQoS.
Edycja MQTT SGC_MQTT jest zdefiniowany w linii 717, wewnątrz bloku {$IFDEF SGC_EDT_STD}, który biegnie od linii 675 do linii 724. Czyli Standard i wyższe. Bloki są kumulatywne, więc Professional, Enterprise i All-Access też go zawierają.
Pozostałe protokoły Wszystkie w tym samym bloku Standard: SGC_STOMP w linii 716, SGC_AMQP w 718, SGC_AMQP1 w 719, SGC_KAFKA w 720 i SGC_WAMP w 715. Żaden z nich nie jest funkcją Enterprise.
Edycja, samodzielny pakiet Produkt sgcMQ definiuje SGC_PACK_MQ w linii 855, a jego własny blok w liniach 959 do 966 włącza te same pięć definów protokołów.
Platformy Brak warunku platformy na poziomie jednostki klienta MQTT. Jedynym warunkiem w jego klauzuli uses jest {$IFDEF MSWINDOWS}Windows, {$ENDIF}.

Chcesz brokera do testów bez instalowania własnego? Dostarczane demo MQTT wskazuje publiczny broker testowy na www.esegece.com, port 15675 dla MQTT przez WebSockety.

Krok 1

Zainstaluj i znajdź stronę palety

sgcMQ jest dostarczany w instalatorze sgcWebSockets, a także jako osobny pakiet. Instalacja jest w obu przypadkach taka sama.

1. Rozpakuj

Rozpakuj pobrany plik do folderu, który poniżej nazywamy {$DIR}.

2. Ścieżka biblioteki

Tools, Options, Library. Dodaj {$DIR}\source oraz folder lib dla swojego IDE, na przykład {$DIR}\libD13\$(Platform).

3. Zbuduj pakiety

Otwórz grupę pakietów dla swojej wersji IDE w {$DIR}\Packages\. Najpierw skompiluj uruchomieniowy .dpk, a potem zainstaluj ten czasu projektowania z prefiksem dcl.

4. Sprawdź paletę

Pojawia się strona o nazwie SGC MQ, zawierająca klientów protokołów włączonych przez twoją edycję. W kompilacji Standard i wyższych jest tam TsgcWSPClient_MQTT.

5. Otwórz demo

Otwórz {$DIR}\Demos\02.WebSocket_Protocols\08.MQTT_Client. Stąd pochodzi poniższy kod i jest już skierowane na działający broker testowy.

QuickStart

Połącz, subskrybuj, publikuj

Podłącz protokół do klienta, otwórz połączenie, zasubskrybuj temat i opublikuj w nim wiadomość. Wiadomość wraca w OnMQTTPublish.

uClientMQTT.pas 
uses
  Classes, SysUtils,
  // sgc
  sgcWebSocket, sgcWebSocket_Classes, sgcWebSocket_Protocols,
  sgcWebSocket_Types, sgcWebSocket_Protocol_MQTT_Client,
  sgcWebSocket_Protocol_MQTT_Message;

procedure TfrmClientPROTOCOL.FormCreate(Sender: TObject);
begin
  WSClient := TsgcWebSocketClient.Create(Self);
  WSClient.Host := 'www.esegece.com';
  WSClient.Port := 15675;
  WSClient.TLS := False;

  // ... attach the client to the MQTT protocol
  MQTT.Client := WSClient;

  // ... and THIS is what opens the connection.
  // There is no Connect call on the protocol component.
  WSClient.Active := True;
end;

Dla zwykłego MQTT przez TCP zamiast przez WebSockety utwórz TsgcTCPClient z sgcTCP_Client_WS i skieruj na niego MQTT.Client. Nic więcej się nie zmienia, i właśnie dlatego oba komponenty są osobne.

uClientMQTT.pas 
procedure TfrmClientPROTOCOL.btnSubscribeClick(Sender: TObject);
begin
  MQTT.Subscribe('sgc/quickstart');
end;

procedure TfrmClientPROTOCOL.btnPublishClick(Sender: TObject);
begin
  // topic, payload, QoS, retain
  MQTT.Publish('sgc/quickstart', 'hello from Delphi',
    mtqsAtLeastOnce, False);
end;

procedure TfrmClientPROTOCOL.btnUnsubscribeClick(Sender: TObject);
begin
  MQTT.UnSubscribe('sgc/quickstart');
end;

Publish zwraca Word, czyli identyfikator pakietu, i nie czeka. PublishAndWait zwraca Boolean i blokuje do potwierdzenia przez brokera, z limitem czasu domyślnie dziesięć sekund. TmqttQoS pochodzi z sgcWebSocket_Types.

uClientMQTT.pas 
procedure TfrmClientPROTOCOL.MQTTMQTTConnect(Connection: TsgcWSConnection;
  const Session: Boolean; const ReasonCode: Integer;
  const ReasonName: String;
  const ConnectProperties: TsgcWSMQTTCONNACKProperties);
begin
  memoLog.Lines.Add('#connected: ' + ReasonName);
end;

procedure TfrmClientPROTOCOL.MQTTMQTTSubscribe(Connection: TsgcWSConnection;
  aPacketIdentifier: Word; aCodes: TsgcWSSUBACKS;
  SubscribeProperties: TsgcWSMQTTSUBACKProperties);
begin
  memoLog.Lines.Add('#subscribed: ' + IntToStr(aPacketIdentifier));
end;

procedure TfrmClientPROTOCOL.MQTTMQTTPublish(Connection: TsgcWSConnection;
  aTopic, aText: string;
  PublishProperties: TsgcWSMQTTPUBLISHProperties);
begin
  memoLog.Lines.Add(aTopic + ': ' + aText);
end;

To trzy zdarzenia, które liczą się na początku. Dziewięć kolejnych służy do przepływu potwierdzeń, rozłączania i uwierzytelniania MQTT 5.0. Pozwól IDE wygenerować procedury obsługi, ponieważ listy parametrów są długie, a obiekty właściwości różnią się w zależności od zdarzenia.

Wszystkie trzy karty pochodzą z dostarczanego dema Demos\02.WebSocket_Protocols\08.MQTT_Client\uClientMQTT.pas, z kontrolkami formularza zastąpionymi literałami. Obiekt MQTT jest w tym projekcie umieszczony na formularzu; utworzenie go w kodzie działa identycznie.

Krok 2

Potwierdź wymianę w obie strony

Dwa zdarzenia mówią ci, że broker cię zaakceptował i temat jest aktywny.

OnMQTTConnect

Broker zaakceptował sesję. ReasonCode i ReasonName mówią, dlaczego tak się nie stało, co jest znacznie przydatniejsze niż zerwane gniazdo.

OnMQTTSubscribe

Subskrypcja została przyznana. aCodes, czyli TsgcWSSUBACKS, niesie odpowiedź brokera dla każdego tematu, więc odrzucona subskrypcja jest widoczna, a nie cicha.

OnMQTTPublish

Nadeszła wiadomość. Opublikuj w temacie, który właśnie zasubskrybowałeś, a wróci od razu, co potwierdza całą ścieżkę jednym kliknięciem.

Zdarzenia potwierdzeń

Przy QoS 1 i 2 dostarczenie jest potwierdzane później, w OnMQTTPubAck, OnMQTTPubRec, OnMQTTPubRel i OnMQTTPubComp. Jeśli zamiast tego potrzebujesz wywołania blokującego, użyj PublishAndWait.

Typowe problemy

Co zwykle idzie nie tak za pierwszym razem

Sześć problemów odpowiada za niemal każde nieudane pierwsze połączenie.

Nic się nie dzieje po wywołaniu Subscribe

Połączenie nie jest jeszcze otwarte. Komponent protokołu nie otwiera gniazda, robi to klient. Ustaw WSClient.Active := True i poczekaj na OnMQTTConnect przed subskrypcją.

Naruszenie dostępu przy pierwszym wywołaniu

MQTT.Client nigdy nie został przypisany. Ta jedna linijka wiąże protokół z transportem, a bez niej protokół nie ma gdzie pisać.

Zły port dla złego transportu

MQTT przez WebSockety i MQTT przez zwykły TCP to w większości brokerów różne porty. 1883 i 8883 to zwykłe porty TCP, a punkt końcowy WebSocket jest zupełnie gdzie indziej. Dostarczane demo używa 15675 dla WebSocketów.

Szukasz OnMQTTMessage

Takiego zdarzenia nie ma. Przychodzące wiadomości brokera docierają w OnMQTTPublish jako tekst oraz w OnMQTTPublishEx, gdy chcesz surowy ładunek i pełny obiekt wiadomości.

QoS 1 i 2 wyglądają, jakby nic nie zrobiły

Są potwierdzane asynchronicznie. Publish od razu zwraca identyfikator pakietu, a potwierdzenie przychodzi później w OnMQTTPubAck, OnMQTTPubRec, OnMQTTPubRel lub OnMQTTPubComp. Użyj PublishAndWait, gdy chcesz wywołania blokującego.

Broker odrzuca połączenie

Większość brokerów wymaga identyfikatora klienta i poświadczeń. Ustaw je w Authentication i użyj OnMQTTBeforeConnect, gdy musisz obliczyć identyfikator klienta w momencie łączenia.

Zgłęb temat

Poza pierwszym tematem

Ten sam dwukomponentowy kształt obsługuje każdy inny protokół w pakiecie.

Właściwości MQTT 5.0

Ustaw MQTTVersion, a obiekty właściwości żądań i odpowiedzi stają się dostępne. Udostępnione są właściwości użytkownika, identyfikatory subskrypcji, aliasy tematów i kody przyczyn.

Dokumentacja MQTT

AMQP, obie wersje

Dwóch osobnych klientów: 0.9.1 dla wymian i kolejek w stylu RabbitMQ oraz 1.0 dla nowszego protokołu sieciowego. Oba podłączają się do klienta tak samo jak MQTT.

Dokumentacja AMQP 0.9.1 i dokumentacja AMQP 1.0

Kafka i STOMP

Natywny klient protokołu sieciowego Kafka oraz STOMP od 1.0 do 1.2 z wariantami dla konkretnych brokerów RabbitMQ i ActiveMQ.

STOMP dla RabbitMQ i STOMP dla ActiveMQ

Rozmawiaj z brokerem w chmurze

AWS IoT i Azure IoT obie mówią MQTT, a biblioteka zawiera dedykowane komponenty, które obsługują ich podpisywanie i uwierzytelnianie za ciebie.

Dokumentacja AWS IoT i dokumentacja Azure IoT

Zasoby

Dokumentacja, dema i materiały

Strony referencyjne opisują każdą właściwość i zdarzenie. Projekty demo znajdują się w pobranym pakiecie, w Demos\02.WebSocket_Protocols.

Dokumentacja, klient MQTT Każda metoda, właściwość i zdarzenie TsgcWSPClient_MQTT. Otwórz
Dokumentacja, AMQP 0.9.1 Wymiany, kolejki, powiązania i konsumenci. Otwórz
Dokumentacja, AMQP 1.0 Łącza, sesje i model wiadomości 1.0. Otwórz
Strona komponentu TsgcWSPClient_MQTT Klient MQTT w całości, z odnośnikami do pozostałych sześciu klientów protokołów. Otwórz
Przegląd protokołów Jak komponenty podprotokołów podłączają się do klienta lub serwera. Otwórz
Pomoc online Generowana dokumentacja, zawsze zgodna z bieżącym wydaniem. Otwórz

Powiązane lektury: publikowanie i oczekiwanie na potwierdzenie, wymiany i kolejki AMQP oraz klient Kafka. Każdy produkt ma własny szybki start, wymieniony na stronie pierwszych kroków.

FAQ

Pytania o szybki start sgcMQ

Ponieważ protokół i transport to osobne zagadnienia, a to pozwala temu samemu klientowi MQTT działać przez zwykły TCP lub przez WebSockety bez zmiany twojego kodu. TsgcWSPClient_MQTT koduje i dekoduje pakiety MQTT. TsgcWebSocketClient lub TsgcTCPClient zarządza gniazdem, hostem, portem i ustawieniami TLS. Jedno przypisanie je łączy: MQTT.Client := WSClient;.
Ustaw Active := True na komponencie klienta, a nie na protokole. Dostarczane demo robi dokładnie to. Protokół ma także metodę Connect, ale demo jej nie używa, a ustawianie Active to ścieżka, którą podąża każdy przykład.
SGC_MQTT jest zdefiniowany w linii 717 pliku sgcVer.inc, wewnątrz bloku SGC_EDT_STD, który biegnie od linii 675 do linii 724. To edycja Standard, najniższy płatny poziom, a bloki są kumulatywne, więc każda wyższa edycja też go ma. STOMP w linii 716, AMQP w 718, AMQP 1.0 w 719 i Kafka w 720 są w tym samym bloku. Żaden z protokołów komunikatów nie jest funkcją Enterprise.
OnMQTTPublish, którego sygnatura to procedure(Connection: TsgcWSConnection; aTopic, aText: String; PublishProperties: TsgcWSMQTTPUBLISHProperties). Zdarzenie o nazwie OnMQTTMessage nie istnieje. Gdy potrzebujesz surowych bajtów lub całego obiektu wiadomości zamiast tekstu, obsłuż zamiast tego OnMQTTPublishEx.
Publish zwraca Word, czyli identyfikator pakietu. Dostarczenie jest potwierdzane asynchronicznie: przy QoS 1 w OnMQTTPubAck, przy QoS 2 przez OnMQTTPubRec, OnMQTTPubRel i OnMQTTPubComp. Jeśli chcesz wywołania, które blokuje do potwierdzenia przez brokera, użyj PublishAndWait, które zwraca Boolean i przyjmuje limit czasu domyślnie równy dziesięciu sekundom.
Trzecim parametrem Publish jest TmqttQoS, zadeklarowany w sgcWebSocket_Types.pas z elementami mtqsAtMostOnce, mtqsAtLeastOnce, mtqsExactlyOnce i mtqsReserved. Domyślnie jest to mtqsAtMostOnce. Subscribe przyjmuje ten sam typ jako drugi parametr.
Tak. sgcWebSocket_Protocol_MQTT_Client.pas nie ma warunku platformy na poziomie jednostki, jedynym warunkiem w jego klauzuli uses jest import Windows, a komponent palety jest zarejestrowany z ComponentPlatforms(0), więc IDE nie ogranicza jego platform docelowych.
Tak. Ustaw MQTTVersion na komponencie protokołu. Wtedy w grę wchodzą obiekty właściwości 5.0: ConnectProperties w drodze na zewnątrz oraz parametr właściwości w każdym zdarzeniu w drodze powrotnej, na przykład TsgcWSMQTTCONNACKProperties w OnMQTTConnect i TsgcWSMQTTPUBLISHProperties w OnMQTTPublish.
Najkorzystniejsza oferta: All-AccessWszystkie produkty eSeGeCe, ze wsparciem Premium w cenie, już od €1,059 rocznie.
Zobacz cennik All-Access

Gotowy postawić brokera za swoją aplikacją?

Pobierz wersję próbną i uruchom demo MQTT na publicznym brokerze testowym.

Pobierz bezpłatną wersję próbną Zobacz cennik