Обогащения для перенаправленных сообщений MQTT

Статья
11/15/2023

Поддержка обогащений позволяет добавлять до 20 настраиваемых свойств "ключ-значение" в сообщения перед отправкой в пользовательский раздел Сетки событий. Эти обогащения позволяют:

Добавьте контекстные данные в сообщения. Например, обогащение сообщения именем клиента или именем пространства имен может предоставить конечные точки с информацией о источнике сообщения.
Уменьшение вычислительной нагрузки на конечные точки. Например, обогащение сообщения индикатором формата полезных данных запроса на публикацию MQTT или типом контента сообщает конечным точкам, как обрабатывать полезные данные сообщения, не пытаясь сначала выполнить несколько синтаксического анализа.
Отфильтруйте перенаправленные сообщения по подпискам на события Сетки событий на основе добавленных данных. Например, обогащение клиентского атрибута позволяет фильтровать сообщения для маршрутизации в конечную точку на основе значений различных атрибутов.

Настройка

Ключ обогащения:

Ключ обогащения — это строка, которая должна соответствовать этим требованиям:

Включить только буквенно-буквенные буквы нижнего регистра: только (a-z) и (0-9)
Не должно бытьspecversion, idsubjecttypetimedatacontenttypedataschemasourcedataили .data_base64
Не следует начинать с azsp.
Не следует дублироваться.
Не должно быть более 20 символов.

Значение обогащения:

Значение обогащения может быть статической строкой для статических обогащений или одним из поддерживаемых значений, представляющих атрибуты клиента или свойства сообщения MQTT для динамического обогащения. Значения обогащения не должны превышать 128 символов. Следующий список содержит поддерживаемые значения:

Атрибуты клиента

${client.authenticationName}: имя клиента публикации.
${client.attributes.x}: атрибут клиента публикации, где x — имя ключа атрибута.

Свойства MQTT

${mqtt.message.userProperties.x}: свойства пользователя в пакете публикации MQTTv5, где x — имя ключа свойства пользователя.
- Тип: string
- Используйте следующий формат переменной, если свойство пользователя содержит специальные символы ${mqtt.message.userProperties['x']}. Вам по-прежнему нужно избежать апострофа и обратной косой черты, как показано ниже: и "PN\t" становится "PN\t".
${mqtt.message.topicName}: раздел в пакете MQTT PUBLISH.
- Тип: string
${mqtt.message.responseTopic}: раздел ответа в пакете публикации MQTTv5.
- Тип: string
${mqtt.message.correlationData}: данные корреляции в пакете MQTTv5 PUBLISH.
- Тип: двоичный
${mqtt.message.pfi}: индикатор формата полезных данных в пакете MQTTv5 PUBLISH.
- Тип: целое число

Настройка портала Azure

Чтобы настроить обогащения маршрутизации, выполните следующие действия.

Перейдите в пространство имен в портал Azure.
В разделе "Маршрутизация" проверьте включение маршрутизации.
В разделе маршрутизации выберите раздел "Сетка событий", созданный, где будут перенаправлены все сообщения MQTT.
В разделе "Обогащение сообщений" выберите +Добавить обогащение.
Добавьте до 20 пар "ключ-значение" и выберите нужный тип.
Выберите Применить.

Screenshot showing the routing enrichment configuration through the portal.

Дополнительные сведения о конфигурации маршрутизации см. в разделе "Маршрутизация портал Azure конфигурации".

Настройка Azure CLI

Используйте команду и полезные данные во время создания и обновления пространства имен, чтобы настроить обогащения маршрутизации:

az resource create --resource-type Microsoft.EventGrid/namespaces --id /subscriptions/<Subscription ID>/resourceGroups/<Resource Group>/providers/Microsoft.EventGrid/namespaces/<Namespace Name> --is-full-object --api-version 2023-06-01-preview --properties @./resources/NS.json

NS.json

{
  "properties": {
    "topicSpacesConfiguration": {
        "state": "Enabled",
        "routeTopicResourceId": "/subscriptions/<Subscription ID>/resourceGroups/<Resource Group>/providers/Microsoft.EventGrid/topics/<Event Grid Topic name>",
        "routingEnrichments": {
            "static": [
                {
                    "key": "namespaceid",
                    "value": "123",
                    "valueType": "string"
                }
            ],
            "dynamic": [
                {
                    "key": "clientname",
                    "value": "${client.authenticationName}"
                },
                {
                    "key": "clienttype",
                    "value": "${client.attributes.type}"
                },
                {
                    "key": "address",
                    "value": "${mqtt.message.userProperties['client.address']}"
                },
                {
                    "key": "region",
                    "value": "${mqtt.message.userProperties.location}"
                },
                {
                    "key": "mqtttopic",
                    "value": "${mqtt.message.topicName}"
                },
                {
                    "key": "mqttresponsetopic",
                    "value": "${mqtt.message.responseTopic}"
                },
                {
                    "key": "mqttcorrelationdata",
                    "value": "${mqtt.message.correlationData}"
                },
                {
                    "key": "mqttpfi",
                    "value": "${mqtt.message.pfi}"
                }
            ]
        }
    }
},
"location": "eastus2euap",
"tags": {},
}

Дополнительные сведения о конфигурации маршрутизации см. в разделе "Маршрутизация конфигурации Azure CLI".

Образец вывода

Следующий CloudEvent — это пример выходных данных сообщения MQTTv5 с PFI=0 после применения предыдущей конфигурации обогащения:

{
    "specversion": "1.0",
	"id": "9aeb0fdf-c01e-0131-0922-9eb54906e20", // unique id stamped by the service
	"time": "2019-11-18T15:13:39.4589254Z", // timestamp when messages was received by the service
	"type": "MQTT.EventPublished", // set type for all MQTT messages enveloped by the service
	"source": "testnamespace", // namespace name
	"subject": "campus/buildings/building17", // topic of the MQTT publish request
	"namespaceid": "123", // static enrichment
	"clientname": "client1", // dynamic enrichment of the name of the publishing client
	"clienttype": "operator", // dynamic enrichment of an attribute of the publishing client
	"address": "1 Microsoft Way, Redmond, WA 98052", // dynamic enrichment of a user property in the MQTT publish request
	"region": "North America", // dynamic enrichment of another user property in the MQTT publish request
	"mqtttopic": "campus/buildings/building17", // dynamic enrichment of the topic of the MQTT publish request
	"mqttresponsetopic": "campus/buildings/building17/response", // dynamic enrichment of the response topic of the MQTT publish request
	"mqttcorrelationdata": "cmVxdWVzdDE=", // dynamic enrichment of the correlation data of the MQTT publish request encoded in base64
	"mqttpfi": 0, // dynamic enrichment of the payload format indicator of the MQTT publish request
	"datacontenttype": "application/octet-stream", //content type of the MQTT publish request
	"data_base64": 
    {
	    IlRlbXAiOiAiNzAiLAoiaHVtaWRpdHkiOiAiNDAiCg==
	}
}

Обработка специальных случаев:

Необязаемые атрибуты клиента или свойства пользователя: если динамическое обогащение указывает на свойство клиента или пользователя, которое не существует, обогащение будет включать указанный ключ с пустой строкой для значения. Например, emptyproperty: "".
Массивы: массивы в атрибутах клиента и повторяющиеся свойства пользователя преобразуются в строку, разделенную запятыми. Например, если обогащенный атрибут клиента имеет значение array: "value1", "value2", "value3", то результирующее обогащенное свойство будет array: value1,value2,value3. Другой пример: если тот же запрос публикации MQTT имеет следующие свойства > пользователя "userproperty1": "value1", "userproperty1": "value2", результирующее обогащенное свойство будет userproperty1: value1,value2.

Дальнейшие действия

Дополнительные сведения о маршрутизации см. в следующих статьях:

Поделиться через