Partilhar via

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

  • Artigo

Importante

Esta página inclui instruções para gerenciar componentes do Azure IoT Operations usando manifestos de implantação do Kubernetes, que está em visualização. Esse recurso é fornecido com várias limitações e não deve ser usado para cargas de trabalho de produção.

Veja Termos de Utilização Complementares da Pré-visualizações do Microsoft Azure para obter os termos legais que se aplicam às funcionalidades do Azure que estão na versão beta, na pré-visualização ou que ainda não foram lançadas para disponibilidade geral.

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

Pré-requisitos

Definir variáveis de ambiente

Entre com a CLI do Azure:

az login

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

# 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 de grade de eventos com o agente MQTT habilitado

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

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

Se a eventgrid extensão não estiver instalada, você receberá um prompt perguntando se deseja instalá-la. Selecione Y para instalar a extensão.

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

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

A opção max client sessions permite que o Azure IoT Operations MQTT gere várias instâncias e ainda se conecte. Para saber mais, consulte Suporte a várias sessões.

Criar um espaço de tópico

No namespace 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 telemetry tópico. Por exemplo, telemetry/temperature ou telemetry/humidity.

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

Usando a CLI do Azure, localize a ID principal para a extensão do Azure IoT Operations Arc. O comando armazena o ID principal 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 Azure IoT Operations MQTT 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

Gorjeta

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

Grade de eventos Nome do host do broker MQTT

Use a CLI do Azure para obter o nome de host do broker 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 que é um valor de nome de host que se parece com:

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

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

Crie o 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 de host MQTT obtido na etapa anterior. Inclua o número 8883da porta .

O fluxo de dados e os pontos de extremidade de fluxo de dados da Grade de Eventos do Azure podem ser implantados como recursos padrão do Azure, pois eles têm implementações do Provedor de Recursos do Azure (RPs). Este arquivo de modelo Bicep do Bicep File for MQTT-bridge dataflow Tutorial implanta o fluxo de dados e os pontos de extremidade de fluxo de dados necessários.

Transfira o ficheiro para o seu local e certifique-se de que substitui os valores de customLocationName, aioInstanceName, eventGridHostName pelo seu.

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-11-01' existing = {
  name: aioInstanceName
}
resource remoteMqttBrokerDataflowEndpoint 'Microsoft.IoTOperations/instances/dataflowEndpoints@2024-11-01' = {
  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 seguinte comando 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 é definido para SystemAssignedManagedIdentity usar a identidade gerenciada da extensão Azure IoT Operations para autenticar com o agente MQTT da Grade de Eventos. Essa configuração funciona porque a extensão de Operações 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 broker MQTT da Grade de Eventos requer TLS, a tls configuração está habilitada. Não há necessidade de fornecer um certificado de CA confiável, 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 do Azure IoT Operations como a origem e o ponto de extremidade da Grade de Eventos do Azure como o destino e vice-versa. Não há necessidade de 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-11-01' existing = {
  name: aioInstanceName
}
resource defaultDataflowProfile 'Microsoft.IoTOperations/instances/dataflowProfiles@2024-11-01' existing = {
  parent: aioInstance
  name: 'default'
}
resource dataflow_1 'Microsoft.IoTOperations/instances/dataflowProfiles/dataflows@2024-11-01' = {
  parent: defaultDataflowProfile
  name: 'local-to-remote'
  extendedLocation: {
    name: customLocation.id
    type: 'CustomLocation'
  }
  properties: {
    mode: 'Enabled'
    operations: [
      {
        operationType: 'Source'
        sourceSettings: {
          endpointRef: 'default'
          serializationFormat: 'Json'
          dataSources: array('tutorial/local')
        }
      }
      {
        operationType: 'BuiltInTransformation'

        builtInTransformationSettings: {
        serializationFormat: 'Json'
        datasets: []
        filter: []
        map: [
          {
            type: 'PassThrough'
            inputs: [
              '*'
            ]
            output: '*'
          }
        ]
        }
      }
      {
        operationType: 'Destination'
        destinationSettings: {
          endpointRef: 'eventgrid'
          dataDestination: 'telemetry/aio'
        }
      }
    ]
  }
} 
resource dataflow_2 'Microsoft.IoTOperations/instances/dataflowProfiles/dataflows@2024-11-01' = {
  parent: defaultDataflowProfile
  name: 'remote-to-local'
  extendedLocation: {
    name: customLocation.id
    type: 'CustomLocation'
  }
  properties: {
    mode: 'Enabled'
    operations: [
      {
        operationType: 'Source'
        sourceSettings: {
          endpointRef: 'eventgrid'
          serializationFormat: 'Json'
          dataSources: array('telemetry/#')
        }
      }
      {
        operationType: 'BuiltInTransformation'

        builtInTransformationSettings: {
        serializationFormat: 'Json'
        datasets: []
        filter: []
        map: [
          {
            type: 'PassThrough'
            inputs: [
              '*'
            ]
            output: '*'
          }
        ]
        }
      }
      {
        operationType: 'Destination'
        destinationSettings: {
          endpointRef: 'default'
          dataDestination: 'tutorial/cloud'
        }
      }
    ]
  }
}

Como o ponto de extremidade de fluxo de dados, execute o seguinte comando em seu terminal:

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

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

  • Use o agente MQTT da grade de eventos como o broker remoto
  • Usar o agente MQTT local do Azure IoT Operations como o agente local
  • Usar TLS para corretores remotos e locais
  • Usar identidade gerenciada atribuída ao sistema para autenticação no agente remoto
  • Usar a conta de serviço do Kubernetes para autenticação no broker local
  • Use o mapa de tópicos para mapear o tutorial/local tópico para o telemetry/aio tópico no broker remoto
  • Use o mapa de tópicos para mapear o telemetry/# tópico no broker remoto para o tutorial/cloud tópico no broker local

Nota

Por padrão, o Azure IoT Operations implanta um broker MQTT, bem como um ponto de extremidade de fluxo de dados do broker MQTT. O ponto de extremidade de fluxo de dados do broker MQTT é usado para se conectar ao broker MQTT. A configuração padrão usa o token de conta de serviço interno para autenticação. O ponto de extremidade é nomeado default e está disponível no mesmo namespace que as Operações do Azure IoT. O ponto de extremidade é usado como a fonte para o fluxo de dados criado neste tutorial. Para saber mais sobre o ponto de extremidade padrão do fluxo de dados do agente MQTT, consulte Ponto de extremidade padrão do agente MQTT local do Azure IoT Operations.

Quando você publica no tutorial/local tópico no agente MQTT local do Azure IoT Operations, a mensagem é conectada telemetry/aio ao tópico no agente MQTT da Grade de Eventos remota. Em seguida, a mensagem é conectada de volta ao tutorial/cloud tópico (porque o tópico curinga telemetry/# a captura) no agente MQTT local do Azure IoT Operations. Da mesma forma, quando você publica no telemetry/aio tópico no broker MQTT da Grade de Eventos remota, a mensagem é conectada tutorial/cloud ao tópico no agente MQTT local do Azure IoT Operations.

Implantar o cliente MQTT

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

Atualmente, o bicep não se aplica para implantar o cliente MQTT.

Iniciar um subscritor

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 do agente de Operações IoT do Azure no espaço de tutorial/# tópico 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 do terminal.

Publique mensagens MQTT na nuvem através da ponte

Em uma nova janela de 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 para o tutorial/local tópico.

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)

Ver as mensagens no subscritor

No shell do assinante, você vê as mensagens publicadas.

Aqui, você vê que as mensagens são publicadas no agente de Operações do Azure IoT local para o tutorial/local tópico, conectadas ao agente MQTT da Grade de Eventos e, em seguida, reconectadas ao agente de Operações do Azure IoT local novamente no tutorial/cloud tópico. As mensagens são então entregues ao assinante. Neste exemplo, o tempo de ida e volta é de cerca de 80 ms.

Verifique 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 broker MQTT da Grade de Eventos. No portal do Azure, vá para o namespace Grade de Eventos que você criou. Em Métricas>MQTT: Mensagens publicadas com sucesso. Você verá o número de mensagens publicadas e entregues aumentar à medida que publica mensagens no agente local do Azure IoT Operations.

Captura de ecrã da vista de métricas no portal do Azure para mostrar mensagens MQTT bem-sucedidas.

Gorjeta

Você pode verificar as configurações de fluxos de dados, QoS e rotas de mensagens com a extensão az iot ops check --detail-level 2CLI.

Próximos passos

Neste tutorial, você aprendeu como configurar o Azure IoT Operations 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 broker MQTT da Grade de Eventos, consulte Publicar mensagens MQTT no broker MQTT da Grade de Eventos. Dê ao cliente uma associação de permissão de editor para o espaço de tópico que você criou, e você pode publicar mensagens em qualquer tópico sob , telemetrycomo telemetry/temperature ou telemetry/humidity. Todas essas mensagens são conectadas ao tutorial/cloud tópico no agente local de Operações do Azure IoT.
  • 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 tópicos diferentes com base no nome do tópico ou para filtrar mensagens com base no conteúdo da mensagem.

Conteúdos relacionados