Compartilhar via

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

Importante

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

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 preliminar ou que, de outra forma, ainda não foram lançados em disponibilidade geral.

Neste tutorial, você terá que configurar uma transferência 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. Não é necessário aplicar nenhuma transformação.

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 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}"

Caso a extensão eventgrid não esteja instalada, você verá 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:

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

A opção para selecionar o máximo de sessões de cliente permite que o MQTT das Operações do Azure IoT gere várias instâncias e, mesmo assim, 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 sensor/#.

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

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

Permitir que as Operações do Azure IoT acessem o espaço de tópicos da Grade de Eventos

Use a CLI do Azure para encontrar a ID da entidade de segurança da 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:

aaaaaaaa-bbbb-cccc-1111-222222222222

Em seguida, use a CLI do Azure a fim de atribuir funções de editor e assinante ao MQTT das Operações do Azure IoT do espaço de tópicos 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

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 do Bicep do Tutorial Arquivo do Bicep para fluxo de dados de ponte MQTT implanta o fluxo de dados e os pontos de extremidade do 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-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'
      }
    }
  }
}

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

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

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

Como o agente MQTT da Grade de Eventos requer o protocolo 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 das 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-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: 'sensor/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('sensor/#')
        }
      }
      {
        operationType: 'BuiltInTransformation'

        builtInTransformationSettings: {
        serializationFormat: 'Json'
        datasets: []
        filter: []
        map: [
          {
            type: 'PassThrough'
            inputs: [
              '*'
            ]
            output: '*'
          }
        ]
        }
      }
      {
        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
  • Usar 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 sensor/aio no agente remoto
  • Usar o mapa de tópicos para mapear o tópico sensor/# sobre o agente remoto para o tópico tutorial/cloud no agente local

Observação

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 a fonte para o fluxo de dados criado neste tutorial. Para saber mais sobre o ponto de extremidade padrão de fluxo de dados do agente MQTT, consulte Ponto de extremidade padrão do agente MQTT local das Operações do Azure IoT.

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 sensor/aio no agente MQTT da Grade de Eventos remoto. Depois, a mensagem é transferida novamente para o tópico tutorial/cloud (porque o tópico curinga sensor/# a captura) no agente MQTT de Operações do Azure IoT local. Da mesma forma, quando você publica no sensor/aio tópico no agente MQTT da Grade de Eventos remoto, a mensagem é colocada transferida para o tópico tutorial/cloud no agente MQTT das Operações do Azure IoT local.

Implantar cliente MQTT

Para verificar se a transferência MQTT funciona, implante um cliente MQTT no mesmo namespace que as Operações do Azure IoT.

Atualmente, o arquivo 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

No 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.

Client null sending CONNECT
Client $server-generated/0000aaaa-11bb-cccc-dd22-eeeeee333333 received CONNACK (0)
Client $server-generated/0000aaaa-11bb-cccc-dd22-eeeeee333333 sending SUBSCRIBE (Mid: 1, Topic: tutorial/#, QoS: 0, Options: 0x00)
Client $server-generated/0000aaaa-11bb-cccc-dd22-eeeeee333333 received SUBACK
Subscribed (mid: 1): 0
Client $server-generated/0000aaaa-11bb-cccc-dd22-eeeeee333333 sending PINGREQ
Client $server-generated/0000aaaa-11bb-cccc-dd22-eeeeee333333 received PINGRESP
Client $server-generated/0000aaaa-11bb-cccc-dd22-eeeeee333333 received PUBLISH (d0, q0, r0, m0, 'tutorial/local', ... (52 bytes))
This message goes all the way to the cloud and back!
Client $server-generated/0000aaaa-11bb-cccc-dd22-eeeeee333333 received PUBLISH (d0, q0, r0, m0, 'tutorial/local', ... (52 bytes))
This message goes all the way to the cloud and back!
Client $server-generated/0000aaaa-11bb-cccc-dd22-eeeeee333333 received PUBLISH (d0, q0, r0, m0, 'tutorial/local', ... (52 bytes))
This message goes all the way to the cloud and back!
Client $server-generated/0000aaaa-11bb-cccc-dd22-eeeeee333333 received PUBLISH (d0, q0, r0, m0, 'tutorial/local', ... (52 bytes))
This message goes all the way to the cloud and back!
Client $server-generated/0000aaaa-11bb-cccc-dd22-eeeeee333333 received PUBLISH (d0, q0, r0, m0, 'tutorial/local', ... (52 bytes))
This message goes all the way to the cloud and back!
Client $server-generated/0000aaaa-11bb-cccc-dd22-eeeeee333333 sending PINGREQ
Client $server-generated/0000aaaa-11bb-cccc-dd22-eeeeee333333 received PINGRESP

Aqui, você verá que as mensagens são publicadas no agente das Operações do Azure IoT local do tópico tutorial/local, transferidas para o agente MQTT da Grade de Eventos e, em seguida, enviadas transferidas novamente para as Operações do Azure IoT local novamente no 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 anteriormente. Em Métricas>MQTT: Mensagens publicadas com êxito. Você deverá ver o número de mensagens publicadas e entregues aumentar conforme publica as 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

Você pode conferir as configurações dos fluxos de dados, de QoS e dos roteamentos de mensagem com a extensão da CLIaz iot ops check --detail-level 2.

Próximas etapas

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

  • Last updated on