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

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

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

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

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

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

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

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

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

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

Для запроса свойства системы кодировки содержимого:

$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 для .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 
        } 
    } 
} 

Выражения параллельных запросов

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

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

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

$twin.tags.deploymentLocation.floor = 1 

Ограничения

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

Дальнейшие шаги

• Узнайте о маршрутизации сообщений.
• Ознакомьтесь с руководством по маршрутизации сообщений.