Compartilhar via

Início Rápido: publicar e assinar mensagens MQTT em um namespace da 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 de nuvem) podem publicar e assinar mensagens MQTT em tópicos hierárquicos flexíveis para cenários como difusão em alta escala e controle e comando.

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

  • Criar um namespace da Grade de Eventos e habilitar o agente MQTT.
  • Criar sub-recursos como clientes, grupos de clientes e espaços de tópicos.
  • 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 não estiver familiarizado com a Grade de Eventos, leia a Visão geral da Grade de Eventos antes de começar 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.
  • Certifique-se de que a porta 8883 esteja aberta no seu firewall. A amostra deste tutorial usa o protocolo MQTT, que se comunica pela porta 8883. Essa porta pode ser bloqueada em alguns ambientes de rede corporativa e educacional.
  • Use o ambiente Bash no Azure Cloud Shell. Para obter mais informações, confira Início Rápido para Bash no Azure Cloud Shell.
  • Se preferir executar os comandos de referência da CLI localmente, instale a CLI do Azure. Para execuções no Windows ou no macOS, considere executar a CLI do Azure em um contêiner do Docker. Para saber mais, confira 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 são exibidas no terminal. Para ver outras opções de entrada, confira Conectar-se com 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, confira Usar extensões com a CLI do Azure.
  • Execute az version para localizar a versão e as bibliotecas dependentes que estão instaladas. Para fazer a atualização 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 a documentação 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 do step, abra um prompt de comando na pasta de perfil do usuário (pressione Win+R e digite %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 (AC) gerados para criar um certificado para o cliente. Certifique-se de usar o caminho correto para os arquivos de certificados 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 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 simplificar o início rápido, você cria um namespace com propriedades mínimas. Para ver etapas detalhadas sobre como definir as configurações de rede, de segurança e outras em outras páginas do assistente, confira 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 simplificar o início rápido, você usa a correspondência de impressão digital para autenticação. Para ver etapas sobre como usar a cadeia de certificados de CA X.509 para a autenticação do cliente, confira Autenticação do cliente usando a cadeia de certificados.
  • Para este exercício, usamos o grupo de clientes padrão $all client, que inclui todos os clientes do namespace. Para saber mais sobre como criar grupos de clientes personalizados usando atributos de cliente, confira Grupos de clientes.

Criar espaços de tópicos

Use o comando para criar o espaço de tópico. 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 -g {Resource Group} --namespace-name {Namespace Name} -n {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 um nome de 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 o grupo de recursos, o nome do namespace e um nome de associação de permissão. Essa associação de permissão se destina a 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 publicador .NET simples que tenta se conectar e publicar em um namespace e assina o tópico MQTT. Você pode usar o código para modificá-lo de acordo com suas necessidades e executá-o no Visual Studio ou em uma das 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, acesse Gerenciar pacotes NuGet e pesquise por MQTTnet. Selecione o pacote MQTTnet e instale-o.)

Observação

O código de exemplo a seguir destina-se apenas a fins de demonstração e não 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 de arquivo pem de chave, dependendo do local dos arquivos de certificado do cliente. Além disso, verifique se o nome da autenticação do cliente e as informações do tópico correspondem à 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óximas etapas