Linguaggio di query dell'hub IoT per dispositivi gemelli, processi e routing di messaggiIoT Hub query language for device twins, jobs, and message routing

L'hub IoT offre un linguaggio simile a SQL avanzato per recuperare informazioni su dispositivi gemelli, processi e routing di messaggi.IoT Hub provides a powerful SQL-like language to retrieve information regarding device twins and jobs, and message routing. Questo articolo contiene:This article presents:

  • Un'introduzione alle principali funzionalità del linguaggio di query dell'hub IoTAn introduction to the major features of the IoT Hub query language, and
  • La descrizione dettagliata del linguaggioThe detailed description of the language.

Query del dispositivo gemelloDevice twin queries

I dispositivi gemelli possono contenere oggetti JSON arbitrari come tag e proprietà.Device twins can contain arbitrary JSON objects as both tags and properties. L'hub IoT consente di effettuare una query dei dispositivi gemelli come singolo documento JSON contenente tutte le informazioni sui dispositivi gemelli.IoT Hub enables you to query device twins as a single JSON document containing all device twin information. Si supponga, ad esempio, che i dispositivi gemelli dell'hub IoT abbiano la struttura seguente:Assume, for instance, that your IoT hub device twins have the following structure:

{
    "deviceId": "myDeviceId",
    "etag": "AAAAAAAAAAc=",
    "tags": {
        "location": {
            "region": "US",
            "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
        }
    }
}

L'hub IoT espone i dispositivi gemelli come raccolta di documenti denominata devices.IoT Hub exposes the device twins as a document collection called devices. Quindi la query seguente recupera l'intero set di dispositivi:So the following query retrieves the whole set of device twins:

SELECT * FROM devices

Nota

Gli SDK dell'hub IoT supportano il paging di risultati di grandi dimensioni.Azure IoT SDKs support paging of large results.

L'hub IoT consente di recuperare i dispositivi gemelli applicando filtri con condizioni arbitrarie.IoT Hub allows you to retrieve device twins filtering with arbitrary conditions. Ad esempio, per ricevere dispositivi gemelli in cui il tag location.region è impostato suUS usare la query seguente:For instance, to receive device twins where the location.region tag is set to US use the following query:

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

Sono supportati anche operatori booleani e confronti aritmetici.Boolean operators and arithmetic comparisons are supported as well. Ad esempio, per recuperare dispositivi gemelli che si trovano negli Stati Uniti e configurati per inviare ogni minuto al massimo i dati di telemetria, usare la query seguente:For example, to retrieve device twins located in the US and configured to send telemetry less than every minute use the following query:

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

Per praticità, è anche possibile usare costanti di matrice con gli operatori IN e NIN (non in).As a convenience, it is also possible to use array constants with the IN and NIN (not in) operators. Ad esempio, per recuperare dispositivi gemelli che segnalano connettività Wi-Fi o cablata, usare la query seguente: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']

È spesso necessario identificare tutti i dispositivi gemelli che contengono una proprietà specifica.It is often necessary to identify all device twins that contain a specific property. L'hub IoT supporta la funzione is_defined() per questo scopo.IoT Hub supports the function is_defined() for this purpose. Ad esempio, per recuperare dispositivi gemelli che definiscono la proprietà connectivity, usare la query seguente:For instance, to retrieve device twins that define the connectivity property use the following query:

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

Per informazioni di riferimento complete sulle funzionalità di filtro, vedere la sezione Clausola WHERE.Refer to the WHERE clause section for the full reference of the filtering capabilities.

Sono supportati anche il raggruppamento e le aggregazioni.Grouping and aggregations are also supported. Ad esempio, per trovare il numero di dispositivi in ogni stato di configurazione di telemetria, usare la query seguente: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

Questa query di raggruppamento restituisce un risultato simile all'esempio seguente.This grouping query would return a result similar to the following example. In questo caso i tre dispositivi segnalano che la configurazione è riuscita, due stanno ancora applicando la configurazione e uno ha segnalato un errore.Here, three devices report successful configuration, two are still applying the configuration, and one reported an error.

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

Esempio in C#C# example

La funzionalità di query viene esposta dall'SDK del servizio C# nella classe RegistryManager.The query functionality is exposed by the C# service SDK in the RegistryManager class. Ecco un esempio di una query semplice: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
    }
}

Si noti come venga creata un'istanza dell'oggetto query con dimensioni della pagina (fino a 100) e quindi si possano recuperare più pagine chiamando più volte i metodi GetNextAsTwinAsync.Note how the query object is instantiated with a page size (up to 100), and then multiple pages can be retrieved by calling the GetNextAsTwinAsync methods multiple times. Si noti che l'oggetto query espone più Next, a seconda dell'opzione di deserializzazione richiesta dalla query, ad esempio se devono essere usati oggetti dispositivi gemelli, oggetti processo oppure il normale codice JSON quando si ricorre alle proiezioni.Note that the query object exposes multiple **Next**, depending on the deserialization option required by the query, such as device twin or job objects, or plain JSON to be used when using projections.

Esempio di Node. jsNode.js example

La funzionalità di query viene esposta da SDK per i servizi IoT di Azure per Node.js nell'oggetto Registro.The query functionality is exposed by the Azure IoT service SDK for Node.js in the Registry object. Ecco un esempio di una query semplice: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);

Si noti come venga creata un'istanza dell'oggetto query con dimensioni della pagina (fino a 100) e quindi si possano recuperare più pagine chiamando più volte i metodi nextAsTwin.Note how the query object is instantiated with a page size (up to 100), and then multiple pages can be retrieved by calling the nextAsTwin methods multiple times. Si noti che l'oggetto query espone più next, a seconda dell'opzione di deserializzazione richiesta dalla query, ad esempio se devono essere usati oggetti dispositivi gemelli, oggetti processo oppure il normale codice JSON quando si ricorre alle proiezioni.Note that the query object exposes multiple **next**, depending on the deserialization option required by the query, such as device twin or job objects, or plain JSON to be used when using projections.

LimitazioniLimitations

Importante

I risultati della query possono avere qualche minuto di ritardo rispetto ai valori più recenti nei dispositivi gemelli.Query results can have a few minutes of delay with respect to the latest values in device twins. Se si eseguono query su singoli dispositivi gemelli in base all'D, è sempre preferibile usare l'API di recupero di dispositivi gemelli, che contiene i valori più recenti e ha soglie di limitazione più alte.If querying individual device twins by id, it is always preferable to use the retrieve device twin API, which always contains the latest values and has higher throttling limits.

I confronti sono attualmente supportati solo tra tipi primitivi (non oggetti), ad esempio ... WHERE properties.desired.config = properties.reported.config è supportato solo se tali proprietà hanno valori primitivi.Currently, 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.

Introduzione alle query dei processiGet started with jobs queries

I processi consentono di eseguire operazioni su set di dispositivi.Jobs provide a way to execute operations on sets of devices. Ogni dispositivo gemello contiene le informazioni dei processi di cui fa parte in una raccolta denominata jobs.Each device twin contains the information of the jobs of which it is part in a collection called jobs. La struttura logica è la seguente.Logically,

{
    "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
            }
        },
        ...
    ]
}

Attualmente è possibile effettuare una query di questa raccolta come devices.jobs nel linguaggio di query dell'hub IoT.Currently, this collection is queryable as devices.jobs in the IoT Hub query language.

Importante

Attualmente la proprietà dei processi non viene mai restituita quando si eseguono query sui dispositivi gemelli (ad esempio query che contengono 'FROM devices').Currently, the jobs property is never returned when querying device twins (that is, queries that contains 'FROM devices'). È possibile accedervi direttamente solo con le query che usano FROM devices.jobs.It can only be accessed directly with queries using FROM devices.jobs.

Ad esempio, per ottenere tutti i processi (passati e pianificati) che influiscono su un singolo dispositivo, è possibile usare la query seguente: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'

Si noti come questa query indichi lo stato specifico del dispositivo (e verosimilmente la risposta del metodo diretto) di ogni processo restituito.Note how this query provides the device-specific status (and possibly the direct method response) of each job returned. È anche possibile applicare un filtro con condizioni booleane arbitrarie a tutte le proprietà degli oggetti della raccolta devices.jobs.It is also possible to filter with arbitrary Boolean conditions on all object properties in the devices.jobs collection. Ad esempio, per recuperare tutti i processi di aggiornamento per dispositivi gemelli completi che sono stati creati dopo il mese di settembre 2016 per un dispositivo specifico, usare la query seguente: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'

È anche possibile recuperare i risultati per ogni dispositivo di un singolo processo.You can also retrieve the per-device outcomes of a single job.

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

LimitazioniLimitations

Attualmente le query su devices.jobs non supportano:Currently, queries on devices.jobs do not support:

  • Proiezioni, quindi è possibile solo SELECT *.Projections, therefore only SELECT * is possible.
  • Condizioni che fanno riferimento al dispositivo gemello oltre alle proprietà del processo (vedere sezione precedente).Conditions that refer to the device twin in addition to job properties (see the preceding section).
  • Esecuzione di aggregazioni, ad esempio count, avg, group by.Performing aggregations, such as count, avg, group by.

Espressioni di query per route di messaggi da dispositivo a cloudDevice-to-cloud message routes query expressions

Usando i route da dispositivo a cloud, è possibile configurare l'hub IoT per l'invio di messaggi da dispositivo a cloud a endpoint diversi in base alle espressioni valutate nei singoli messaggi.Using device-to-cloud routes, you can configure IoT Hub to dispatch device-to-cloud messages to different endpoints based on expressions evaluated against individual messages.

La condizione route usa lo stesso linguaggio di query dell'hub IoT come condizione nelle query gemelle e di processo.The route condition uses the same IoT Hub query language as conditions in twin and job queries. Le condizioni di routing vengono valutate nel corpo e nelle intestazioni del messaggio.Route conditions are evaluated on the message headers and body. L'espressione di query del routing potrebbe riguardare solo le intestazioni dei messaggi, solo il corpo del messaggio oppure entrambi.Your routing query expression may involve only message headers, only the message body, or both message headers and message body. Per il routing dei messaggi, l'hub IoT presuppone uno schema specifico per le intestazioni e il corpo del messaggio.IoT Hub assumes a specific schema for the headers and message body in order to route messages. Nelle sezioni seguenti vengono descritti i requisiti dell'hub IoT per un routing corretto.The following sections describe what is required for IoT Hub to properly route.

Routing delle intestazioni dei messaggiRouting on message headers

L'hub IoT presuppone la seguente rappresentazione JSON delle intestazioni dei messaggi per il routing dei messaggi:IoT Hub assumes the following JSON representation of message headers for message routing:

{
    "$messageId": "",
    "$enqueuedTime": "",
    "$to": "",
    "$expiryTimeUtc": "",
    "$correlationId": "",
    "$userId": "",
    "$ack": "",
    "$connectionDeviceId": "",
    "$connectionDeviceGenerationId": "",
    "$connectionAuthMethod": "",
    "$content-type": "",
    "$content-encoding": "",

    "userProperty1": "",
    "userProperty2": ""
}

Le proprietà di sistema del messaggio hanno come prefisso il simbolo '$'.Message system properties are prefixed with the '$' symbol. Alle proprietà utente si accede sempre con il relativo nome.User properties are always accessed with their name. Se un nome di proprietà utente coincide con una proprietà di sistema, ad esempio $to, la proprietà dell'utente verrà recuperata con l'espressione $to.If a user property name happens to coincide with a system property (such as $to), the user property will be retrieved with the $to expression. È sempre possibile accedere alle proprietà di sistema con le parentesi {}: ad esempio, l'espressione {$to} consente di accedere alla proprietà di sistema to.You can always access the system property using brackets {}: for instance, you can use the expression {$to} to access the system property to. I nomi di proprietà tra parentesi recuperano sempre le corrispondenti proprietà di sistema.Bracketed property names always retrieve the corresponding system property.

Si ricordi che nei nomi delle proprietà viene fatta distinzione tra maiuscole e minuscole.Remember that property names are case insensitive.

Nota

Tutte le proprietà dei messaggi sono stringhe.All message properties are strings. Le proprietà di sistema, come descritto nella guida per gli sviluppatori, non sono attualmente disponibili per l'uso nelle query.System properties, as described in the developer guide, are currently not available to use in queries.

Ad esempio, se si utilizza una proprietà messageType, è possibile indirizzare tutti i dati di telemetria a un endpoint e tutti gli avvisi a un altro endpoint.For example, if you use a messageType property, you might want to route all telemetry to one endpoint, and all alerts to another endpoint. È possibile scrivere l'espressione seguente per indirizzare i dati di telemetria:You can write the following expression to route the telemetry:

messageType = 'telemetry'

L'espressione seguente per indirizzare i messaggi di avviso:And the following expression to route the alert messages:

messageType = 'alert'

Sono supportate anche le espressioni e le funzione booleane.Boolean expressions and functions are also supported. Questa funzionalità consente di distinguere i vari livelli di gravità, ad esempio:This feature enables you to distinguish between severity level, for example:

messageType = 'alerts' AND as_number(severity) <= 2

Fare riferimento alla sezione Espressioni e condizioni per l'elenco completo delle funzioni e degli operatori supportati.Refer to the Expression and conditions section for the full list of supported operators and functions.

Routing del corpo dei messaggiRouting on message bodies

L'hub IoT può eseguire il routing solo in base al contenuto del corpo del messaggio se il corpo del messaggio è formato correttamente con codifica JSON in UTF-8, UTF-16 o UTF-32.IoT Hub can only route based on message body contents if the message body is properly formed JSON encoded in either UTF-8, UTF-16, or UTF-32. Impostare il tipo di contenuto del messaggio su application/json e la codifica del contenuto su una delle codifiche UTF supportate nelle intestazioni del messaggio.Set the content type of the message to application/json and the content encoding to one of the supported UTF encodings in the message headers. Se una delle intestazioni viene omessa, l'hub IoT non tenterà di valutare alcuna espressione di query che coinvolga il corpo rispetto al messaggio.If either of the headers is not specified, IoT Hub will not attempt to evaluate any query expression involving the body against the message. Se il messaggio non è un messaggio JSON oppure se il messaggio non specifica il tipo di contenuto e la codifica del contenuto, è comunque possibile usare il routing dei messaggi per indirizzare il messaggio in base alle intestazioni.If your message is not a JSON message, or if the message does not specify the content type and content encoding, you may still use message routing to route the message based on the message headers.

È possibile usare $body nell'espressione di query per indirizzare il messaggio.You can use $body in the query expression to route the message. Nell'espressione di query è possibile usare un riferimento semplice al corpo, un riferimento a una matrice del corpo o riferimenti multipli al corpo.You can use a simple body reference, body array reference, or multiple body references in the query expression. L'espressione di query può anche combinare un riferimento al corpo con un riferimento all'intestazione del messaggio.Your query expression can also combine a body reference with a message header reference. Ad esempio, di seguito sono riportate tutte le espressioni di query valide:For example, the following are all valid query expressions:

$body.message.Weather.Location.State = 'WA'
$body.Weather.HistoricalData[0].Month = 'Feb'
$body.Weather.Temperature = 50 AND $body.message.Weather.IsEnabled
length($body.Weather.Location.State) = 2
$body.Weather.Temperature = 50 AND Status = 'Active'

Nozioni di base di una query dell'hub IoTBasics of an IoT Hub query

Ogni query dell'hub IoT è costituita da una clausola SELECT e da una clausola FROM e dalle clausole facoltative WHERE e GROUP BY.Every IoT Hub query consists of SELECT and FROM clauses, with optional WHERE and GROUP BY clauses. Ogni query viene eseguita su una raccolta di documenti JSON, ad esempio dispositivi gemelli.Every query is run on a collection of JSON documents, for example device twins. La clausola FROM indica la raccolta di documenti in cui eseguire l'iterazione (devices o devices.jobs).The FROM clause indicates the document collection to be iterated on (devices or devices.jobs). Viene quindi applicato il filtro nella clausola WHERE.Then, the filter in the WHERE clause is applied. Nel caso delle aggregazioni, i risultati di questo passaggio vengono raggruppati come specificato nella clausola GROUP BY e, per ogni gruppo, viene generata una riga come specificato nella clausola SELECT.With aggregations, the results of this step are grouped as specified in the GROUP BY clause and, 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>]

Clausola FROMFROM clause

La clausola FROM <from_specification> può avere solo due valori: FROM devices, per effettuare una query dei dispositivi gemelli, o FROM devices.jobs, per effettuare una query dei dettagli di ogni dispositivo.The FROM <from_specification> clause can assume only two values: FROM devices to query device twins, or FROM devices.jobs to query job per-device details.

Clausola WHEREWHERE clause

La clausola WHERE <filter_condition> è facoltativaThe WHERE <filter_condition> clause is optional. e specifica una o più condizioni che i documenti JSON della raccolta FROM devono soddisfare per essere inclusi come parte del risultato.It specifies one or more conditions that the JSON documents in the FROM collection must satisfy to be included as part of the result. Per essere incluso nel risultato, qualsiasi documento JSON deve restituire "true" per le condizioni specificate.Any JSON document must evaluate the specified conditions to "true" to be included in the result.

Le condizioni consentite vengono descritte nella sezione Espressioni e condizioni.The allowed conditions are described in section Expressions and conditions.

Clausola SELECTSELECT clause

La clausola SELECT <select_list> è obbligatoria e specifica quali valori vengono recuperati dalla query.The SELECT <select_list> is mandatory and specifies what values are retrieved from the query. Specifica i valori JSON da usare per generare nuovi oggetti JSON.It specifies the JSON values to be used to generate new JSON objects. Per ogni elemento del subset filtrato (e facoltativamente raggruppato) della raccolta FROM, la fase di proiezione genera un nuovo oggetto JSON, costruito con i valori specificati nella clausola SELECT.For each element of the filtered (and optionally grouped) subset of the FROM collection, the projection phase generates a new JSON object, constructed with the values specified in the SELECT clause.

Questa è la sintassi della clausola 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 si riferisce alle proprietà del documento JSON nella raccolta FROM.Attribute_name refers to any property of the JSON document in the FROM collection. Alcuni esempi di clausola SELECT sono disponibili nella sezione Introduzione alle query dei dispositivi gemelli.Some examples of SELECT clauses can be found in the Getting started with device twin queries section.

Attualmente le clausole di selezione diverse da SELECT* sono supportate solo nelle query aggregate in dispositivi gemelli.Currently, selection clauses different than SELECT* are only supported in aggregate queries on device twins.

Clausola GROUP BYGROUP BY clause

La clausola GROUP BY <group_specification> è un passaggio facoltativo che può essere eseguito dopo aver applicato il filtro specificato nella clausola WHERE e prima della proiezione specificata in SELECT.The GROUP BY <group_specification> clause is an optional step that can be executed after the filter specified in the WHERE clause, and before the projection specified in the SELECT. Raggruppa i documenti in base al valore di un attributo.It groups documents based on the value of an attribute. Questi gruppi vengono usati per generare valori aggregati come specificato nella clausola SELECT.These groups are used to generate aggregated values as specified in the SELECT clause.

Ecco un esempio di query che usa 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

La sintassi formale di 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 si riferisce alle proprietà del documento JSON nella raccolta FROM.Attribute_name refers to any property of the JSON document in the FROM collection.

Attualmente la clausola GROUP BY è supportata solo quando si effettua una query sui dispositivi gemelli.Currently, the GROUP BY clause is only supported when querying device twins.

Espressioni e condizioniExpressions and conditions

In generale, un'espressione:At a high level, an expression:

  • Restituisce un'istanza di un tipo JSON, ad esempio un operatore booleano, un numero, una stringa, una matrice o un oggetto.Evaluates to an instance of a JSON type (such as Boolean, number, string, array, or object).
  • Viene definita modificando i dati provenienti dalle costanti e dal documento JSON dei dispositivi, che usano funzioni e operatori predefiniti.Is defined by manipulating data coming from the device JSON document and constants using built-in operators and functions.

Le condizioni sono espressioni che restituiscono un valore booleano.Conditions are expressions that evaluate to a Boolean. Una costante diversa dal valore booleano true viene considerata false (inclusi null, undefined, qualsiasi istanza di oggetto o matrice, qualsiasi stringa e ovviamente il valore booleano false).Any constant different than Boolean true is considered as false (including null, undefined, any object or array instance, any string, and clearly the Boolean false).

La sintassi delle espressioni è: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>]+ ']'

Per informazioni sul significato di ogni simbolo nella sintassi delle espressioni, fare riferimento alla tabella seguente:To understand what each symbol in the expressions syntax stands for, refer to the following table:

SimboloSymbol DefinizioneDefinition
attribute_nameattribute_name Proprietà del documento JSON nella raccolta FROM.Any property of the JSON document in the FROM collection.
binary_operatorbinary_operator Operatore binario elencato nella sezione Operatori.Any binary operator listed in the Operators section.
function_namefunction_name Funzioni elencate nella sezione Funzioni.Any function listed in the Functions section.
decimal_literaldecimal_literal Float espresso in una notazione decimale.A float expressed in decimal notation.
hexadecimal_literalhexadecimal_literal Numero espresso dalla stringa "0x" seguita da una stringa costituita da cifre esadecimali.A number expressed by the string ‘0x’ followed by a string of hexadecimal digits.
string_literalstring_literal I valori letterali stringa sono stringhe Unicode rappresentate da una sequenza di zero o più caratteri Unicode o sequenze di escape.String literals are Unicode strings represented by a sequence of zero or more Unicode characters or escape sequences. I valori letterali stringa sono racchiusi tra virgolette singole o virgolette doppie.String literals are enclosed in single quotes or double quotes. Caratteri di escape consentiti: \', \", \\, \uXXXX per i caratteri Unicode definiti da 4 cifre esadecimali.Allowed escapes: \', \", \\, \uXXXX for Unicode characters defined by 4 hexadecimal digits.

OperatoriOperators

Sono supportati gli operatori seguenti:The following operators are supported:

FamigliaFamily OperatoriOperators
AritmeticoArithmetic +, -, *, /, %+, -, *, /, %
LogicoLogical AND, OR, NOTAND, OR, NOT
ConfrontoComparison =, !=, <, >, <=, >=, <>=, !=, <, >, <=, >=, <>

FunzioniFunctions

Quando si eseguono query gemelle e di processi l'unica funzione supportata è:When querying twins and jobs the only supported function is:

FunzioneFunction DescrizioneDescription
IS_DEFINED(proprietà)IS_DEFINED(property) Restituisce un valore booleano che indica se alla proprietà è stata assegnato un valore (incluso null).Returns a Boolean indicating if the property has been assigned a value (including null).

Nelle condizioni di route, sono supportate le funzioni matematiche seguenti:In routes conditions, the following math functions are supported:

FunzioneFunction DescrizioneDescription
ABS(x)ABS(x) Restituisce il valore assoluto (positivo) dell'espressione numerica specificata.Returns the absolute (positive) value of the specified numeric expression.
EXP(x)EXP(x) Restituisce il valore esponente dell'espressione numerica specificata (e^x).Returns the exponential value of the specified numeric expression (e^x).
POWER(x,y)POWER(x,y) Restituisce il valore dell'espressione specificata alla potenza specificata (x^y).Returns the value of the specified expression to the specified power (x^y).
SQUARE(x)SQUARE(x) Restituisce il quadrato del valore numerico specificato.Returns the square of the specified numeric value.
CEILING(x)CEILING(x) Restituisce il più piccolo valore integer maggiore di o uguale all'espressione numerica specificata.Returns the smallest integer value greater than, or equal to, the specified numeric expression.
FLOOR(x)FLOOR(x) Restituisce il valore integer più alto, minore di o uguale all'espressione numerica specificata.Returns the largest integer less than or equal to the specified numeric expression.
SIGN(x)SIGN(x) Restituisce il segno positivo (+1), zero (0) o negativo (-1) dell'espressione numerica specificata.Returns the positive (+1), zero (0), or negative (-1) sign of the specified numeric expression.
SQRT(x)SQRT(x) Restituisce la radice quadrata del valore numerico specificato.Returns the square root of the specified numeric value.

Nelle condizioni di route, sono supportate le funzioni di trasmissione e controllo seguenti:In routes conditions, the following type checking and casting functions are supported:

FunzioneFunction DescrizioneDescription
AS_NUMBERAS_NUMBER Converte la stringa di input in un numero.Converts the input string to a number. noop se l'input è un numero, Undefined se la stringa non rappresenta un numero.noop if input is a number; Undefined if string does not represent a number.
IS_ARRAYIS_ARRAY Restituisce un valore booleano che indica se il tipo di espressione specificata è una matrice.Returns a Boolean value indicating if the type of the specified expression is an array.
IS_BOOLIS_BOOL Restituisce un valore booleano che indica se il tipo di espressione specificata è un valore booleano.Returns a Boolean value indicating if the type of the specified expression is a Boolean.
IS_DEFINEDIS_DEFINED Restituisce un valore booleano che indica se alla proprietà è stata assegnato un valore.Returns a Boolean indicating if the property has been assigned a value.
IS_NULLIS_NULL Restituisce un valore booleano che indica se il tipo di espressione specificata è nulla.Returns a Boolean value indicating if the type of the specified expression is null.
IS_NUMBERIS_NUMBER Restituisce un valore booleano che indica se il tipo di espressione specificata è un numero.Returns a Boolean value indicating if the type of the specified expression is a number.
IS_OBJECTIS_OBJECT Restituisce un valore booleano che indica se il tipo di espressione specificata è un oggetto JSON.Returns a Boolean value indicating if the type of the specified expression is a JSON object.
IS_PRIMITIVEIS_PRIMITIVE Restituisce un valore booleano che indica se il tipo di espressione specificata è un primitivo (stringa, valore booleano, numerico o null).Returns a Boolean value indicating if the type of the specified expression is a primitive (string, Boolean, numeric or null).
IS_STRINGIS_STRING Restituisce un valore booleano che indica se il tipo di espressione specificata è una stringa.Returns a Boolean value indicating if the type of the specified expression is a string.

Nelle condizioni di route, sono supportate le funzioni di stringa seguenti:In routes conditions, the following string functions are supported:

FunzioneFunction DescrizioneDescription
CONCAT(x, y, …)CONCAT(x, y, …) Restituisce una stringa che rappresenta il risultato della concatenazione di due o più valori di stringa.Returns a string that is the result of concatenating two or more string values.
LENGTH(x)LENGTH(x) Restituisce il numero di caratteri dell'espressione stringa specificata.Returns the number of characters of the specified string expression.
LOWER(x)LOWER(x) Restituisce un'espressione stringa dopo la conversione di dati in caratteri maiuscoli in caratteri minuscoli.Returns a string expression after converting uppercase character data to lowercase.
UPPER(x)UPPER(x) Restituisce un'espressione stringa dopo aver convertito i caratteri minuscoli in caratteri maiuscoli.Returns a string expression after converting lowercase character data to uppercase.
SUBSTRING (stringa, avvio [, lunghezza])SUBSTRING(string, start [, length]) Restituisce parte di un'espressione stringa a partire dalla posizione in base al carattere zero specificata e continua fino alla lunghezza specificata o alla fine della stringa.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(stringa, frammento)INDEX_OF(string, fragment) Restituisce la posizione iniziale della prima occorrenza della seconda stringa di espressione all'interno della prima espressione stringa specificata oppure -1 se la stringa non viene trovata.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) Restituisce un valore booleano che indica se la prima espressione stringa inizia con il secondo.Returns a Boolean indicating whether the first string expression starts with the second.
ENDS_WITH(x, y)ENDS_WITH(x, y) Restituisce un valore booleano che indica se la prima espressione stringa termina con il secondo.Returns a Boolean indicating whether the first string expression ends with the second.
CONTAINS(x,y)CONTAINS(x,y) Restituisce un valore booleano che indica se la prima espressione stringa contiene il secondo.Returns a Boolean indicating whether the first string expression contains the second.

Passaggi successiviNext steps

Informazioni su come eseguire query nelle app usando gli SDK dell'hub IoT.Learn how to execute queries in your apps using Azure IoT SDKs.