Синтаксис запросов маршрутизации сообщений центра Интернета вещей

Статья
03/18/2023

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

Примечание

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

Маршрутизация сообщений позволяет запрашивать свойства сообщения, текст сообщения, теги и свойства двойников устройств. Если текст сообщения не в формате JSON, маршрутизация сообщений по-прежнему может маршрутизировать сообщение, но запросы не могут применяться к тексту сообщения. Запросы описываются как логические выражения, где при значении true запрос выполняется успешно и направляет все входящие данные; В противном случае запрос завершается сбоем, а входящие данные не направляются. Если выражение принимает значение 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}}" 
  } 
}

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

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

Свойство	Тип	Описание
сontentType	строка	Пользователь указывает тип содержимого сообщений. Чтобы разрешить выполнение запросов к тексту сообщения, это значение должно иметь значение `application/JSON`.
contentEncoding	строка	Пользователь указывает тип кодирования сообщений. Если свойству contentType присвоено значение `application/JSON`, то допустимые значения: `UTF-8`, `UTF-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, выполните следующие действия:

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 IoT для .NET. Этот пример используется в руководстве по маршрутизации сообщений. Файл Program.cs также имеет метод с именем ReadOneRowFromFile, который считывает один из закодированных файлов, декодирует его и записывает обратно в 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в качестве имен свойств , $twin, bodyили $body . Например, следующие примеры являются допустимыми выражениями запроса:

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

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

$twin.tags.deploymentLocation.floor = 1

Ограничения

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

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

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