IoT 中心消息路由查询语法

消息路由使用户能够将不同的数据类型（即设备遥测消息、设备生命周期事件和设备孪生更改事件）路由到各个终结点。 此外，还可以在路由此数据之前对其应用丰富查询，以接收对你而言重要的数据。 本文介绍 IoT 中心消息路由查询语言，并提供一些常见的查询模式。

消息路由允许你查询消息属性和消息正文以及设备孪生标记和设备孪生属性。 如果消息正文不是 JSON，则消息路由仍可路由消息，但查询不能应用于消息正文。 查询被描述为布尔表达式，其中的布尔值 true 使查询成功并路由所有传入数据，而布尔值 false 使查询失败且不会路由数据。 如果表达式计算结果为 null 或未定义，则将其视为 false，并将在 IoT 中心路由资源日志中生成错误。 查询语法必须正确，才能保存和计算路由。

基于消息属性的消息路由查询

IoT 中心为所有设备到云的消息传送定义了常见格式，以便实现跨协议互操作性。 IoT 中心采用以下 JSON 表示形式的消息。 为所有用户添加系统属性并标识消息的内容。 用户可以有选择地向消息添加应用程序属性。 我们建议使用唯一的属性名称，因为 IoT 中心设备到云消息传递不区分大小写。 例如，如果有多个具有相同名称的属性，IoT 中心将仅发送其中一个属性。

{ 
  "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}}" 
  } 
} 

系统属性

系统属性有助于标识消息的内容和源。

如创建和读取 IoT 中心消息中所述，一条消息中还有其他系统属性。 除了上一表中的上述属性外，还可以查询 connectionDeviceId、connectionModuleId。

应用程序属性

应用程序属性是用户定义的字符串，可以添加到消息。 这些字段是可选的。

查询表达式

对消息系统属性的查询需要以 $ 符号为前缀。 对应用程序属性的查询使用其名称进行访问，而且不应以 $ 符号为前缀。 如果应用程序属性名称以 $ 开头，则 IoT 中心将在系统属性中搜索它，如果找不到，再在应用程序属性中查找。 例如：

查询系统属性 contentEncoding

$contentEncoding = 'UTF-8'

查询应用程序属性 processingPath：

processingPath = 'hot'

若要组合这些查询，可以使用布尔表达式和函数：

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

表达式和条件中显示了支持的运算符和函数的完整列表。

基于消息正文的消息路由查询

若要启用对消息正文的查询，消息应采用以 UTF-8、UTF-16 或 UTF-32 编码的 JSON 格式。 在系统属性中，contentType 必须设置为 application/JSON，而 contentEncoding 则设置为一个受支持的 UTF 编码。 如果未指定这些属性，IoT 中心将不会计算消息正文的查询表达式。

下面的示例演示如何创建具有正确格式和编码 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);
});

查询表达式

对消息正文的查询需要以 $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'

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

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

$body[0] = 'Feb'

基于设备孪生的消息路由查询

通过消息路由，可以查询设备孪生标记和属性，这些是 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、$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 

限制

路由查询不支持在属性名称、消息正文路径或设备/模块孪生路径中使用空格或以下任何字符：()<>@,;:\"/?={}。

后续步骤

• 了解消息路由。
• 尝试消息路由教程。