Declaratie-instructie queryparameters

  • Artikel

Query's die naar Kusto worden verzonden, kunnen een set naam- of waardeparen bevatten. De paren worden queryparameters genoemd, 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 voor queryparameters.

Queryparameters hebben twee belangrijke toepassingen:

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

Met name clienttoepassingen die door de gebruiker verstrekte invoer combineren in query's die ze vervolgens naar Kusto verzenden, moeten het mechanisme gebruiken om te beschermen tegen het Kusto-equivalent van SQL-injectieaanvallen .

Queryparameters declareren

Als u wilt verwijzen naar queryparameters, moet de querytekst of de functies die worden gebruikt, eerst declareren welke queryparameter wordt gebruikt. Voor elke parameter bevat de declaratie de naam en het scalaire type. 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 parseerregels voor dat type.

Syntax

declarequery_parameters(Naam1: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 parseermethode 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 als door de gebruiker gedefinieerde functies kunnen queryparameters van het type dynamic geen standaardwaarden hebben.
  • Let, set en tabellaire instructies worden aan elkaar gekoppeld/gescheiden door een puntkomma, anders worden ze niet beschouwd als onderdeel van dezelfde query.

Voorbeeld

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 Heat 187
10217 Overmatige hitte 422
10217 Overmatige hitte 519

Queryparameters opgeven in een clienttoepassing

De namen en waarden van queryparameters worden als string waarden opgegeven door de toepassing die de query maakt. De naam mag niet worden herhaald.

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

REST-API

Queryparameters worden geleverd door clienttoepassingen via de properties sleuf van het JSON-object van de aanvraagbody, in een geneste eigenschappenverzameling met de naam Parameters. Dit is bijvoorbeeld de hoofdtekst van een REST API-aanroep naar Kusto waarmee de leeftijd van een gebruiker wordt berekend, 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 beveiligen voor 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 bij de service, gebruikt u het pictogram 'Moersleutel' voor queryparameters (ALT + P).

Deze mogelijkheid wordt niet ondersteund in Azure Monitor