Início Rápido: Publicar e assinar mensagens MQTT em um namespace da Grade de Eventos com a CLI do Azure

Neste início rápido, você usará o recurso do agente MQTT da Grade de Eventos do Azure para dar suporte a mensagens usando o protocolo MQTT. Os clientes, incluindo dispositivos e aplicativos de nuvem, podem publicar e assinar mensagens MQTT sobre tópicos hierárquicos flexíveis para cenários como difusão em alta escala e comando e controle.

Neste artigo, você usará a CLI do Azure para:

• Crie um namespace do Event Grid e habilite o broker MQTT.
• Crie subrecursos, como clientes, grupos de clientes e espaços de tópico.
• Permitir aos clientes acesso para publicação e assinatura em espaços de tópicos.
• Publicar e receber mensagens MQTT.

Caso você não tenha uma assinatura do Azure, crie uma conta gratuita do Azure antes de começar.

Pré-requisitos

• Se você não estiver familiarizado com a Grade de Eventos, consulte a visão geral da Grade de Eventos antes de iniciar este tutorial.
• Registre o provedor de recursos da Grade de Eventos de acordo com as etapas em Registrar o provedor de recursos da Grade de Eventos.
• Verifique se a porta 8883 está aberta no firewall. Este tutorial usa o protocolo MQTT, que se comunica pela porta 8883. Essa porta pode ser bloqueada em alguns ambientes de rede corporativa e educacional.
• Utilize o ambiente Bash no Azure Cloud Shell. Para obter mais informações, confira Introdução ao Azure Cloud Shell.
• Se preferir executar os comandos de referência da CLI localmente, instale a CLI do Azure. Se você executar no Windows ou macOS, considere executar a CLI do Azure em um contêiner do Docker. Para obter mais informações, consulte Executar a CLI do Azure em um contêiner do Docker.
• Se estiver usando uma instalação local, entre com a CLI do Azure usando o comando az login. Para concluir o processo de autenticação, siga as etapas que aparecem no terminal. Para obter outras opções de entrada, consulte Autenticar no Azure usando a CLI do Azure.
• Quando solicitado, instale a extensão da CLI do Azure no primeiro uso. Para obter mais informações sobre extensões, consulte Gerenciar extensões da CLI do Azure.
• Execute o comando az version para localizar a versão e as bibliotecas dependentes que estão instaladas. Para atualizar para a versão mais recente, execute az upgrade.
• Este artigo requer a versão 2.53.1 ou posterior da CLI do Azure. Se você está usando o Azure Cloud Shell, a última versão já está instalada.
• Você precisa ter um certificado de cliente X.509 para gerar a impressão digital e autenticar a conexão do cliente.
• Examine os comandos da CLI do namespace da Grade de Eventos.

Gerar uma amostra de certificado do cliente e impressão digital

Caso ainda não tenha um certificado, você pode criar uma amostra de certificado usando a CLI do step. Considere a possibilidade de instalação manual para o Windows.

Após uma instalação bem-sucedida usando a CLI da etapa, abra uma janela do prompt de comando na pasta de perfil do usuário (Win+R type %USERPROFILE%).

1. Para criar certificados raiz e intermediários, execute o comando a seguir. Lembre-se da senha, que você precisa usar na próxima etapa.

   step ca init --deployment-type standalone --name MqttAppSamplesCA --dns localhost --address 127.0.0.1:443 --provisioner MqttAppSamplesCAProvisioner
   

2. Para criar um certificado para o cliente, use os arquivos de autoridade de certificação (AC) gerados. Certifique-se de usar o caminho correto para os arquivos de certificado e segredos no comando.

   step certificate create client1-authnID client1-authnID.pem client1-authnID.key --ca .step/certs/intermediate_ca.crt --ca-key .step/secrets/intermediate_ca_key --no-password --insecure --not-after 2400h
   

3. Para ver a impressão digital, execute o comando step.

   step certificate fingerprint client1-authnID.pem
   

Criar um namespace

Use este comando para criar um namespace. Atualize o comando com seu grupo de recursos e um nome de namespace.

az eventgrid namespace create --resource-group {Resource Group} --name {Namespace Name} --topic-spaces-configuration "{state:Enabled}"

Para manter este início rápido simples, crie um namespace com propriedades mínimas. Para obter mais informações sobre rede, segurança e configurações em outras guias, consulte Criar e gerenciar namespaces.

Criar clientes

Use este comando para criar o cliente. Atualize o comando com seu grupo de recursos e um nome de namespace.

az eventgrid namespace client create --resource-group {Resource Group} --namespace-name {Namespace Name} --name {Client Name} --authentication-name client1-authnID --client-certificate-authentication "{validationScheme:ThumbprintMatch,allowed-thumbprints:[Client Thumbprint]}"

• Para manter este início rápido simples, use a correspondência de impressão digital para autenticação. Para obter etapas sobre como usar a cadeia de certificados da autoridade certificadora X.509 para autenticação de cliente, consulte autenticação de cliente usando cadeia de certificados.
• Para este exercício, use o grupo padrão $all client , que inclui todos os clientes no namespace. Para saber mais sobre como criar grupos de clientes personalizados usando atributos de cliente, consulte grupos de clientes.

Criar espaços de tópicos

Use este comando para criar o espaço de tópicos. Atualize o comando com o grupo de recursos, o nome do namespace e um nome de espaço de tópico.

az eventgrid namespace topic-space create --resource-group {Resource Group} --namespace-name {Namespace Name} --name {Topicspace Name} --topic-templates ['contosotopics/topic1']

Criar associações de permissão

Use o comando az eventgrid para criar a primeira associação de permissão para a permissão do publicador. Atualize o comando com o grupo de recursos, o nome do namespace e o nome da associação de permissão.

az eventgrid namespace permission-binding create --resource-group {Resource Group} --namespace-name {Namespace Name} --name {Permission Binding Name} --client-group-name '$all' --permission publisher --topic-space-name {Topicspace Name}

Use este comando para criar a segunda associação de permissão. Atualize o comando com o grupo de recursos, o nome do namespace e o nome da associação de permissão. Esta vinculação de permissão é para assinantes.

az eventgrid namespace permission-binding create --resource-group {Resource Group} --namespace-name {Namespace Name} --name {Name of second Permission Binding} --client-group-name '$all' --permission subscriber --topic-space-name {Topicspace Name}

Publicar e assinar mensagens MQTT

O código de exemplo a seguir é um publicador .NET simples que tenta se conectar e publicar em um namespace e se inscreve no tópico MQTT. Você pode modificar o código para seus requisitos e executá-lo no Visual Studio ou em outra ferramenta de design.

Você precisa instalar o pacote MQTTnet (versão 4.1.4.563) do NuGet para executar esse código. No Visual Studio, clique com o botão direito do mouse no nome do projeto no Gerenciador de Soluções, vá para Gerenciar pacotes NuGet e pesquise por MQTTnet. Selecione o pacote MQTTnet e instale.

Código C# de exemplo para conectar um cliente, publicar e assinar uma mensagem MQTT em um tópico

using MQTTnet.Client;
using MQTTnet;
using System.Security.Cryptography.X509Certificates;

string hostname = "{Your Event Grid namespace MQTT hostname}";
string clientId = "client1-session1";  //client ID can be the session identifier.  A client can have multiple sessions using username and clientId.
string x509_pem = @" client certificate cer.pem file path\client.cer.pem";  //Provide your client certificate .cer.pem file path
string x509_key = @"client certificate key.pem file path\client.key.pem";  //Provide your client certificate .key.pem file path

var certificate = new X509Certificate2(X509Certificate2.CreateFromPemFile(x509_pem, x509_key).Export(X509ContentType.Pkcs12));

var mqttClient = new MqttFactory().CreateMqttClient();

var connAck = await mqttClient!.ConnectAsync(new MqttClientOptionsBuilder()
    .WithTcpServer(hostname, 8883)
    .WithClientId(clientId)
    .WithCredentials("client1-authnID", "")  //use client authentication name in the username
    .WithTls(new MqttClientOptionsBuilderTlsParameters()
    {
        UseTls = true,
        Certificates = new X509Certificate2Collection(certificate)
    })

    .Build());

Console.WriteLine($"Client Connected: {mqttClient.IsConnected} with CONNACK: {connAck.ResultCode}");

mqttClient.ApplicationMessageReceivedAsync += async m => await Console.Out.WriteAsync($"Received message on topic: '{m.ApplicationMessage.Topic}' with content: '{m.ApplicationMessage.ConvertPayloadToString()}'\n\n");

var suback = await mqttClient.SubscribeAsync("contosotopics/topic1");
suback.Items.ToList().ForEach(s => Console.WriteLine($"subscribed to '{s.TopicFilter.Topic}' with '{s.ResultCode}'"));

while (true)
{
    var puback = await mqttClient.PublishStringAsync("contosotopics/topic1", "hello world!");
    Console.WriteLine(puback.ReasonString);
    await Task.Delay(1000);
}

Você pode replicar e modificar o mesmo código para vários clientes, para que os clientes possam publicar e assinar conteúdo entre si.

Conteúdo relacionado

• Tutorial: Encaminhar mensagens MQTT para Hubs de Eventos do Azure usando tópicos de namespace
• Tutorial: Encaminhar mensagens MQTT para Azure Functions usando tópicos personalizados

Para obter amostras de código, acesse esse repositório do GitHub.