Tutorial: ponte MQTT bidirecional para a Grade de Eventos do Azure

  • Artigo

Importante

A Versão Prévia das Operações da Internet das Coisas do Azure – habilitadas pelo Azure Arc – está atualmente em versão prévia. Você não deve usar esse software em versão prévia em ambientes de produção.

Você precisará implantar uma nova instalação das Operações da Internet das Coisas do Azure quando uma versão em disponibilidade geral for disponibilizada. Você não poderá atualizar uma instalação de versão prévia.

Veja os Termos de Uso Complementares para Versões Prévias do Microsoft Azure para obter termos legais que se aplicam aos recursos do Azure que estão em versão beta, versão prévia ou que, de outra forma, ainda não foram lançados em disponibilidade geral.

Neste tutorial, você configurará uma ponte MQTT bidirecional entre um agente MQTT de Operações do Azure IoT e a Grade de Eventos do Azure. Para manter o tutorial simples, use as configurações padrão para o agente MQTT de Operações do Azure IoT e os pontos de extremidade da Grade de Eventos do Azure e nenhuma transformação é aplicada.

Pré-requisitos

Definir variáveis de ambiente

Entre com a CLI do Azure:

az login

Defina as variáveis de ambiente para o restante da configuração. Substitua valores em <> por valores ou nomes válidos de sua escolha. Um novo namespace da Grade de Eventos do Azure e um espaço de tópico são criados em sua assinatura do Azure com base nos nomes que você fornece:

# For this tutorial, the steps assume the IoT Operations cluster and the Event Grid
# are in the same subscription, resource group, and location.

# Name of the resource group of Azure Event Grid and IoT Operations cluster 
export RESOURCE_GROUP=<RESOURCE_GROUP_NAME>

# Azure region of Azure Event Grid and IoT Operations cluster
export LOCATION=<LOCATION>

# Name of the Azure Event Grid namespace
export EVENT_GRID_NAMESPACE=<EVENT_GRID_NAMESPACE>

# Name of the Arc-enabled IoT Operations cluster 
export CLUSTER_NAME=<CLUSTER_NAME>

# Subscription ID of Azure Event Grid and IoT Operations cluster
export SUBSCRIPTION_ID=<SUBSCRIPTION_ID>

Criar namespace da Grade de Eventos com o agente MQTT habilitado

Crie o namespace da Grade de Eventos com a CLI do Azure. O local deve ser o mesmo que você usou para implantar operações de IoT do Azure.

az eventgrid namespace create \
  --namespace-name $EVENT_GRID_NAMESPACE \
  --resource-group $RESOURCE_GROUP \
  --location $LOCATION \
  --topic-spaces-configuration "{state:Enabled,maximumClientSessionsPerAuthenticationName:3}"

Ao definir o topic-spaces-configuration, este comando cria um namespace com:

  • Agente MQTT habilitado
  • Máximo de sessões de cliente por nome de autenticação como 3.

A opção máximo de sessões de cliente permite que o MQTT das Operações do Azure IoT gere várias instâncias e ainda se conecte. Para saber mais, confira suporte a várias sessões.

Criar um espaço de tópico

No namespace da Grade de Eventos, crie um espaço de tópico nomeado tutorial com um modelo de tópico telemetry/#.

az eventgrid namespace topic-space create \
  --resource-group $RESOURCE_GROUP \
  --namespace-name $EVENT_GRID_NAMESPACE \
  --name tutorial \
  --topic-templates "telemetry/#"

Usando o curinga # no modelo de tópico, você pode publicar em qualquer tópico no espaço do tópico telemetry. Por exemplo, telemetry/temperature ou telemetry/humidity.

Permita às Operações do Azure IoT acesso ao espaço de tópico da Grade de Eventos

Usando a CLI do Azure, localize a ID da entidade de segurança para a extensão do Arc das Operações do Azure IoT. O comando armazena a ID da entidade de segurança em uma variável para uso posterior.

export PRINCIPAL_ID=$(az k8s-extension list \
  --resource-group $RESOURCE_GROUP \
  --cluster-name $CLUSTER_NAME \
  --cluster-type connectedClusters \
  --query "[?extensionType=='microsoft.iotoperations'].identity.principalId | [0]" -o tsv)
echo $PRINCIPAL_ID

Anote o valor de saída para identity.principalId, que é um valor GUID com o seguinte formato:

d84481ae-9181-xxxx-xxxx-xxxxxxxxxxxx

Em seguida, use a CLI do Azure para atribuir funções de editor e assinante ao MQTT das Operações do Azure IoT para o espaço de tópico que você criou.

Atribua a função de editor:

az role assignment create \
  --assignee $PRINCIPAL_ID \
  --role "EventGrid TopicSpaces Publisher" \
  --scope /subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.EventGrid/namespaces/$EVENT_GRID_NAMESPACE/topicSpaces/tutorial

Atribua a função de assinante:

az role assignment create \
  --assignee $PRINCIPAL_ID \
  --role "EventGrid TopicSpaces Subscriber" \
  --scope /subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.EventGrid/namespaces/$EVENT_GRID_NAMESPACE/topicSpaces/tutorial

Dica

O escopo corresponde ao id do espaço de tópico que você criou com az eventgrid namespace topic-space create na etapa anterior e você pode encontrá-lo na saída do comando.

Nome do host do agente MQTT da Grade de Eventos

Use a CLI do Azure para obter o nome de host do agente MQTT da Grade de Eventos.

az eventgrid namespace show \
  --resource-group $RESOURCE_GROUP \
  --namespace-name $EVENT_GRID_NAMESPACE \
  --query topicSpacesConfiguration.hostname \
  -o tsv

Anote o valor de saída para topicSpacesConfiguration.hostname esse é um valor de nome de host semelhante a:

example.region-1.ts.eventgrid.azure.net

Entenda o ponto de extremidade padrão de fluxo de dados do agente MQTT de Operações do Azure IoT

Por padrão, o recurso Operações do Azure IoT implanta um agente MQTT e também um ponto de extremidade de fluxo de dados do agente MQTT. O ponto de extremidade de fluxo de dados do agente MQTT é usado para a conexão com o agente MQTT. A configuração padrão usa o token integrado da conta de serviço para autenticação. O ponto de extremidade é chamado default e está disponível no mesmo namespace das Operações do Azure IoT. O ponto de extremidade é usado como fonte dos fluxos de dados que você vai criar nas próximas etapas.

Para saber mais sobre o ponto de extremidade padrão de fluxo de dados do agente MQTT, confira Ponto de extremidade padrão do agente MQTT local das Operações do Azure IoT.

Criar um ponto de extremidade de fluxo de dados da Grade de Eventos do Azure

Crie um ponto de extremidade de fluxo de dados para a Grade de Eventos do Azure. Esse ponto de extremidade é o destino do fluxo de dados que envia mensagens para a Grade de Eventos do Azure. Substitua <EVENT_GRID_HOSTNAME> pelo nome do host MQTT que você obteve na etapa anterior. Inclua o número da porta 8883.

O fluxo de dados e a Grade de Eventos do Azure dos pontos de extremidade de fluxo de dados podem ser implantados como um recurso padrão do Azure, já que têm implementações de Provedor de Recursos (RPs) do Azure. Este arquivo de modelo Bicep do Tutorial de arquivo Bicep para fluxo de dados de ponte MQTT implanta o fluxo de dados e os pontos de extremidade de fluxo de dados necessários.

Baixe o arquivo em seu local e substitua os valores de customLocationName, aioInstanceName e eventGridHostName pelos seus.

param customLocationName string = '<CUSTOM_LOCATION_NAME>'
param aioInstanceName string = '<AIO_INSTANCE_NAME>'
param eventGridHostName string = '<EVENT_GRID_HOSTNAME>:8883'

resource customLocation 'Microsoft.ExtendedLocation/customLocations@2021-08-31-preview' existing = {
  name: customLocationName
}

resource aioInstance 'Microsoft.IoTOperations/instances@2024-09-15-preview' existing = {
  name: aioInstanceName
}
resource remoteMqttBrokerDataflowEndpoint 'Microsoft.IoTOperations/instances/dataflowEndpoints@2024-09-15-preview' = {
  parent: aioInstance
  name: 'eventgrid'
  extendedLocation: {
    name: customLocation.id
    type: 'CustomLocation'
  }
  properties: {
    endpointType: 'Mqtt'
    mqttSettings: {
      host: eventGridHostName
      authentication: {
        method: 'SystemAssignedManagedIdentity'
        systemAssignedManagedIdentitySettings: {}
      }
      tls: {
        mode: 'Enabled'
      }
    }
  }
}

Em seguida, execute o comando a seguir no seu terminal. Substitua <FILE> pelo nome do arquivo Bicep que você baixou.

az deployment group create --resource-group <RESOURCE_GROUP> --template-file <FILE>.bicep

Aqui, o método de autenticação está definido para SystemAssignedManagedIdentity para usar a identidade gerenciada da extensão de Operações do Azure IoT para autenticar com o agente MQTT da Grade de Eventos. Essa configuração funciona porque a extensão operações de IoT do Azure tem as permissões necessárias para publicar e assinar o espaço de tópico da Grade de Eventos configurado por meio de funções RBAC do Azure. Observe que nenhum segredo, como nome de usuário ou senha, é necessário na configuração.

Como o agente MQTT da Grade de Eventos requer TLS, a configuração tls está habilitada. Não é necessário fornecer um certificado de autoridade de certificação, pois o agente MQTT da Grade de Eventos usa uma autoridade de certificação amplamente confiável.

Criar fluxos de dados

Crie dois fluxos de dados com o ponto de extremidade do agente MQTT de Operações do Azure IoT como a origem e o ponto de extremidade da Grade de Eventos do Azure como o destino e vice-versa. Não é necessário configurar a transformação.

param customLocationName string = '<CUSTOM_LOCATION_NAME>'
param aioInstanceName string = '<AIO_INSTANCE_NAME>'

resource customLocation 'Microsoft.ExtendedLocation/customLocations@2021-08-31-preview' existing = {
  name: customLocationName
}
resource aioInstance 'Microsoft.IoTOperations/instances@2024-09-15-preview' existing = {
  name: aioInstanceName
}
resource defaultDataflowProfile 'Microsoft.IoTOperations/instances/dataflowProfiles@2024-09-15-preview' existing = {
  parent: aioInstance
  name: 'default'
}
resource dataflow_1 'Microsoft.IoTOperations/instances/dataflowProfiles/dataflows@2024-09-15-preview' = {
  parent: defaultDataflowProfile
  name: 'local-to-remote'
  extendedLocation: {
    name: customLocation.id
    type: 'CustomLocation'
  }
  properties: {
    mode: 'Enabled'
    operations: [
      {
        operationType: 'Source'
        sourceSettings: {
          endpointRef: 'default'
          dataSources: array('tutorial/local')
        }
      }
      {
        operationType: 'Destination'
        destinationSettings: {
          endpointRef: remoteMqttBrokerDataflowEndpoint.name
          dataDestination: 'telemetry/aio'
        }
      }
    ]
  }
} 
resource dataflow_2 'Microsoft.IoTOperations/instances/dataflowProfiles/dataflows@2024-09-15-preview' = {
  parent: defaultDataflowProfile
  name: 'remote-to-local'
  extendedLocation: {
    name: customLocation.id
    type: 'CustomLocation'
  }
  properties: {
    mode: 'Enabled'
    operations: [
      {
        operationType: 'Source'
        sourceSettings: {
          endpointRef: remoteMqttBrokerDataflowEndpoint.name
          dataSources: array('telemetry/#')
        }
      }
      {
        operationType: 'Destination'
        destinationSettings: {
          endpointRef: 'default'
          dataDestination: 'tutorial/cloud'
        }
      }
    ]
  }
}

Assim como ocorreu com o ponto de extremidade do fluxo de dados, execute o seguinte comando no seu terminal:

az deployment group create --resource-group <RESOURCE_GROUP> --template-file <FILE>.bicep

Juntos, os dois fluxos de dados formam uma ponte MQTT, na qual você:

  • Usar o agente MQTT da Grade de Eventos como o agente remoto
  • Usa o agente MQTT de Operações do Azure IoT local como o agente local
  • Usar o TLS para agentes remotos e locais
  • Usar a identidade gerenciada atribuída pelo sistema para autenticação no agente remoto
  • Usar a conta de serviço do Kubernetes para autenticação no agente local
  • Usar o mapa de tópicos para mapear o tópico tutorial/local para o tópico telemetry/aio no agente remoto
  • Usar o mapa de tópicos para mapear o tópico telemetry/# sobre o agente remoto para o tópico tutorial/cloud no agente local

Da mesma forma, quando você publica no tópico tutorial/local no agente MQTT de Operações do Azure IoT, a mensagem é colocada em ponte para o tópico telemetry/aio no agente MQTT da Grade de Eventos remoto. Em seguida, a mensagem é enviada novamente para o tópico tutorial/cloud (porque o tópico telemetry/# curinga a captura) no agente MQTT de Operações do Azure IoT local. Da mesma forma, quando você publica no telemetry/aio tópico no agente MQTT da Grade de Eventos remoto, a mensagem é colocada em ponte para o tutorial/cloud tópico no agente MQTT das Operações do Azure IoT local.

Implantar cliente MQTT

Para verificar se a ponte MQTT está funcionando, implante um cliente MQTT no mesmo namespace que as Operações do Azure IoT. Em um novo arquivo chamado client.yaml, especifique a implantação do cliente:

Atualmente, o Bicep não se aplica à implantação do cliente MQTT.

Iniciar um assinante

Use kubectl exec para iniciar um shell no pod do cliente mosquitto.

kubectl exec --stdin --tty mqtt-client -n azure-iot-operations -- sh

Dentro do shell, inicie um assinante para o agente das Operações do Azure IoT no espaço do tópico tutorial/# com mosquitto_sub.

mosquitto_sub --host aio-broker --port 18883 \
  -t "tutorial/#" \
  --debug --cafile /var/run/certs/ca.crt \
  -D CONNECT authentication-method 'K8S-SAT' \
  -D CONNECT authentication-data $(cat /var/run/secrets/tokens/broker-sat)

Deixe o comando em execução e abra uma nova janela de terminal.

Publicar mensagens MQTT na nuvem por meio da ponte

Em uma nova janela do terminal, inicie outro shell no pod do cliente mosquitto.

kubectl exec --stdin --tty mqtt-client -n azure-iot-operations -- sh

Dentro do shell, use mosquitto para publicar cinco mensagens no tópico tutorial/local.

mosquitto_pub -h aio-broker -p 18883 \
  -m "This message goes all the way to the cloud and back!" \
  -t "tutorial/local" \
  --repeat 5 --repeat-delay 1 -d \
  --debug --cafile /var/run/certs/ca.crt \
  -D CONNECT authentication-method 'K8S-SAT' \
  -D CONNECT authentication-data $(cat /var/run/secrets/tokens/broker-sat)

Exibir as mensagens no assinante

No shell do assinante, você verá as mensagens publicadas.

Aqui, você verá que as mensagens são publicadas no agente das Operações do Azure IoT local para o tópico tutorial/local, feitas em ponte para o agente MQTT da Grade de Eventos e, em seguida, enviadas novamente em ponte ao agente das Operações do Azure IoT local novamente sobre o tópico tutorial/cloud. Em seguida, as mensagens são entregues ao assinante. Neste exemplo, o tempo de viagem de ida e volta é de cerca de 80 ms.

Verificar as métricas da Grade de Eventos para verificar a entrega de mensagens

Você também pode verificar as métricas da Grade de Eventos para verificar se as mensagens são entregues ao agente MQTT da Grade de Eventos. No portal do Azure, acesse o namespace da Grade de Eventos que você criou. Em Métricas>MQTT: Mensagens publicadas com êxito. Você deverá ver o número de mensagens publicadas e entregues aumentar à medida que publica mensagens no agente das Operações do Azure IoT local.

Captura de tela da exibição de métricas no portal do Azure para mostrar mensagens MQTT bem-sucedidas.

Dica

Verifique as configurações de fluxos de dados, QoS e rotas de mensagem com a extensão da CLI az iot ops check --detail-level 2.

Próximas etapas

Neste tutorial, você aprendeu a configurar as Operações do Azure IoT para ponte MQTT bidirecional com o agente MQTT da Grade de Eventos do Azure. Como próximas etapas, explore os seguintes cenários:

  • Para usar um cliente MQTT para publicar mensagens diretamente no agente MQTT da Grade de Eventos, consulte Publicar mensagens MQTT no agente MQTT da Grade de Eventos. Conceda ao cliente uma associação de permissão do editor ao espaço de tópico criado e você pode publicar mensagens em qualquer tópico no telemetry, como telemetry/temperature ou telemetry/humidity. Todas essas mensagens são colocadas em ponte para o tópico tutorial/cloud no agente das Operações do Azure IoT local.
  • Para configurar regras de roteamento para o agente MQTT da Grade de Eventos, consulte Configurar regras de roteamento para o agente MQTT da Grade de Eventos. Você pode usar regras de roteamento para rotear mensagens para diferentes tópicos com base no nome do tópico ou filtrar mensagens com base no conteúdo da mensagem.

Conteúdo relacionado