Deklarationsanweisung für Abfrageparameter

Artikel
07/04/2024

An Kusto gesendete Abfragen können eine Gruppe von Namen- oder Wertpaaren enthalten. Die Paare werden zusammen mit dem Abfragetext selbst als Abfrageparameter bezeichnet. 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.

Insbesondere Clientanwendungen, die vom Benutzer bereitgestellte Eingaben in Abfragen kombinieren, die sie dann an Kusto senden, sollten den Mechanismus verwenden, um vor dem Kusto-Äquivalent von SQL Injection-Angriffen zu schützen.

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

declarequery_parameters ( Name1 Typ1 : [= DefaultValue1] [,...]);

Erfahren Sie mehr über Syntaxkonventionen.

Parameter

Name	Type	Erforderlich	Beschreibung
Name1	`string`	✔️	Der Name eines Abfrageparameters, der in der Abfrage verwendet wird.
Typ1	`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.

Hinweis

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.

Beispiel

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	Winterwetter	137
10477	Excessive Heat	200
10391	Hitze	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

Informationen zum Bereitstellen der Namen und Werte von Abfrageparametern bei Verwendung von Kusto-Clientbibliotheken finden Sie unter Verwenden von Abfrageparametern zum Schutz der Benutzereingabe.

Kusto.Explorer

Um die Abfrageparameter festzulegen, die beim Senden einer Anforderung an den Dienst gesendet werden, verwenden Sie das Abfrageparametersymbol "Wrench" (ALTP + ).

Diese Funktion wird in Azure Monitor nicht unterstützt.

Freigeben über