sgcMQ em cinco minutos

Sete clientes de mensageria nativos acompanham este pacote. O MQTT é o caminho mais curto até algo funcionando, então é isso que esta página faz: conectar-se a um broker, assinar um tópico, publicar uma mensagem e vê-la voltar. AMQP, Kafka e STOMP seguem o mesmo formato de dois componentes.

MQTT 3.1.1 e 5.0, AMQP 0.9.1 e 1.0, Kafka, STOMP
Sem biblioteca externa e sem DLL
Edição Standard e superiores
Visão geral

Dois componentes, não um

Esta é a parte que confunde as pessoas. O componente de protocolo fala MQTT; um componente cliente separado é dono do socket. Você os conecta com uma única atribuição.

O componente de protocolo

TsgcWSPClient_MQTT na página SGC MQ da paleta. Ele traz Connect, Subscribe, Publish, UnSubscribe e treze eventos MQTT.

O componente de transporte

TsgcWebSocketClient para MQTT sobre WebSockets, ou TsgcTCPClient para MQTT puro sobre TCP. Defina Host e Port neste.

A linha que os une

MQTT.Client := WSClient;. Depois disso, você abre a conexão definindo WSClient.Active := True, e não chamando um método do protocolo.

Plataformas

sgcWebSocket_Protocol_MQTT_Client.pas não tem restrição de plataforma, apenas um import condicional de Windows, e o componente é registrado com ComponentPlatforms(0). Todos os destinos compilam.

Antes de começar

Requisitos e edições

A coluna de edição é o define que controla cada protocolo, com a linha em que ele aparece em Source/sgcVer.inc.

O quê Valor
IDE Do Delphi 7 ao RAD Studio 13, e do C++Builder 2007 ao 13.
Cláusula uses sgcWebSocket_Protocols para TsgcWSPClient_MQTT, sgcWebSocket para o cliente, sgcWebSocket_Classes para TsgcWSConnection e sgcWebSocket_Types para TmqttQoS.
Edição do MQTT SGC_MQTT é definido na linha 717, dentro do bloco {$IFDEF SGC_EDT_STD} que vai da linha 675 à linha 724. Ou seja, Standard e superiores. Os blocos são cumulativos, então Professional, Enterprise e All-Access também o incluem.
Os outros protocolos Todos no mesmo bloco Standard: SGC_STOMP na linha 716, SGC_AMQP na 718, SGC_AMQP1 na 719, SGC_KAFKA na 720 e SGC_WAMP na 715. Nenhum deles é um recurso Enterprise.
Edição, pacote independente O produto sgcMQ define SGC_PACK_MQ na linha 855, e seu próprio bloco nas linhas 959 a 966 ativa os mesmos cinco defines de protocolo.
Plataformas Nenhuma restrição de plataforma no escopo da unit do cliente MQTT. A única condicional em sua cláusula uses é {$IFDEF MSWINDOWS}Windows, {$ENDIF}.

Quer um broker para testar sem instalar um? O demo MQTT que acompanha o pacote aponta para um broker de teste público em www.esegece.com, porta 15675 para MQTT sobre WebSockets.

Passo 1

Instale e encontre a página da paleta

O sgcMQ acompanha o instalador do sgcWebSockets e também como pacote próprio. A instalação é a mesma nos dois casos.

1. Descompacte

Descompacte o download em uma pasta, chamada de {$DIR} abaixo.

2. Caminho da biblioteca

Tools, Options, Library. Adicione {$DIR}\source e a pasta lib da sua IDE, por exemplo {$DIR}\libD13\$(Platform).

3. Compile os pacotes

Abra o grupo de pacotes da versão da sua IDE em {$DIR}\Packages\. Compile primeiro o .dpk de runtime e depois instale o de design-time, o dcl.

4. Confira a paleta

Aparece uma página chamada SGC MQ, com os clientes de protocolo que a sua edição habilita. Em uma compilação Standard e superiores, TsgcWSPClient_MQTT está lá.

5. Abra o demo

Abra {$DIR}\Demos\02.WebSocket_Protocols\08.MQTT_Client. É de onde vem o código abaixo, e ele já aponta para um broker de teste ativo.

QuickStart

Conectar, assinar, publicar

Ligue o protocolo a um cliente, abra a conexão, assine um tópico e publique nele. A mensagem volta em 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;

Para MQTT puro sobre TCP em vez de sobre WebSockets, crie um TsgcTCPClient de sgcTCP_Client_WS e aponte MQTT.Client para ele. Nada mais muda, e esse é o motivo de os dois componentes serem separados.

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 retorna um Word, o identificador do pacote, e não espera. PublishAndWait retorna um Boolean e bloqueia até o broker confirmar, com um timeout que por padrão é de dez segundos. TmqttQoS vem de 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;

Estes são os três que mais importam no início. Existem outros nove para o fluxo de confirmação, a desconexão e a autenticação do MQTT 5.0. Deixe a IDE gerar os manipuladores, porque as listas de parâmetros são longas e os objetos de propriedades diferem por evento.

As três abas vêm do demo que acompanha o pacote, Demos\02.WebSocket_Protocols\08.MQTT_Client\uClientMQTT.pas, com os controles do formulário substituídos por literais. O objeto MQTT é colocado no formulário nesse projeto; criá-lo em código funciona de forma idêntica.

Passo 2

Comprove a viagem de ida e volta

Dois eventos dizem que o broker aceitou você e que o tópico está ativo.

OnMQTTConnect

O broker aceitou a sessão. ReasonCode e ReasonName dizem por que não aceitou, o que é muito mais útil do que um socket derrubado.

OnMQTTSubscribe

A assinatura foi concedida. aCodes, um TsgcWSSUBACKS, traz a resposta do broker por tópico, então uma assinatura recusada fica visível em vez de silenciosa.

OnMQTTPublish

Uma mensagem chegou. Publique no tópico que você acabou de assinar e ela volta direto, o que comprova todo o caminho com um clique.

Os eventos de confirmação

Em QoS 1 e 2, a entrega é confirmada depois, em OnMQTTPubAck, OnMQTTPubRec, OnMQTTPubRel e OnMQTTPubComp. Se você precisa de uma chamada bloqueante, use PublishAndWait.

Problemas comuns

O que costuma dar errado na primeira vez

Seis problemas respondem por quase toda primeira conexão que falha.

Nada acontece quando você chama Subscribe

A conexão ainda não está aberta. O componente de protocolo não abre o socket; o cliente abre. Defina WSClient.Active := True e espere por OnMQTTConnect antes de assinar.

Violação de acesso na primeira chamada

MQTT.Client nunca foi atribuído. Essa linha é o que liga o protocolo a um transporte, e sem ela o protocolo não tem onde escrever.

Porta errada para o transporte errado

MQTT sobre WebSockets e MQTT sobre TCP puro usam portas diferentes na maioria dos brokers. 1883 e 8883 são as portas TCP usuais, enquanto o endpoint WebSocket fica em outro lugar completamente diferente. O demo que acompanha o pacote usa 15675 para WebSockets.

Você está procurando OnMQTTMessage

Esse evento não existe. As mensagens recebidas do broker chegam em OnMQTTPublish para texto e em OnMQTTPublishEx quando você quer o payload bruto e o objeto de mensagem completo.

QoS 1 e 2 parecem não ter feito nada

Elas são confirmadas de forma assíncrona. Publish retorna o identificador do pacote imediatamente; a confirmação chega depois em OnMQTTPubAck, OnMQTTPubRec, OnMQTTPubRel ou OnMQTTPubComp. Use PublishAndWait quando quiser uma chamada bloqueante.

O broker recusa a conexão

A maioria dos brokers quer um identificador de cliente e credenciais. Defina-os em Authentication e use OnMQTTBeforeConnect quando precisar calcular o identificador do cliente no momento da conexão.

Aprofunde-se

Além do primeiro tópico

O mesmo formato de dois componentes serve a todos os outros protocolos do pacote.

Propriedades do MQTT 5.0

Defina MQTTVersion e os objetos de propriedades de requisição e resposta ficam disponíveis. Propriedades de usuário, identificadores de assinatura, aliases de tópico e códigos de motivo são todos expostos.

Referência do MQTT

AMQP, as duas versões

Dois clientes separados, o 0.9.1 para exchanges e filas no estilo RabbitMQ e o 1.0 para o protocolo mais novo. Ambos se conectam a um cliente da mesma forma que o MQTT.

Referência do AMQP 0.9.1 e referência do AMQP 1.0

Kafka e STOMP

Um cliente nativo do protocolo Kafka e o STOMP 1.0 a 1.2, com variantes específicas de broker para RabbitMQ e ActiveMQ.

STOMP para RabbitMQ e STOMP para ActiveMQ

Converse com um broker na nuvem

AWS IoT e Azure IoT falam MQTT, e a biblioteca traz componentes dedicados que cuidam da assinatura e da autenticação para você.

Referência do AWS IoT e referência do Azure IoT

Recursos

Referência, demos e documentação

As páginas de referência documentam cada propriedade e evento. Os projetos de demo acompanham o download, em Demos\02.WebSocket_Protocols.

Referência, cliente MQTT Cada método, propriedade e evento de TsgcWSPClient_MQTT. Abrir
Referência, AMQP 0.9.1 Exchanges, filas, bindings e consumidores. Abrir
Referência, AMQP 1.0 Links, sessões e o modelo de mensagens do 1.0. Abrir
Página do componente TsgcWSPClient_MQTT O cliente MQTT completo, com os outros seis clientes de protocolo ligados a partir dela. Abrir
Visão geral dos protocolos Como os componentes de subprotocolo se conectam a um cliente ou a um servidor. Abrir
Ajuda online A referência gerada, sempre alinhada com a versão atual. Abrir

Leitura relacionada: publicar e esperar pela confirmação, exchanges e filas do AMQP e o cliente Kafka. Cada produto tem seu próprio início rápido, listado na página de primeiros passos.

FAQ

Perguntas sobre o início rápido do sgcMQ

Porque o protocolo e o transporte são preocupações separadas, e é isso que permite que o mesmo cliente MQTT rode sobre TCP puro ou sobre WebSockets sem mudar seu código. TsgcWSPClient_MQTT codifica e decodifica pacotes MQTT. TsgcWebSocketClient ou TsgcTCPClient é dono do socket, do host, da porta e das configurações de TLS. Uma atribuição os une: MQTT.Client := WSClient;.
Defina Active := True no componente cliente, não no protocolo. O demo que acompanha o pacote faz exatamente isso. Há também um método Connect no protocolo, mas o demo não o usa, e definir Active é o caminho que todo exemplo segue.
SGC_MQTT é definido na linha 717 de sgcVer.inc, dentro do bloco SGC_EDT_STD que vai da linha 675 à linha 724. Essa é a edição Standard, o nível pago mais baixo, e os blocos são cumulativos, então toda edição superior também o tem. STOMP na linha 716, AMQP na 718, AMQP 1.0 na 719 e Kafka na 720 estão todos no mesmo bloco. Nenhum dos protocolos de mensageria é um recurso Enterprise.
OnMQTTPublish, cuja assinatura é procedure(Connection: TsgcWSConnection; aTopic, aText: String; PublishProperties: TsgcWSMQTTPUBLISHProperties). Não existe um evento chamado OnMQTTMessage. Quando você precisa dos bytes brutos ou do objeto de mensagem completo em vez de uma string, trate OnMQTTPublishEx.
Publish retorna um Word, o identificador do pacote. A entrega é confirmada de forma assíncrona: em QoS 1 por OnMQTTPubAck, em QoS 2 por OnMQTTPubRec, OnMQTTPubRel e OnMQTTPubComp. Se você quer uma chamada que bloqueie até o broker confirmar, use PublishAndWait, que retorna um Boolean e recebe um timeout que por padrão é de dez segundos.
O terceiro parâmetro de Publish é um TmqttQoS, declarado em sgcWebSocket_Types.pas com os membros mtqsAtMostOnce, mtqsAtLeastOnce, mtqsExactlyOnce e mtqsReserved. O padrão é mtqsAtMostOnce. Subscribe recebe o mesmo tipo como segundo parâmetro.
Sim. sgcWebSocket_Protocol_MQTT_Client.pas não tem restrição de plataforma no escopo da unit, a única condicional em sua cláusula uses é o import de Windows, e o componente da paleta é registrado com ComponentPlatforms(0), então a IDE não restringe suas plataformas de destino.
Sim. Defina MQTTVersion no componente de protocolo. Os objetos de propriedades do 5.0 entram então em jogo: ConnectProperties na ida e o parâmetro de propriedades de cada evento na volta, por exemplo TsgcWSMQTTCONNACKProperties em OnMQTTConnect e TsgcWSMQTTPUBLISHProperties em OnMQTTPublish.
Melhor custo-benefício: All-AccessTodos os produtos da eSeGeCe, com Suporte Premium incluído, a partir de €1,059/ano.
Ver preços do All-Access

Pronto para colocar um broker por trás do seu aplicativo?

Baixe a versão de avaliação e execute o demo MQTT contra o broker de teste público.

Baixar avaliação gratuita Ver preços