Deklarationsanweisung für Abfrageparameter

  • Artikel

An Kusto gesendete Abfragen können eine Reihe von Namens- oder Wertpaaren enthalten. Die Paare werden zusammen mit dem Abfragetext selbst als Abfrageparameter bezeichnet. Die Abfrage kann durch Angabe von Namen und Typ in einer Abfrageparameterdeklarationsanweisung auf einen oder mehrere Werte verweisen.

Abfrageparameter verwenden zwei Standard:

  • Als Schutzmechanismus gegen Injektionsangriffe.
  • Als Möglichkeit zum Parametrisieren von Abfragen.

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

Deklarieren von Abfrageparametern

Um auf Abfrageparameter zu verweisen, muss der abfragetext oder die funktionen, die er verwendet, zuerst deklarieren, welcher Abfrageparameter verwendet wird. Für jeden Parameter stellt die Deklaration den Namen und den Skalartyp 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:Type1 [=DefaultValue1] [,...] );

Erfahren Sie mehr über Syntaxkonventionen.

Parameter

Name Typ 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 typisierten Wert abzurufen.
DefaultValue1 string Ein Standardwert für den Parameter. Dieser Wert muss ein Literal des entsprechenden Skalartyps sein.

Hinweis

  • Wie benutzerdefinierte Funktionen können Abfrageparameter des Typs dynamic keine Standardwerte aufweisen.
  • Let-, set- und tabellarische Anweisungen werden durch ein Semikolon miteinander verknüpft bzw. getrennt. Andernfalls werden sie nicht als Teil derselben Abfrage betrachtet.

Beispiel

Abfrage ausführen

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

Ausgabe

EpisodeId EventType totalInjuries
12459 Winterwetter 137
10477 Übermäßige Hitze 200
10391 Hitze 187
10217 Übermäßige Hitze 422
10217 Übermäßige Hitze 519

Angeben von Abfrageparametern in einer Clientanwendung

Die Namen und Werte von Abfrageparametern werden von der abfragebereiten Anwendung als string Werte bereitgestellt. Es darf sich kein Name wiederholen.

Die Interpretation der Werte erfolgt gemäß der Deklarationsanweisung der Abfrageparameter. Jeder Wert wird so analysiert, als wäre er ein Literal im Text einer Abfrage. Die Analyse erfolgt gemäß dem Typ, der in der Deklarationsanweisung der Abfrageparameter angegeben wird.

REST-API

Abfrageparameter werden von Clientanwendungen über den properties Slot des JSON-Objekts des Anforderungstexts in einem geschachtelten Eigenschaftenbehälter namens Parametersbereitgestellt. Hier sehen Sie beispielsweise den Text 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 von Benutzereingaben.

Kusto.Explorer

Um die Abfrageparameter festzulegen, die beim Senden einer Anforderung an den Dienst gesendet werden, verwenden Sie das Symbol "Schraubenschlüssel" (ALT + P) für Abfrageparameter.

Diese Funktion wird in Azure Monitor nicht unterstützt.