IoT Hub message routing query syntax (Синтаксис запросов маршрутизации сообщений Центра Интернета вещей)

Статья
03/18/2023

Маршрутизация сообщений позволяет пользователям направлять различные типы данных, включая сообщения телеметрии устройства, события жизненного цикла устройства и события изменения двойника устройства в различные конечные точки. Кроме того, можно применить полнофункциональные запросы к этим данным перед их отправкой, чтобы получить важные сведения. В этой статье описывается язык запросов маршрутизации сообщений Центра Интернета вещей, а также приводятся некоторые распространенные шаблоны запросов.

Примечание.

Некоторые функции, упоминаемые в этой статье, например обмен сообщениями между облаком и устройством, двойники устройств и управление устройствами, доступны только для Центра Интернета вещей уровня "Стандартный". Дополнительные сведения о базовых и бесплатных уровнях Центр Интернета вещей см. в разделе "Выбор подходящего уровня Центр Интернета вещей" для решения.

Маршрутизация сообщений позволяет запрашивать свойства сообщения, текст сообщения, теги и свойства двойников устройств. Если текст сообщения не находится в формате JSON, маршрутизация сообщений по-прежнему может маршрутизировать сообщение, но запросы не могут быть применены к тексту сообщения. Запросы описываются как логические выражения, в которых запрос успешно выполняется и направляет все входящие данные. в противном случае запрос завершается ошибкой, и входящие данные не маршрутизаются. Если выражение вычисляет значение NULL или неопределенное значение, оно обрабатывается как логическое значение false и создает ошибку в Центр Интернета вещей маршрутизирует журналы ресурсов. Для сохранения и вычисления маршрута синтаксис запроса должен быть правильным.

Запрос на основе свойств сообщения

Центр Интернета вещей определяет общий формат для всех сообщений между устройствами и облаком для взаимодействия между протоколами. Центр Интернета вещей предполагает следующее представление сообщения в формате JSON. Системные свойства добавляются для всех пользователей и определяют содержимое сообщения. Пользователи могут выборочно добавлять в сообщение свойства приложений. Рекомендуется использовать уникальные имена свойств, так как Центр Интернета вещей обмен сообщениями между устройствами и облаком не учитывает регистр. Например, если у вас есть несколько свойств с одним именем, центр Интернета вещей будет отправлять только одно из этих свойств.

{ 
  "message": { 
    "systemProperties": { 
      "contentType": "application/json", 
      "contentEncoding": "UTF-8", 
      "iothub-message-source": "deviceMessages", 
      "iothub-enqueuedtime": "2017-05-08T18:55:31.8514657Z" 
    }, 
    "appProperties": { 
      "processingPath": "{cold | warm | hot}", 
      "verbose": "{true, false}", 
      "severity": 1-5, 
      "testDevice": "{true | false}" 
    }, 
    "body": "{\"Weather\":{\"Temperature\":50}}" 
  } 
}

Свойства системы

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

Свойство	Type	Описание
contentType	строка	Пользователь указывает тип содержимого сообщений. Чтобы разрешить запросы в тексте сообщения, это значение должно иметь значение `application/JSON`.
contentEncoding	строка	Пользователь указывает тип кодирования сообщений. Если для свойства contentType задано `application/JSON`значение, допустимые значения : `UTF-8UTF-16`и `UTF-32`.
iothub-connection-device-id	строка	Это значение задается Центром Интернета вещей и определяет идентификатор устройства. Чтобы запросить, используйте `$connectionDeviceId`.
iothub-connection-module-id	строка	Это значение задается Центром Интернета вещей и определяет идентификатор граничного модуля. Чтобы запросить, используйте `$connectionModuleId`.
iothub-enqueuedtime	строка	Это значение задается центром Интернета вещей и представляет фактическое время постановки сообщения в очередь в формате UTC. Чтобы запросить, используйте `$enqueuedTime`.
dt-dataschema	строка	Это значение задается Центр Интернета вещей в сообщениях устройства в облако. Оно содержит идентификатор модели устройства, указанный в подключении устройства. Чтобы запросить, используйте `$dt-dataschema`.
dt-subject	строка	Имя компонента, который отправляет сообщения с устройства в облако. Чтобы запросить, используйте `$dt-subject`.

Дополнительные сведения о других доступных системных свойствах см. в статье "Создание и чтение Центр Интернета вещей сообщений".

Свойства приложения

Свойства приложения — это определяемые пользователем строки, которые можно добавить в сообщение. Эти поля являются необязательными.

Выражения запросов свойств сообщения

Запрос к свойствам системы сообщений должен быть префиксирован символом $ . Запросы к свойствам приложения получают доступ с их именем и не должны быть префиксированы символом $. Если имя свойства приложения начинается с$, Центр Интернета вещей сначала ищет его в системных свойствах, и если он не найден, будет искать его в свойствах приложения. В следующих примерах показано, как запрашивать свойства системы и свойства приложения.

Запрос к содержимому содержимого системного свойстваEncoding:

$contentEncoding = 'UTF-8'

Чтобы выполнить запрос к обработчику свойств приложения, выполните следующие действия:

processingPath = 'hot'

Чтобы объединить эти запросы, можно использовать логические выражения и функции.

$contentEncoding = 'UTF-8' AND processingPath = 'hot'

Полный список поддерживаемых операторов и функций представлен в разделе выражений и условий языка запросов Центр Интернета вещей для двойников устройств и модулей, заданий и маршрутизации сообщений.

Запрос на основе текста сообщения

Чтобы включить запросы в тексте сообщения, сообщение должно быть в формате JSON и закодировано в UTF-8, UTF-16 или UTF-32. Системное contentType свойство должно быть application/JSON. Системное contentEncoding свойство должно быть одним из значений кодировки UTF, поддерживаемых этим системным свойством. Если эти системные свойства не указаны, Центр Интернета вещей не будет оценивать выражение запроса в тексте сообщения.

В следующем примере JavaScript показано, как создать сообщение с правильно сформированным и закодированным текстом JSON:

var messageBody = JSON.stringify(Object.assign({}, {
    "Weather": {
        "Temperature": 50,
        "Time": "2017-03-09T00:00:00.000Z",
        "PrevTemperatures": [
            20,
            30,
            40
        ],
        "IsEnabled": true,
        "Location": {
            "Street": "One Microsoft Way",
            "City": "Redmond",
            "State": "WA"
        },
        "HistoricalData": [
            {
                "Month": "Feb",
                "Temperature": 40
            },
            {
                "Month": "Jan",
                "Temperature": 30
            }
        ]
    }
}));

// Encode message body using UTF-8  
var messageBytes = Buffer.from(messageBody, "utf8");

var message = new Message(messageBytes);

// Set message body type and content encoding 
message.contentEncoding = "utf-8";
message.contentType = "application/json";

// Add other custom application properties   
message.properties.add("Status", "Active");

deviceClient.sendEvent(message, (err, res) => {
    if (err) console.log('error: ' + err.toString());
    if (res) console.log('status: ' + res.constructor.name);
});

Пример кодирования сообщений в C#см . в разделе HubRoutingSample , предоставленном в пакете SDK Для Интернета вещей Microsoft Azure для .NET. Этот пример используется в руководстве по маршрутизации сообщений. Файл Program.cs также имеет метод с именем ReadOneRowFromFile, который считывает один из кодированных файлов, декодирует его и записывает его обратно в as ASCII, чтобы можно было прочитать его.

Выражения запроса текста сообщения

Запрос к тексту сообщения должен начинаться с $body. В выражении запроса можно использовать ссылку на текст, ссылку на массив текста или несколько ссылок на текст. Выражение запроса также может объединять ссылку на текст со ссылкой на свойства системы сообщений или ссылкой на свойства приложения сообщения. Например, следующие примеры являются допустимыми выражениями запросов:

$body.Weather.HistoricalData[0].Month = 'Feb'

$body.Weather.Temperature = 50 AND $body.Weather.IsEnabled

length($body.Weather.Location.State) = 2

$body.Weather.Temperature = 50 AND processingPath = 'hot'

Запросы и функции можно выполнять только в свойствах в ссылке на текст. Запросы и функции нельзя выполнять для всей ссылки на текст. Например, следующий запрос не поддерживается и возвращаетсяundefined:

$body[0] = 'Feb'

Чтобы отфильтровать полезные данные уведомления двойника на основе того, что изменилось, запустите запрос в тексте сообщения. Например, чтобы отфильтровать при изменении sendFrequency требуемого свойства и значение больше 10:

$body.properties.desired.telemetryConfig.sendFrequency > 10

Для фильтрации сообщений, содержащих изменение свойства, независимо от значения свойства, можно использовать функцию is_defined() (если значение является примитивным типом):

is_defined($body.properties.desired.telemetryConfig.sendFrequency)

Запрос на основе двойника устройства или модуля

Маршрутизация сообщений позволяет запрашивать теги и свойства двойника двойника устройства или модуля , которые являются объектами JSON. В следующем примере показан двойник устройства с тегами и свойствами:

{
    "tags": { 
        "deploymentLocation": { 
            "building": "43", 
            "floor": "1" 
        } 
    }, 
    "properties": { 
        "desired": { 
            "telemetryConfig": { 
                "sendFrequency": "5m" 
            }, 
            "$metadata" : {...}, 
            "$version": 1 
        }, 
        "reported": { 
            "telemetryConfig": { 
                "sendFrequency": "5m", 
                "status": "success" 
            },
            "batteryLevel": 55, 
            "$metadata" : {...}, 
            "$version": 4 
        } 
    } 
}

Примечание.

Модули не наследуют теги двойника соответствующих устройств. Запросы двойников для сообщений, поступающих из модулей устройств (например, из модулей IoT Edge) к двойнику модуля, а не к соответствующему двойнику устройства.

Выражения запросов двойников

Запрос к двойнику устройства или двойнику модуля должен быть префиксирован.$twin Выражение запроса также может объединять тег двойника или ссылку на свойство со ссылкой на текст, ссылку на свойства системы сообщений или ссылку на свойства приложения сообщения. Рекомендуется использовать уникальные имена в тегах и свойствах, так как запрос не учитывает регистр. Эта рекомендация применяется как к двойникам устройств, так и к двойникам модулей. Кроме того, рекомендуется избегать использования twinимен свойств , $twinbodyили $body в качестве имен свойств. Например, следующие примеры являются допустимыми выражениями запросов:

$twin.properties.desired.telemetryConfig.sendFrequency = '5m'

$body.Weather.Temperature = 50 AND $twin.properties.desired.telemetryConfig.sendFrequency = '5m'

$twin.tags.deploymentLocation.floor = 1

Ограничения

Запросы маршрутизации не поддерживают использование в именах свойств, пути текста сообщения или пути двойника устройства или модуля пробелов и следующих символов: ()<>@,;:\"/?={}

Следующие шаги

Дополнительные сведения о маршрутизации сообщений.
Руководство по маршрутизации сообщений.

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