Adicionar atributos de propagação para enriquecimento da mensagem - AWS IoT Core
Console de gerenciamento da AWSAWS CLI

Adicionar atributos de propagação para enriquecimento da mensagem

No AWS IoT Core, você pode enriquecer mensagens do MQTT de dispositivos adicionando atributos de propagação, que são metadados contextuais de atributos de coisas ou detalhes de conexão. Esse processo, conhecido como enriquecimento de mensagens, pode ser útil em vários cenários. Por exemplo, é possível enriquecer mensagens para cada operação de publicação de entrada sem fazer alterações no dispositivo nem precisar usar regras. Ao utilizar os atributos de propagação, você pode se beneficiar de uma maneira mais eficiente e econômica de enriquecer seus dados da IoT sem as complexidades de configurar regras ou gerenciar configurações de republicação.

O recurso de enriquecimento de mensagens está disponível para clientes do AWS IoT Core que usam ingestão básica e agente de mensagens. É importante observar que, embora os dispositivos de publicação possam usar qualquer versão do MQTT, os assinantes (aplicações ou serviços que consomem mensagens) devem comportar o MQTT 5 para receber as mensagens enriquecidas com atributos de propagação. As mensagens enriquecidas serão adicionadas como propriedades do usuário do MQTT 5 a todas as mensagens publicadas dos dispositivos. Se você usar regras, poderá utilizar a função get_user_properties para recuperar os dados enriquecidos para roteamento ou processamento de mensagens com base nos dados.

No AWS IoT Core, você pode adicionar atributos de propagação ao criar ou atualizar um tipo de coisa, usando o Console de gerenciamento da AWS ou a AWS CLI.

Importante

Ao adicionar atributos de propagação, você deve garantir que o cliente que está publicando a mensagem tenha sido autenticado com um certificado. Para obter mais informações, consulte Autenticação de cliente.

nota

Se você tentar testar esse recurso usando o cliente de teste do MQTT no console, pode ser que ele não funcione, pois esse recurso precisa de clientes do MQTT autenticados com um certificado associado.

Console de gerenciamento da AWS

Como adicionar atributos de propagação para enriquecimento de mensagens usando o Console de gerenciamento da AWS

  1. Abra a página inicial do AWS IoT no console do AWS IoT. No painel de navegação esquerdo, em Gerenciar, escolha Todos os dispositivos. Depois, selecione Tipos de coisas.

  2. Na página Tipos de coisas, selecione Criar tipo de coisa.

    Para configurar o enriquecimento de mensagens atualizando um tipo de coisa, escolha um tipo de coisa. Depois, na página de detalhes do tipo de coisa, escolha Atualizar.

  3. Na página Criar tipo de coisa, selecione ou insira as informações do tipo de coisa em Propriedades do tipo de coisa.

    Se você optar por atualizar um tipo de coisa, verá as propriedades do tipo de coisa depois de selecionar Atualizar na etapa anterior.

  4. Em Configuração adicional, expanda Atributos de propagação. Depois, escolha Atributo de coisa e insira o atributo de coisa que você deseja preencher nas mensagens publicadas do MQTT5. Usando o console, você pode adicionar até outros três atributos de coisa.

    Na seção Atributos de propagação, escolha Atributo de conexão e insira o tipo de atributo e, opcionalmente, o nome do atributo.

  5. Opcionalmente, adicione tags. Depois, escolha Criar tipo de coisa.

    Se você optar por atualizar um tipo de coisa, escolha Atualizar tipo de coisa.

AWS CLI

  1. Para adicionar atributos de propagação para enriquecimento de mensagens criando um tipo de coisa com a AWS CLI, execute o comando create-thing-type. O comando a seguir é um exemplo.

    aws iot create-thing-type \
    --thing-type-name "LightBulb" \
    --thing-type-properties "{\"mqtt5Configuration\":{\"propagatingAttributes\":[{\"userPropertyKey\":\"iot:ClientId\", \"connectionAttribute\":\"iot:ClientId\"}, {\"userPropertyKey\":\"test\", \"thingAttribute\":\"A\"}]}}" \

    A saída do comando pode ser semelhante à seguinte.

    {
	"thingTypeName": "LightBulb",
	"thingTypeArn": "arn:aws:iot:us-west-2:123456789012:thingtype/LightBulb",
	"thingTypeId": "ce3573b0-0a3c-45a7-ac93-4e0ce14cd190"
}

  2. Para configurar o enriquecimento de mensagens atualizando um tipo de coisa com a AWS CLI, execute o comando update-thing-type. Observe que você só pode atualizar a mqtt5Configuration quando executar esse comando. O comando a seguir é um exemplo.

    aws iot update-thing-type \
    --thing-type-name "MyThingType" \
    --thing-type-properties "{\"mqtt5Configuration\":{\"propagatingAttributes\":[{\"userPropertyKey\":\"iot:ClientId\", \"connectionAttribute\":\"iot:ClientId\"}, {\"userPropertyKey\":\"test\", \"thingAttribute\":\"A\"}]}}" \

    Esse comando não retorna nenhuma saída.

  3. Para descrever um tipo de coisa, execute o comando describe-thing-type. Esse comando produzirá uma saída com informações de configuração de enriquecimento de mensagens no campo thing-type-properties. O comando a seguir é um exemplo.

    aws iot describe-thing-type \
    --thing-type-name "LightBulb"

    A saída poderá ser parecida com a seguinte:

    {
	"thingTypeName": "LightBulb",
	"thingTypeId": "bdf72512-0116-4392-8d79-bf39b17ef73d",
	"thingTypeArn": "arn:aws:iot:us-east-1:123456789012:thingtype/LightBulb",
	"thingTypeProperties": {
		"mqtt5Configuration": {
			"propagatingAttributes": [
				{
					"userPropertyKey": "iot:ClientId",
					"connectionAttribute": "iot:ClientId"
				},
				{
					"userPropertyKey": "test",
					"thingAttribute": "attribute"
				}
			]
		}
	},
	"thingTypeMetadata": {
		"deprecated": false,
		"creationDate": "2024-10-18T17:37:46.656000+00:00"
	}
}

Para obter mais informações, consulte Tipos de objeto.