Declaratie-instructie queryparameters

Artikel
01/20/2025

Van toepassing op: ✅Microsoft Fabric✅Azure Data Explorer✅Azure Monitor✅Microsoft Sentinel-

Query's die naar Kusto worden verzonden, kunnen een set naam- of waardeparen bevatten. De paren worden queryparametersgenoemd, samen met de querytekst zelf. De query kan verwijzen naar een of meer waarden door namen en typen op te geven in een declaratie-instructie van queryparameters.

Queryparameters hebben twee hoofdgebruiken:

Als beschermingsmechanisme tegen injectieaanvallen.
Als een manier om query's te parameteriseren.

Clienttoepassingen die door de gebruiker geleverde invoer combineren in query's die ze vervolgens naar Kusto verzenden, moeten het mechanisme gebruiken om te beschermen tegen het Kusto-equivalent van SQL-injectie-aanvallen.

Queryparameters declareren

Als u wilt verwijzen naar queryparameters, de querytekst of functies die worden gebruikt, moet u eerst declareren welke queryparameter wordt gebruikt. Voor elke parameter geeft de declaratie de naam en het scalaire type op. Optioneel kan de parameter ook een standaardwaarde hebben. De standaardwaarde wordt gebruikt als de aanvraag geen concrete waarde voor de parameter biedt. Kusto parseert vervolgens de waarde van de queryparameter volgens de normale parseringsregels voor dat type.

Syntaxis

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

Meer informatie over syntaxisconventies.

Parameters

Naam	Type	Vereist	Beschrijving
naam1	`string`	✔️	De naam van een queryparameter die in de query wordt gebruikt.
Type1-	`string`	✔️	Het bijbehorende type, zoals `string` of `datetime`. De waarden die door de gebruiker worden opgegeven, worden gecodeerd als tekenreeksen. De juiste parseringsmethode wordt toegepast op de queryparameter om een sterk getypte waarde op te halen.
DefaultValue1-	`string`		Een standaardwaarde voor de parameter. Deze waarde moet een letterlijke waarde van het juiste scalaire type zijn.

Notitie

Net zoals door de gebruiker gedefinieerde functies, kunnen queryparameters van het type dynamic geen standaardwaarden hebben.
Laten, instellen en tabellaire instructies worden samengevoegd/gescheiden door een puntkomma, anders worden ze niet beschouwd als onderdeel van dezelfde query.

Voorbeeld

In het helpclusteris er een Samples database met een StormEvents tabel.

de query uitvoeren

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

uitvoer

EpisodeId	EventType	totalInjuries
12459	Winterweer	137
10477	Overmatige hitte	200
10391	Hitte	187
10217	Overmatige hitte	422
10217	Overmatige hitte	519

Queryparameters opgeven in een clienttoepassing

De namen en waarden van queryparameters worden geleverd als string waarden door de toepassing die de query maakt. Er mag geen naam worden herhaald.

De interpretatie van de waarden wordt uitgevoerd volgens de declaratie-instructie queryparameters. Elke waarde wordt geparseerd alsof deze een letterlijke waarde is in de hoofdtekst van een query. Het parseren wordt uitgevoerd op basis van het type dat is opgegeven door de declaratie-instructie queryparameters.

REST API

Queryparameters worden geleverd door clienttoepassingen via de properties-site van het JSON-object van de aanvraagbody, in een geneste eigenschapszak met de naam Parameters. Hier volgt bijvoorbeeld de hoofdtekst van een REST API-aanroep naar Kusto die de leeftijd van een bepaalde gebruiker berekent, waarschijnlijk door de toepassing te laten vragen om de verjaardag van de gebruiker.

{
    "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 SDK's

Zie Queryparameters gebruiken om gebruikersinvoer te beveiligenvoor meer informatie over het opgeven van de namen en waarden van queryparameters bij het gebruik van Kusto clientbibliotheken.

Kusto.Explorer

Als u de queryparameters wilt instellen die worden verzonden bij het indienen van een aanvraag naar de service, gebruikt u het queryparameters pictogram 'wrench' (ALT + P).

Delen via