用于设备和模块孪生、作业和消息路由的 IoT 中心查询语言IoT Hub query language for device and module twins, jobs, and message routing

IoT 中心提供类似于 SQL 的强大语言,用于检索有关设备孪生作业消息路由的信息。IoT Hub provides a powerful SQL-like language to retrieve information regarding device twins and jobs, and message routing. 本文内容:This article presents:

  • IoT 中心查询语言的主要功能简介,以及An introduction to the major features of the IoT Hub query language, and
  • 语言的详细说明。The detailed description of the language. 有关用于消息路由的查询语言的详细信息,请参阅消息路由中的查询For details on query language for message routing, see queries in message routing.

Note

本文中提到的某些功能(例如云到设备消息传递、设备孪生、设备管理)仅在 IoT 中心的标准层中提供。Some of the features mentioned in this article, like cloud-to-device messaging, device twins, and device management, are only available in the standard tier of IoT hub. 有关基本和标准 IoT 中心层的详细信息,请参阅如何选择合适的 IoT 中心层For more information about the basic and standard IoT Hub tiers, see How to choose the right IoT Hub tier.

设备和模块孪生查询Device and module twin queries

设备孪生模块孪生可以包含标记和属性形式的任意 JSON 对象。Device twins and module twins can contain arbitrary JSON objects as both tags and properties. 通过 IoT 中心,可将设备孪生和模块孪生作为包含所有孪生信息的单个 JSON 文档进行查询。IoT Hub enables you to query device twins and module twins as a single JSON document containing all twin information.

例如,假定 IoT 中心设备孪生具有以下结构(模块孪生将与之类似,只是具有附加的 moduleId):Assume, for instance, that your IoT hub device twins have the following structure (module twin would be similar just with an additional moduleId):

{
    "deviceId": "myDeviceId",
    "etag": "AAAAAAAAAAc=",
    "status": "enabled",
    "statusUpdateTime": "0001-01-01T00:00:00",    
    "connectionState": "Disconnected",    
    "lastActivityTime": "0001-01-01T00:00:00",
    "cloudToDeviceMessageCount": 0,
    "authenticationType": "sas",    
    "x509Thumbprint": {    
        "primaryThumbprint": null,
        "secondaryThumbprint": null
    },
    "version": 2,
    "tags": {
        "location": {
            "region": "CN",
            "plant": "Redmond43"
        }
    },
    "properties": {
        "desired": {
            "telemetryConfig": {
                "configId": "db00ebf5-eeeb-42be-86a1-458cccb69e57",
                "sendFrequencyInSecs": 300
            },
            "$metadata": {
            ...
            },
            "$version": 4
        },
        "reported": {
            "connectivity": {
                "type": "cellular"
            },
            "telemetryConfig": {
                "configId": "db00ebf5-eeeb-42be-86a1-458cccb69e57",
                "sendFrequencyInSecs": 300,
                "status": "Success"
            },
            "$metadata": {
            ...
            },
            "$version": 7
        }
    }
}

设备孪生查询Device twin queries

IoT 中心将设备孪生公开为名为设备的文档集合。IoT Hub exposes the device twins as a document collection called devices. 例如,以下查询将检索设备孪生的整个集:For example, the following query retrieves the whole set of device twins:

SELECT * FROM devices

Note

Azure IoT SDK 支持将大型结果分页。Azure IoT SDKs support paging of large results.

IoT 中心允许使用任意条件检索设备孪生筛选结果。IoT Hub allows you to retrieve device twins filtering with arbitrary conditions. 例如,若要接收 location.region 标记设置为 CN 的设备孪生,请使用以下查询:For instance, to receive device twins where the location.region tag is set to CN use the following query:

SELECT * FROM devices
WHERE tags.location.region = 'CN'

还支持布尔运算符和算术比较。Boolean operators and arithmetic comparisons are supported as well. 例如,若要接收位于中国且配置为每隔不到一分钟就发送遥测数据的设备孪生,请使用以下查询:For example, to retrieve device twins located in the CN and configured to send telemetry less than every minute use the following query:

SELECT * FROM devices
WHERE tags.location.region = 'CN'
    AND properties.reported.telemetryConfig.sendFrequencyInSecs >= 60

方便起见,还可将数组常量与 INNIN(不包含)运算符结合使用。As a convenience, it is also possible to use array constants with the IN and NIN (not in) operators. 例如,若要检索报告了 WiFi 或有线连接的设备孪生,请使用以下查询:For instance, to retrieve device twins that report WiFi or wired connectivity use the following query:

SELECT * FROM devices
WHERE properties.reported.connectivity IN ['wired', 'wifi']

通常需要它才能识别包含特定属性的所有设备孪生。It is often necessary to identify all device twins that contain a specific property. 为此,IoT 中心支持函数 is_defined()IoT Hub supports the function is_defined() for this purpose. 例如,若要检索定义了 connectivity 属性的设备孪生,请使用以下查询:For instance, to retrieve device twins that define the connectivity property use the following query:

SELECT * FROM devices
WHERE is_defined(properties.reported.connectivity)

有关筛选功能的完整参考,请参阅 WHERE 子句部分。Refer to the WHERE clause section for the full reference of the filtering capabilities.

此外还支持分组与聚合。Grouping and aggregations are also supported. 例如,若要查明每个遥测配置中的设备计数,请使用以下查询:For instance, to find the count of devices in each telemetry configuration status use the following query:

SELECT properties.reported.telemetryConfig.status AS status,
    COUNT() AS numberOfDevices
FROM devices
GROUP BY properties.reported.telemetryConfig.status

此分组查询将返回类似于以下示例的结果:This grouping query would return a result similar to the following example:

[
    {
        "numberOfDevices": 3,
        "status": "Success"
    },
    {
        "numberOfDevices": 2,
        "status": "Pending"
    },
    {
        "numberOfDevices": 1,
        "status": "Error"
    }
]

在此示例中,三个设备报告了成功配置,两个仍在应用配置,一个报告了错误。In this example, three devices reported successful configuration, two are still applying the configuration, and one reported an error.

投影查询允许开发人员仅返回他们所关注的属性。Projection queries allow developers to return only the properties they care about. 例如,若要检索所有已断开连接设备的上次活动时间,请使用以下查询:For example, to retrieve the last activity time of all disconnected devices use the following query:

SELECT LastActivityTime FROM devices WHERE status = 'enabled'

模块孪生查询Module twin queries

对模块孪生进行查询类似于对设备孪生进行查询,但使用不同的集合/命名空间,即不从设备进行查询,而是从 devices.modules 进行查询:Querying on module twins is similar to querying on device twins, but using a different collection/namespace; instead of from devices, you query from devices.modules:

SELECT * FROM devices.modules

不允许在 devices 与 devices.modules 集合之间进行联接。We don't allow join between the devices and devices.modules collections. 如果要跨设备查询模块孪生,则需要基于标记来执行此操作。If you want to query module twins across devices, you do it based on tags. 以下查询将返回所有设备中具有扫描状态的所有模块孪生:This query will return all module twins across all devices with the scanning status:

SELECT * FROM devices.modules WHERE properties.reported.status = 'scanning'

以下查询将仅返回指定的设备子集上具有扫描状态的所有模块孪生:This query will return all module twins with the scanning status, but only on the specified subset of devices:

SELECT * FROM devices.modules 
  WHERE properties.reported.status = 'scanning' 
  AND deviceId IN ['device1', 'device2']

C# 示例C# example

查询功能由 C# 服务 SDK 在 RegistryManager 类中公开 。The query functionality is exposed by the C# service SDK in the RegistryManager class.

下面是一个简单的查询示例:Here is an example of a simple query:

var query = registryManager.CreateQuery("SELECT * FROM devices", 100);
while (query.HasMoreResults)
{
    var page = await query.GetNextAsTwinAsync();
    foreach (var twin in page)
    {
        // do work on twin object
    }
}

“查询”对象实例化为页面大小(最大为 100) 。The query object is instantiated with a page size (up to 100). 然后通过多次调用 GetNextAsTwinAsync 方法来检索多个页面 。Then multiple pages are retrieved by calling the GetNextAsTwinAsync methods multiple times.

查询对象公开多个“下一步”值,具体取决于该查询所需的反序列化选项 。The query object exposes multiple Next values, depending on the deserialization option required by the query. 例如,设备孪生或作业对象,或使用投影时的普通 JSON。For example, device twin or job objects, or plain JSON when using projections.

Node.js 示例Node.js example

查询功能由适用于 Node.js 的 Azure IoT 服务 SDK 在 Registry 对象中公开 。The query functionality is exposed by the Azure IoT service SDK for Node.js in the Registry object.

下面是一个简单的查询示例:Here is an example of a simple query:

var query = registry.createQuery('SELECT * FROM devices', 100);
var onResults = function(err, results) {
    if (err) {
        console.error('Failed to fetch the results: ' + err.message);
    } else {
        // Do something with the results
        results.forEach(function(twin) {
            console.log(twin.deviceId);
        });

        if (query.hasMoreResults) {
            query.nextAsTwin(onResults);
        }
    }
};
query.nextAsTwin(onResults);

“查询”对象实例化为页面大小(最大为 100) 。The query object is instantiated with a page size (up to 100). 然后通过多次调用 nextAsTwin 方法来检索多个页面 。Then multiple pages are retrieved by calling the nextAsTwin method multiple times.

查询对象公开多个“下一步”值,具体取决于该查询所需的反序列化选项 。The query object exposes multiple Next values, depending on the deserialization option required by the query. 例如,设备孪生或作业对象,或使用投影时的普通 JSON。For example, device twin or job objects, or plain JSON when using projections.

限制Limitations

Important

关于设备孪生中的最新值,查询结果可能有几分钟的延迟。Query results can have a few minutes of delay with respect to the latest values in device twins. 如果按 ID 查询单个设备孪生,请使用获取孪生 REST APIIf querying individual device twins by ID, use the get twin REST API. 此 API 始终返回最新值,并具有更高的节流限制。This API always returns the latest values and has higher throttling limits. 可以直接发出 REST API 或使用 Azure IoT 中心服务 SDK 之一中的等效功能。You can issue the REST API directly or use the equivalent functionality in one of the Azure IoT Hub Service SDKs.

目前,仅支持在基元类型(无对象)之间进行比较,例如,仅在这些属性具有基元值时才支持 ... WHERE properties.desired.config = properties.reported.configCurrently, comparisons are supported only between primitive types (no objects), for instance ... WHERE properties.desired.config = properties.reported.config is supported only if those properties have primitive values.

作业查询入门Get started with jobs queries

使用作业可对一组设备执行操作。Jobs provide a way to execute operations on sets of devices. 每个设备孪生包含名为 作业的集合中该设备参与的作业的信息。Each device twin contains the information of the jobs of which it is part in a collection called jobs.

{
    "deviceId": "myDeviceId",
    "etag": "AAAAAAAAAAc=",
    "tags": {
        ...
    },
    "properties": {
        ...
    },
    "jobs": [
        {
            "deviceId": "myDeviceId",
            "jobId": "myJobId",
            "jobType": "scheduleTwinUpdate",
            "status": "completed",
            "startTimeUtc": "2016-09-29T18:18:52.7418462",
            "endTimeUtc": "2016-09-29T18:20:52.7418462",
            "createdDateTimeUtc": "2016-09-29T18:18:56.7787107Z",
            "lastUpdatedDateTimeUtc": "2016-09-29T18:18:56.8894408Z",
            "outcome": {
                "deviceMethodResponse": null
            }
        },
        ...
    ]
}

目前,可以使用 IoT 中心查询语言以 devices.jobs 形式查询此集合。Currently, this collection is queryable as devices.jobs in the IoT Hub query language.

Important

目前,查询设备孪生时不会返回作业属性。Currently, the jobs property is never returned when querying device twins. 即包含“FROM 设备”的查询。That is, queries that contain 'FROM devices'. 该作业属性仅可通过使用 FROM devices.jobs 的查询直接访问。The jobs property can only be accessed directly with queries using FROM devices.jobs.

例如,若要获取影响单个设备的所有作业(过去和计划的作业),可以使用以下查询:For instance, to get all jobs (past and scheduled) that affect a single device, you can use the following query:

SELECT * FROM devices.jobs
WHERE devices.jobs.deviceId = 'myDeviceId'

请注意此查询如何提供每个返回的作业的设备特定状态(可能还会提供直接方法响应)。Note how this query provides the device-specific status (and possibly the direct method response) of each job returned. 还可针对 devices.jobs 集合中的所有对象属性,使用任意布尔条件进行筛选。It is also possible to filter with arbitrary Boolean conditions on all object properties in the devices.jobs collection. 若要为特定设备检索在 2016 年 9 月之后创建的所有已完成的设备孪生更新作业,请使用以下查询:For instance, to retrieve all completed device twin update jobs that were created after September 2016 for a specific device, use the following query:

SELECT * FROM devices.jobs
WHERE devices.jobs.deviceId = 'myDeviceId'
    AND devices.jobs.jobType = 'scheduleTwinUpdate'
    AND devices.jobs.status = 'completed'
    AND devices.jobs.createdTimeUtc > '2016-09-01'

还可以检索单个作业在每个设备上的结果。You can also retrieve the per-device outcomes of a single job.

SELECT * FROM devices.jobs
WHERE devices.jobs.jobId = 'myJobId'

限制Limitations

目前,对 devices.jobs 的查询不支持:Currently, queries on devices.jobs do not support:

  • 投影,因此仅可使用 SELECT *Projections, therefore only SELECT * is possible.
  • 引用设备孪生和作业属性的条件(参见上一节)。Conditions that refer to the device twin in addition to job properties (see the preceding section).
  • 执行聚合,例如 count、avg、group by。Performing aggregations, such as count, avg, group by.

IoT 中心查询基础知识Basics of an IoT Hub query

每个 IoT 中心查询都包括 SELECT 和 FROM 子句,以及可选的 WHERE 和 GROUP BY 子句。Every IoT Hub query consists of SELECT and FROM clauses, with optional WHERE and GROUP BY clauses. 每个查询针对 JSON 文档的集合(例如,设备孪生)运行。Every query is run on a collection of JSON documents, for example device twins. FROM 子句指示要迭代的文档集合(devicesdevices.modulesdevices.jobs)。The FROM clause indicates the document collection to be iterated on (devices, devices.modules, or devices.jobs). 然后,应用 WHERE 子句中的筛选器。Then, the filter in the WHERE clause is applied. 使用聚合时,将按 GROUP BY 子句中的指定对此步骤的结果分组。With aggregations, the results of this step are grouped as specified in the GROUP BY clause. 对于每组,将按照 SELECT 子句中的指定生成一行。For each group, a row is generated as specified in the SELECT clause.

SELECT <select_list>
FROM <from_specification>
[WHERE <filter_condition>]
[GROUP BY <group_specification>]

FROM 子句FROM clause

FROM <from_specification> 子句只能假定三个值:用于查询设备孪生的“FROM devices”、用于查询模块孪生的“FROM devices.modules”或用于根据设备详情查询作业“FROM devices.jobs” 。The FROM <from_specification> clause can assume only three values: FROM devices to query device twins, FROM devices.modules to query module twins, or FROM devices.jobs to query job per-device details.

WHERE 子句WHERE clause

WHERE <filter_condition> 子句是可选的。The WHERE <filter_condition> clause is optional. 它指定要将 FROM 集合中的 JSON 文档内含在结果中时需满足的一项或多项条件。It specifies one or more conditions that the JSON documents in the FROM collection must satisfy to be included as part of the result. 任何 JSON 文档必须将指定的条件求值为“true”才能包含在结果中。Any JSON document must evaluate the specified conditions to "true" to be included in the result.

表达式和条件部分介绍了允许的条件。The allowed conditions are described in section Expressions and conditions.

SELECT 子句SELECT clause

SELECT <select_list> 是必需的,用于指定要通过查询检索的值。The SELECT <select_list> is mandatory and specifies what values are retrieved from the query. 它指定用于生成新 JSON 对象的 JSON 值。It specifies the JSON values to be used to generate new JSON objects. 对于 FROM 集合中已筛选子集(且可选择性分组)的每个元素,投影阶段将生成一个新 JSON 对象。For each element of the filtered (and optionally grouped) subset of the FROM collection, the projection phase generates a new JSON object. 使用 SELECT 子句中指定的值构造此对象。This object is constructed with the values specified in the SELECT clause.

SELECT 子句的语法如下:Following is the grammar of the SELECT clause:

    SELECT [TOP <max number>] <projection list>

    <projection_list> ::=
        '*'
        | <projection_element> AS alias [, <projection_element> AS alias]+

    <projection_element> :==
        attribute_name
        | <projection_element> '.' attribute_name
        | <aggregate>

    <aggregate> :==
        count()
        | avg(<projection_element>)
        | sum(<projection_element>)
        | min(<projection_element>)
        | max(<projection_element>)

Attribute_name 引用 FROM 集合中 JSON 文档的任一属性。Attribute_name refers to any property of the JSON document in the FROM collection. 在“设备孪生查询入门”部分可以找到 SELECT 子句的一些示例。Some examples of SELECT clauses can be found in the Getting started with device twin queries section.

目前,仅支持在针对设备孪生执行的聚合查询中使用除 SELECT* 以外的选择子句。Currently, selection clauses different than SELECT* are only supported in aggregate queries on device twins.

GROUP BY 子句GROUP BY clause

GROUP BY <group_specification> 子句是可选步骤,可在 WHERE 子句中指定的筛选器后、在 SELECT 中指定的投影前执行该子句。The GROUP BY <group_specification> clause is an optional step that executes after the filter specified in the WHERE clause, and before the projection specified in the SELECT. 它根据属性值来分组文档。It groups documents based on the value of an attribute. 这些组用于生成 SELECT 子句中指定的聚合值。These groups are used to generate aggregated values as specified in the SELECT clause.

下面是使用 GROUP BY 的查询示例:An example of a query using GROUP BY is:

SELECT properties.reported.telemetryConfig.status AS status,
    COUNT() AS numberOfDevices
FROM devices
GROUP BY properties.reported.telemetryConfig.status

GROUP BY 的正式语法为:The formal syntax for GROUP BY is:

    GROUP BY <group_by_element>
    <group_by_element> :==
        attribute_name
        | < group_by_element > '.' attribute_name

Attribute_name 引用 FROM 集合中 JSON 文档的任一属性。Attribute_name refers to any property of the JSON document in the FROM collection.

目前,仅在查询设备孪生时才支持使用 GROUP BY 子句。Currently, the GROUP BY clause is only supported when querying device twins.

Important

术语 group 目前被视为查询中的特殊关键字。The term group is currently treated as a special keyword in queries. 如果你使用 group 作为属性名,请考虑使用双括号将其括起来以避免错误,例如 SELECT * FROM devices WHERE tags.[[group]].name = 'some_value'In case, you use group as your property name, consider surrounding it with double brackets to avoid errors, e.g., SELECT * FROM devices WHERE tags.[[group]].name = 'some_value'.

表达式和条件Expressions and conditions

从较高层面讲,表达式可以:At a high level, an expression:

  • 求值结果为 JSON 类型的实例(例如布尔值、数字、字符串、数组或对象)。Evaluates to an instance of a JSON type (such as Boolean, number, string, array, or object).
  • 由设备 JSON 文档中的操作数据以及使用内置运算符和函数的常量定义。Is defined by manipulating data coming from the device JSON document and constants using built-in operators and functions.

条件是求值为布尔值的表达式。Conditions are expressions that evaluate to a Boolean. 将任何不同于布尔值“true”的常数视为“false” 。Any constant different than Boolean true is considered as false. 此规则包括“Null”、“undefined”、任何对象或数组实例、任何字符串和布尔值“false” 。This rule includes null, undefined, any object or array instance, any string, and the Boolean false.

表达式的语法为:The syntax for expressions is:

    <expression> ::=
        <constant> |
        attribute_name |
        <function_call> |
        <expression> binary_operator <expression> |
        <create_array_expression> |
        '(' <expression> ')'

    <function_call> ::=
        <function_name> '(' expression ')'

    <constant> ::=
        <undefined_constant>
        | <null_constant>
        | <number_constant>
        | <string_constant>
        | <array_constant>

    <undefined_constant> ::= undefined
    <null_constant> ::= null
    <number_constant> ::= decimal_literal | hexadecimal_literal
    <string_constant> ::= string_literal
    <array_constant> ::= '[' <constant> [, <constant>]+ ']'

若要了解表达式语法中的每个符号表示什么,请参阅下表:To understand what each symbol in the expressions syntax stands for, refer to the following table:

符号Symbol 定义Definition
attribute_nameattribute_name FROM 集合中 JSON 文档的任一属性。Any property of the JSON document in the FROM collection.
binary_operatorbinary_operator 运算符部分列出的任意二进制运算符。Any binary operator listed in the Operators section.
function_namefunction_name 函数部分列出的任一函数。Any function listed in the Functions section.
decimal_literaldecimal_literal 以十进制表示法表示的浮点数。A float expressed in decimal notation.
hexadecimal_literalhexadecimal_literal 以字符串“0x”后接十六进制数字符串表示的数字。A number expressed by the string '0x' followed by a string of hexadecimal digits.
string_literalstring_literal 字符串文本是以零个或多个 Unicode 字符序列或转义符序列表示的 Unicode 字符串。String literals are Unicode strings represented by a sequence of zero or more Unicode characters or escape sequences. 字符串文本括在单引号或双引号中。String literals are enclosed in single quotes or double quotes. 允许的转义符:\'\"\\\uXXXX(由 4 个十六进制数字定义的 Unicode 字符)。Allowed escapes: \', \", \\, \uXXXX for Unicode characters defined by 4 hexadecimal digits.

运算符Operators

支持以下运算符:The following operators are supported:

系列Family 运算符Operators
算术Arithmetic +,-,*,/,%+,-,*,/,%
逻辑Logical AND、OR、NOTAND, OR, NOT
比较Comparison =、!=、<、>、<=、>=、<>=, !=, <, >, <=, >=, <>

函数Functions

查询克隆和作业时唯一受支持的函数是:When querying twins and jobs the only supported function is:

函数Function 说明Description
IS_DEFINED(property)IS_DEFINED(property) 返回一个布尔值,指示是否已向属性分配值(包括 null)。Returns a Boolean indicating if the property has been assigned a value (including null).

在路由情况下,支持以下数学函数:In routes conditions, the following math functions are supported:

函数Function 说明Description
ABS(x)ABS(x) 返回指定数值表达式的绝对(正)值。Returns the absolute (positive) value of the specified numeric expression.
EXP(x)EXP(x) 返回指定数值表达式 (e^x) 的指数值。Returns the exponential value of the specified numeric expression (e^x).
POWER(x,y)POWER(x,y) 返回指定表达式相对指定幂 (x^y) 的值。Returns the value of the specified expression to the specified power (x^y).
SQUARE(x)SQUARE(x) 返回指定数字值的平方。Returns the square of the specified numeric value.
CEILING(x)CEILING(x) 返回大于或等于指定数值表达式的最小整数值。Returns the smallest integer value greater than, or equal to, the specified numeric expression.
FLOOR(x)FLOOR(x) 返回小于或等于指定数值表达式的最大整数。Returns the largest integer less than or equal to the specified numeric expression.
SIGN(x)SIGN(x) 返回指定数值表达式的正数 (+1)、零 (0) 或负数 (-1)。Returns the positive (+1), zero (0), or negative (-1) sign of the specified numeric expression.
SQRT(x)SQRT(x) 返回指定数值的平方根。Returns the square root of the specified numeric value.

在路由情况下,支持以下检查和强制转换类型的函数:In routes conditions, the following type checking and casting functions are supported:

函数Function 说明Description
AS_NUMBERAS_NUMBER 将输入字符串转换为数字。Converts the input string to a number. 如果输入数字,则为 noop;如果字符串不表示数字,则为 Undefinednoop if input is a number; Undefined if string does not represent a number.
IS_ARRAYIS_ARRAY 返回一个布尔值,指示指定表达式类型是否为数组。Returns a Boolean value indicating if the type of the specified expression is an array.
IS_BOOLIS_BOOL 返回一个布尔值,指示指定表达式的类型是否为布尔表达式。Returns a Boolean value indicating if the type of the specified expression is a Boolean.
IS_DEFINEDIS_DEFINED 返回一个布尔,它指示属性是否已经分配了值。Returns a Boolean indicating if the property has been assigned a value. 仅当该值为基元类型时才支持此功能。This is supported only when the value is a primitive type. 基元类型包括字符串、布尔值、数字或 nullPrimitive types include string, Boolean, numeric, or null. 不支持日期/时间、对象类型和数组。DateTime, object types and arrays are not supported.
IS_NULLIS_NULL 返回一个布尔值,指示指定表达式的类型是否为 null。Returns a Boolean value indicating if the type of the specified expression is null.
IS_NUMBERIS_NUMBER 返回一个布尔值,指示指定表达式的类型是否为数字。Returns a Boolean value indicating if the type of the specified expression is a number.
IS_OBJECTIS_OBJECT 返回一个布尔值,指示指定表达式的类型是否为 JSON 对象。Returns a Boolean value indicating if the type of the specified expression is a JSON object.
IS_PRIMITIVEIS_PRIMITIVE 返回一个布尔值,指示指定表达式的类型是否为基元(字符串、布尔值、数字或 null)。Returns a Boolean value indicating if the type of the specified expression is a primitive (string, Boolean, numeric, or null).
IS_STRINGIS_STRING 返回一个布尔值,指示指定表达式的类型是否为字符串。Returns a Boolean value indicating if the type of the specified expression is a string.

在路由情况下,支持以下字符串函数:In routes conditions, the following string functions are supported:

函数Function 说明Description
CONCAT(x, y, …)CONCAT(x, y, …) 返回一个字符串,该字符串是连接两个或多个字符串值的结果。Returns a string that is the result of concatenating two or more string values.
LENGTH(x)LENGTH(x) 返回指定字符串表达式的字符数。Returns the number of characters of the specified string expression.
LOWER(x)LOWER(x) 返回在将大写字符数据转换为小写后的字符串表达式。Returns a string expression after converting uppercase character data to lowercase.
UPPER(x)UPPER(x) 返回在将小写字符数据转换为大写后的字符串表达式。Returns a string expression after converting lowercase character data to uppercase.
SUBSTRING(string, start [, length])SUBSTRING(string, start [, length]) 返回字符串表达式的部分内容,该内容起于指定字符从零开始的位置,继续到指定长度或字符串结尾。Returns part of a string expression starting at the specified character zero-based position and continues to the specified length, or to the end of the string.
INDEX_OF(string, fragment)INDEX_OF(string, fragment) 返回第一个指定的字符串表达式中第一次出现第二个字符串表达式的起始位置,如果未找到字符串,则返回 -1。Returns the starting position of the first occurrence of the second string expression within the first specified string expression, or -1 if the string is not found.
STARTS_WITH(x, y)STARTS_WITH(x, y) 返回一个布尔值,指示第一个字符串表达式是否以第二个字符串表达式开头。Returns a Boolean indicating whether the first string expression starts with the second.
ENDS_WITH(x, y)ENDS_WITH(x, y) 返回一个布尔值,指示第一个字符串表达式是否以第二个字符串表达式结尾。Returns a Boolean indicating whether the first string expression ends with the second.
CONTAINS(x,y)CONTAINS(x,y) 返回一个布尔值,该值指示第一个字符串表达式是否包含第二个字符串表达式。Returns a Boolean indicating whether the first string expression contains the second.

后续步骤Next steps

了解如何使用 Azure IoT SDK 在应用中执行查询。Learn how to execute queries in your apps using Azure IoT SDKs.