Partilhar via

Guia de início rápido: publicar e assinar mensagens MQTT em um namespace de Grade de Eventos com a CLI do Azure

  • Artigo

O recurso de agente MQTT da Grade de Eventos do Azure dá suporte a mensagens usando o protocolo MQTT. Os clientes (dispositivos e aplicativos em nuvem) podem publicar e assinar mensagens MQTT em tópicos hierárquicos flexíveis para cenários como transmissão em alta escala e comando e controle.

Neste artigo, você usa a CLI do Azure para:

  • Crie um namespace Event Grid e habilite o broker MQTT.
  • Crie subrecursos como clientes, grupos de clientes e espaços de tópicos.
  • Conceda aos clientes acesso para publicar e assinar espaços temáticos.
  • Publique e receba mensagens MQTT.

Se não tiver uma subscrição do Azure, crie uma conta gratuita do Azure antes de começar.

Pré-requisitos

  • Se você é novo na Grade de Eventos, leia 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. O exemplo neste tutorial usa o protocolo MQTT, que se comunica pela porta 8883. Essa porta pode estar bloqueada em alguns ambientes de rede corporativa e educacional.
  • Use o ambiente Bash no Azure Cloud Shell. Para obter mais informações, consulte Guia de início rápido para Bash no Azure Cloud Shell.
  • Se preferir executar comandos de referência da CLI localmente, instale a CLI do Azure. Se você estiver executando 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 você estiver usando uma instalação local, entre na CLI do Azure usando o az login comando. Para concluir o processo de autenticação, siga os passos que aparecem no seu terminal. Para outras opções de entrada, consulte Entrar com a CLI do Azure.
  • Quando solicitado, instale a extensão da CLI do Azure na primeira utilização. Para obter mais informações sobre as extensões, veja Utilizar extensões com o CLI do Azure.
  • Execute o comando az version para localizar a versão e as bibliotecas dependentes instaladas. Para atualizar para a versão mais recente, execute o comando az upgrade.
  • Este artigo requer a versão 2.53.1 ou posterior da CLI do Azure. Se você estiver usando o Azure Cloud Shell, a versão mais recente já está instalada.
  • Você precisa de um certificado de cliente X.509 para gerar a impressão digital e autenticar a conexão do cliente.
  • Analise a documentação da CLI do namespace Event Grid.

Gerar um certificado de cliente de exemplo e impressão digital

Se você ainda não tiver um certificado, poderá criar um certificado de exemplo usando a etapa CLI. Considere instalar manualmente para Windows.

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

  1. Para criar certificados raiz e intermediários, execute o seguinte comando. 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. Use os arquivos de autoridade de certificação (CA) gerados para criar um certificado para o cliente. Certifique-se de usar o caminho correto para os arquivos cert e secrets 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 visualizar a impressão digital, execute o comando step.

    step certificate fingerprint client1-authnID.pem

Criar um espaço de nomes

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

az eventgrid namespace create -g {Resource Group} -n {Namespace Name} --topic-spaces-configuration "{state:Enabled}"

Para manter o início rápido simples, crie um namespace com propriedades mínimas. Para obter etapas detalhadas sobre como configurar a rede, a segurança e outras configurações em outras páginas do assistente, consulte Criar e gerenciar namespaces.

Criar clientes

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

az eventgrid namespace client create -g {Resource Group} --namespace-name {Namespace Name} -n {Client Name} --authentication-name client1-authnID --client-certificate-authentication "{validationScheme:ThumbprintMatch,allowed-thumbprints:[Client Thumbprint]}"
  • Para manter o 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 de CA X.509 para autenticação de cliente, consulte Autenticação de cliente usando cadeia de certificados.
  • Para este exercício, usamos 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ópico

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

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

Criar associações de permissão

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

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

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

az eventgrid namespace permission-binding create -g {Resource Group} --namespace-name {Namespace Name} -n {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 editor .NET simples que tenta se conectar e publicar em um namespace e se inscreve no tópico MQTT. Você pode usar o código para modificar de acordo com sua exigência e executar o código no Visual Studio ou em qualquer uma de suas ferramentas favoritas.

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 Gerencie pacotes NuGet e pesquise MQTTnet. Selecione o pacote MQTTnet e instale.)

Nota

O código de exemplo a seguir é apenas para fins de demonstração e não se destina ao uso em produção.

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

Importante

Atualize o certificado do cliente e os caminhos do arquivo pem de chave, dependendo do local dos arquivos de certificado do cliente. Além disso, certifique-se de que o nome de autenticação do cliente e as informações de tópico correspondam à sua configuração.

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 publicarem e assinarem entre os clientes.

Próximos passos