sgcMQ in cinque minuti

In questo pacchetto sono inclusi sette client di messaggistica nativi. MQTT è il percorso più breve per avere qualcosa in esecuzione, ed è quello che fa questa pagina: connettersi a un broker, sottoscrivere un topic, pubblicare un messaggio e vederlo tornare indietro. AMQP, Kafka e STOMP seguono la stessa struttura a due componenti.

MQTT 3.1.1 e 5.0, AMQP 0.9.1 e 1.0, Kafka, STOMP
Nessuna libreria esterna e nessuna DLL
Edizione Standard e superiori

Due componenti, non uno

È la parte su cui si inciampa. Il componente di protocollo parla MQTT; un componente client separato gestisce il socket. Li colleghi con una sola assegnazione.

Il componente di protocollo

TsgcWSPClient_MQTT nella pagina SGC MQ della palette. Contiene Connect, Subscribe, Publish, UnSubscribe e tredici eventi MQTT.

Il componente di trasporto

TsgcWebSocketClient per MQTT su WebSocket, oppure TsgcTCPClient per MQTT semplice su TCP. Imposta Host e Port su questo.

La riga che li unisce

MQTT.Client := WSClient;. Dopo di che apri la connessione impostando WSClient.Active := True, non chiamando un metodo sul protocollo.

Piattaforme

sgcWebSocket_Protocol_MQTT_Client.pas non ha guardie di piattaforma, solo un import condizionale di Windows, e il componente è registrato con ComponentPlatforms(0). Ogni target compila.

Requisiti ed edizioni

La colonna dell'edizione indica il define che regola ogni protocollo, con la riga in cui si trova in Source/sgcVer.inc.

Cosa Valore
IDE Da Delphi 7 a RAD Studio 13 e da C++Builder 2007 a 13.
Clausola uses sgcWebSocket_Protocols per TsgcWSPClient_MQTT, sgcWebSocket per il client, sgcWebSocket_Classes per TsgcWSConnection e sgcWebSocket_Types per TmqttQoS.
Edizione MQTT SGC_MQTT è definito alla riga 717, dentro il blocco {$IFDEF SGC_EDT_STD} che va dalla riga 675 alla riga 724. Quindi Standard e superiori. I blocchi sono cumulativi, quindi lo includono anche Professional, Enterprise e All-Access.
Gli altri protocolli Tutti nello stesso blocco Standard: SGC_STOMP alla riga 716, SGC_AMQP alla 718, SGC_AMQP1 alla 719, SGC_KAFKA alla 720 e SGC_WAMP alla 715. Nessuno di essi è una funzionalità Enterprise.
Edizione, pacchetto autonomo Il prodotto sgcMQ definisce SGC_PACK_MQ alla riga 855 e il suo blocco alle righe da 959 a 966 attiva gli stessi cinque define di protocollo.
Piattaforme Nessuna guardia di piattaforma a livello di unit nell'unit del client MQTT. L'unica condizione nella sua clausola uses è {$IFDEF MSWINDOWS}Windows, {$ENDIF}.

Vuoi un broker su cui provare senza installarne uno? La demo MQTT inclusa punta a un broker di test pubblico su www.esegece.com, porta 15675 per MQTT su WebSocket.

Installa e trova la pagina della palette

sgcMQ è incluso nell'installer di sgcWebSockets e anche come pacchetto a sé. L'installazione è la stessa in entrambi i casi.

1. Decomprimi

Decomprimi il download in una cartella, chiamata {$DIR} qui sotto.

2. Library path

Tools, Options, Library. Aggiungi {$DIR}\source e la cartella lib per il tuo IDE, per esempio {$DIR}\libD13\$(Platform).

3. Compila i package

Apri il gruppo di package per la versione del tuo IDE in {$DIR}\Packages\. Compila prima il .dpk di runtime, poi installa quello di design-time dcl.

4. Controlla la palette

Compare una pagina chiamata SGC MQ, con i client di protocollo abilitati dalla tua edizione. Da una build Standard in su, TsgcWSPClient_MQTT è presente.

5. Apri la demo

Apri {$DIR}\Demos\02.WebSocket_Protocols\08.MQTT_Client. È da qui che proviene il codice qui sotto ed è già configurata per un broker di test attivo.

Connetti, sottoscrivi, pubblica

Collega il protocollo a un client, apri la connessione, sottoscrivi un topic e pubblica su di esso. Il messaggio torna in 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;

Per MQTT semplice su TCP invece che su WebSocket, crea invece un TsgcTCPClient da sgcTCP_Client_WS e punta MQTT.Client a quello. Nient'altro cambia, ed è il motivo per cui i due componenti sono separati.

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 restituisce un Word, l'identificatore del pacchetto, e non attende. PublishAndWait restituisce un Boolean e si blocca finché il broker non conferma, con un timeout predefinito di dieci secondi. TmqttQoS proviene da 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;

Questi sono i tre che contano per primi. Ne esistono altri nove per il flusso di conferma, la disconnessione e l'autenticazione MQTT 5.0. Lascia che sia l'IDE a generare i gestori, perché gli elenchi di parametri sono lunghi e gli oggetti delle proprietà cambiano per ogni evento.

Tutte e tre le schede provengono dalla demo inclusa Demos\02.WebSocket_Protocols\08.MQTT_Client\uClientMQTT.pas, con i controlli del form sostituiti da valori letterali. L'oggetto MQTT è posizionato sul form in quel progetto; crearlo da codice funziona in modo identico.

Verifica lo scambio completo

Due eventi ti dicono che il broker ti ha accettato e che il topic è attivo.

OnMQTTConnect

Il broker ha accettato la sessione. ReasonCode e ReasonName ti dicono il perché quando non l'ha fatto, il che è molto più utile di un socket caduto.

OnMQTTSubscribe

La sottoscrizione è stata concessa. aCodes, un TsgcWSSUBACKS, contiene la risposta del broker per ogni topic, quindi una sottoscrizione rifiutata è visibile e non silenziosa.

OnMQTTPublish

È arrivato un messaggio. Pubblica sul topic che hai appena sottoscritto e torna subito indietro, il che dimostra l'intero percorso con un clic.

Gli eventi di conferma

A QoS 1 e 2 la consegna viene confermata più tardi, in OnMQTTPubAck, OnMQTTPubRec, OnMQTTPubRel e OnMQTTPubComp. Se ti serve invece una chiamata bloccante, usa PublishAndWait.

Cosa va storto di solito la prima volta

Sei problemi spiegano quasi ogni prima connessione fallita.

Non succede nulla quando chiami Subscribe

La connessione non è ancora aperta. Il componente di protocollo non apre il socket; lo fa il client. Imposta WSClient.Active := True e attendi OnMQTTConnect prima di sottoscrivere.

Access violation alla prima chiamata

MQTT.Client non è mai stato assegnato. Quella riga è ciò che lega il protocollo a un trasporto e, senza di essa, il protocollo non ha dove scrivere.

Porta sbagliata per il trasporto sbagliato

MQTT su WebSocket e MQTT su TCP semplice usano porte diverse sulla maggior parte dei broker. 1883 e 8883 sono le solite porte TCP, mentre l'endpoint WebSocket è tutt'altrove. La demo inclusa usa la 15675 per WebSocket.

Stai cercando OnMQTTMessage

Non esiste un evento del genere. I messaggi in arrivo dal broker arrivano in OnMQTTPublish per il testo e in OnMQTTPublishEx quando vuoi il payload grezzo e l'oggetto messaggio completo.

QoS 1 e 2 sembrano non fare nulla

Vengono confermati in modo asincrono. Publish restituisce subito l'identificatore del pacchetto; la conferma arriva più tardi in OnMQTTPubAck, OnMQTTPubRec, OnMQTTPubRel o OnMQTTPubComp. Usa PublishAndWait quando vuoi una chiamata bloccante.

Il broker rifiuta la connessione

La maggior parte dei broker richiede un identificatore del client e delle credenziali. Impostali in Authentication e usa OnMQTTBeforeConnect quando devi calcolare l'identificatore del client al momento della connessione.

Oltre il primo topic

La stessa struttura a due componenti vale per ogni altro protocollo del pacchetto.

Proprietà di MQTT 5.0

Imposta MQTTVersion e gli oggetti delle proprietà di richiesta e risposta diventano disponibili. Proprietà utente, identificatori di sottoscrizione, alias dei topic e reason code sono tutti esposti.

Riferimento di MQTT

AMQP, entrambe le versioni

Due client separati, 0.9.1 per exchange e code in stile RabbitMQ e 1.0 per il protocollo wire più recente. Entrambi si collegano a un client come fa MQTT.

Riferimento di AMQP 0.9.1 e riferimento di AMQP 1.0

Kafka e STOMP

Un client nativo per il protocollo wire di Kafka e STOMP da 1.0 a 1.2 con varianti specifiche per broker, RabbitMQ e ActiveMQ.

STOMP per RabbitMQ e STOMP per ActiveMQ

Dialoga con un broker cloud

AWS IoT e Azure IoT parlano entrambi MQTT e la libreria include componenti dedicati che gestiscono per te la firma e l'autenticazione.

Riferimento di AWS IoT e riferimento di Azure IoT

Riferimento, demo e documentazione

Le pagine di riferimento documentano ogni proprietà ed evento. I progetti demo sono inclusi nel download, in Demos\02.WebSocket_Protocols.

Riferimento, client MQTT Ogni metodo, proprietà ed evento di TsgcWSPClient_MQTT.
Riferimento, AMQP 0.9.1 Exchange, code, binding e consumer.
Riferimento, AMQP 1.0 Link, sessioni e il modello di messaggio 1.0.
Pagina del componente TsgcWSPClient_MQTT Il client MQTT per intero, con gli altri sei client di protocollo collegati da lì.
Panoramica dei protocolli Come i componenti dei sotto-protocolli si collegano a un client o a un server.
Guida online Il riferimento generato, sempre allineato alla versione corrente.

Letture correlate: pubblicare e attendere la conferma, exchange e code AMQP e il client Kafka. Ogni prodotto ha la propria guida rapida, elencata nella pagina per iniziare.

Domande sulla guida rapida di sgcMQ

Perché il protocollo e il trasporto sono responsabilità separate, ed è ciò che permette allo stesso client MQTT di funzionare su TCP semplice o su WebSocket senza cambiare il tuo codice. TsgcWSPClient_MQTT codifica e decodifica i pacchetti MQTT. TsgcWebSocketClient o TsgcTCPClient gestisce il socket, l'host, la porta e le impostazioni TLS. Una sola assegnazione li unisce: MQTT.Client := WSClient;.
Imposta Active := True sul componente client, non sul protocollo. La demo inclusa fa esattamente questo. Esiste anche un metodo Connect sul protocollo, ma la demo non lo usa e impostare Active è il percorso seguito da ogni esempio.
SGC_MQTT è definito alla riga 717 di sgcVer.inc, dentro il blocco SGC_EDT_STD che va dalla riga 675 alla riga 724. È l'edizione Standard, il livello a pagamento più basso, e i blocchi sono cumulativi, quindi lo hanno anche tutte le edizioni superiori. STOMP alla riga 716, AMQP alla 718, AMQP 1.0 alla 719 e Kafka alla 720 sono tutti nello stesso blocco. Nessuno dei protocolli di messaggistica è una funzionalità Enterprise.
OnMQTTPublish, la cui firma è procedure(Connection: TsgcWSConnection; aTopic, aText: String; PublishProperties: TsgcWSMQTTPUBLISHProperties). Non esiste un evento chiamato OnMQTTMessage. Quando ti servono i byte grezzi o l'intero oggetto messaggio invece di una stringa, gestisci invece OnMQTTPublishEx.
Publish restituisce un Word, l'identificatore del pacchetto. La consegna viene confermata in modo asincrono: a QoS 1 in OnMQTTPubAck, a QoS 2 tramite OnMQTTPubRec, OnMQTTPubRel e OnMQTTPubComp. Se vuoi una chiamata che si blocca finché il broker non conferma, usa PublishAndWait, che restituisce un Boolean e accetta un timeout predefinito di dieci secondi.
Il terzo parametro di Publish è un TmqttQoS, dichiarato in sgcWebSocket_Types.pas con i membri mtqsAtMostOnce, mtqsAtLeastOnce, mtqsExactlyOnce e mtqsReserved. Il valore predefinito è mtqsAtMostOnce. Subscribe accetta lo stesso tipo come secondo parametro.
Sì. sgcWebSocket_Protocol_MQTT_Client.pas non ha guardie di piattaforma a livello di unit, l'unica condizione nella sua clausola uses è l'import di Windows e il componente della palette è registrato con ComponentPlatforms(0), quindi l'IDE non ne limita le piattaforme di destinazione.
Sì. Imposta MQTTVersion sul componente di protocollo. Entrano quindi in gioco gli oggetti delle proprietà 5.0: ConnectProperties in uscita e il parametro delle proprietà di ogni evento in ritorno, per esempio TsgcWSMQTTCONNACKProperties in OnMQTTConnect e TsgcWSMQTTPUBLISHProperties in OnMQTTPublish.
La scelta più conveniente: All-AccessTutti i prodotti eSeGeCe, con Supporto Premium incluso, a partire da €1,059/anno.
Vedi i prezzi All-Access

Pronto a mettere un broker dietro la tua applicazione?

Scarica la versione di prova ed esegui la demo MQTT sul broker di test pubblico.