Delen via

Declaratie-instructie queryparameters

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

Query's die naar Kusto worden verzonden, kunnen een set naam- of waardeparen bevatten. The pairs are called query parameters, together with the query text itself. 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.

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.

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.

Syntax

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

Learn more about syntax conventions.

Parameters

Name Type Required Description
Name1 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.

Note

  • 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.

Example

In de voorbeelden in deze sectie ziet u hoe u de syntaxis kunt gebruiken om aan de slag te gaan.

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. Mogelijk moet u de tabelnaam in de voorbeeldquery wijzigen zodat deze overeenkomt met de tabel in uw werkruimte.

Queryparameters declareren

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.

de query uitvoeren

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

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 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).