Freigeben über

Deklarationsanweisung für Abfrageparameter

Applies to: ✅Microsoft Fabric✅Azure Data Explorer✅Azure Monitor✅Microsoft Sentinel

An Kusto gesendete Abfragen können eine Gruppe von Namen- oder Wertpaaren enthalten. The pairs are called query parameters, together with the query text itself. Die Abfrage kann auf einen oder mehrere Werte verweisen, indem Namen und Typ angegeben werden, in einer Abfrageparameterdeklarationsanweisung.

Abfrageparameter haben zwei Hauptverwendungen:

  • Als Schutzmechanismus gegen Einfügungsangriffe.
  • Als Methode zum Parametrisieren von Abfragen.

In particular, client applications that combine user-provided input in queries that they then send to Kusto should use the mechanism to protect against the Kusto equivalent of SQL Injection attacks.

Deklarieren von Abfrageparametern

Um auf Abfrageparameter zu verweisen, muss der verwendete Abfragetext oder die verwendete Funktion zuerst deklarieren, welcher Abfrageparameter verwendet wird. Für jeden Parameter stellt die Deklaration den Namen und den skalaren Typ bereit. Optional kann der Parameter auch einen Standardwert aufweisen. Der Standardwert wird verwendet, wenn die Anforderung keinen konkreten Wert für den Parameter bereitstellt. Kusto analysiert dann den Wert des Abfrageparameters gemäß seinen normalen Analyseregeln für diesen Typ.

Syntax

declare query_parameters ( Name1:Type1 [=DefaultValue1] [,...] );

Learn more about syntax conventions.

Parameters

Name Type Required Description
Name1 string ✔️ Der Name eines Abfrageparameters, der in der Abfrage verwendet wird.
Type1 string ✔️ Der entsprechende Typ, z string . B. oder datetime. Die vom Benutzer bereitgestellten Werte werden als Zeichenfolgen codiert. Die entsprechende Analysemethode wird auf den Abfrageparameter angewendet, um einen stark typierten Wert abzurufen.
DefaultValue1 string Ein Standardwert für den Parameter. Dieser Wert muss ein Literal des entsprechenden skalaren Typs sein.

Note

  • Wie benutzerdefinierte Funktionen können Abfrageparameter des Typs dynamic keine Standardwerte aufweisen.
  • Let, set, and tabular statements are strung together/separated by a semicolon, otherwise they will not be considered part of the same query.

Example

Die Beispiele in diesem Abschnitt zeigen, wie Sie die Syntax verwenden, um Ihnen den Einstieg zu erleichtern.

The examples in this article use publicly available tables in the help cluster, such as the StormEvents table in the Samples database.

The examples in this article use publicly available tables, such as the Weather table in the Weather analytics sample gallery. Möglicherweise müssen Sie den Tabellennamen in der Beispielabfrage so ändern, dass er der Tabelle in Ihrem Arbeitsbereich entspricht.

Deklarieren von Abfrageparametern

This query retrieves storm events from the StormEvents table where the total number of direct and indirect injuries exceeds a specified threshold (default is 90). It then projects the EpisodeId, EventType, and the total number of injuries for each of these events.

Abfrage ausführen

declare query_parameters(maxInjured:long = 90);
StormEvents 
| where InjuriesDirect + InjuriesIndirect > maxInjured
| project EpisodeId, EventType, totalInjuries = InjuriesDirect + InjuriesIndirect

Output

EpisodeId EventType totalInjuries
12459 Winter Weather 137
10477 Excessive Heat 200
10391 Heat 187
10217 Excessive Heat 422
10217 Excessive Heat 519

Angeben von Abfrageparametern in einer Clientanwendung

Die Namen und Werte von Abfrageparametern werden von der Anwendung, die die Abfrage erstellt, als string Werte bereitgestellt. Es kann kein Name wiederholt werden.

Die Interpretation der Werte erfolgt gemäß der Abfrageparameterdeklarationsanweisung. Jeder Wert wird analysiert, als wäre er ein Literal im Textkörper einer Abfrage. Die Analyse erfolgt entsprechend dem Typ, der durch die Abfrageparameterdeklarationsanweisung angegeben wird.

REST API

Abfrageparameter werden von Clientanwendungen über den properties Platz des JSON-Objekts des Anforderungstexts in einem geschachtelten Eigenschaftenbehälter bereitgestellt Parameters. Hier ist beispielsweise der Textkörper eines REST-API-Aufrufs an Kusto, der das Alter eines Benutzers berechnet, vermutlich indem die Anwendung nach dem Geburtstag des Benutzers fragt.

{
    "ns": null,
    "db": "myDB",
    "csl": "declare query_parameters(birthday:datetime); print strcat(\"Your age is: \", tostring(now() - birthday))",
    "properties": "{\"Options\":{},\"Parameters\":{\"birthday\":\"datetime(1970-05-11)\",\"courses\":\"dynamic(['Java', 'C++'])\"}}"
}

Kusto SDKs

To learn how to provide the names and values of query parameters when using Kusto client libraries, see Use query parameters to protect user input.

Kusto.Explorer

To set the query parameters sent when making a request to the service, use the Query parameters "wrench" icon (ALT + P).