查詢參數宣告陳述式

發行項
01/23/2024

傳送至 Kusto 的查詢可能包含一組名稱或值組。這兩組與查詢文字本身一同稱為查詢參數。查詢可能會在查詢參數宣告陳述式中指定名稱和類型，以參考一或多個值。

查詢參數有兩個主要用途：

做為針對插入式攻擊的防護機制。
做為參數化查詢的方法。

尤其是，在查詢中將使用者提供的輸入結合到 Kusto 的用戶端應用程式，應該使用機制來防止對等 SQL 插入式攻擊的 Kusto。

宣告查詢參數

若要參考查詢參數、查詢文字或其使用的函式，必須先宣告所使用的查詢參數。針對每個參數，宣告會提供名稱和純量類型。或者，參數也可以有預設值。如果要求未提供參數的具體值，就會使用預設值。然後，Kusto 會根據該類型的一般剖析規則，來剖析查詢參數的值。

語法

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

深入瞭解語法慣例。

參數

名稱	類型	必要	Description
Name1	`string`	✔️	查詢中使用的查詢參數名稱。
Type1	`string`	✔️	對應的型別，例如 `string` 或 `datetime`。使用者所提供的值會編碼為字串。適當的剖析方法會套用至查詢參數，以取得強型別值。
DefaultValue1	`string`		參數的預設值。這個值必須是適當純量類型的常值。

注意

如同使用者定義函式，類型 dynamic 的查詢參數不能有預設值。
Let、set 和 tabular 陳述式會串聯在一起/以分號分割，否則不會視為相同查詢的一部份。

範例

執行查詢

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

輸出

EpisodeId	EventType	totalInjuries
12459	冬季天氣	137
10477	過度熱度	200
10391	Heat	187
10217	過度熱度	422
10217	過度熱度	519

在用戶端應用程式中指定查詢參數

查詢參數的名稱和值會由進行查詢的應用程式以 string 值的形式提供。名稱不可重複。

值的解釋是根據查詢參數宣告陳述式來完成。每個值都會剖析為查詢主體中的常值。剖析是根據查詢參數宣告陳述式所指定的型別來完成。

REST API

查詢參數是由用戶端應用程式透過 properties 插槽要求主體 JSON 物件的位置，在名為 Parameters 的嵌套屬性包中提供。例如，以下是 Kusto 呼叫的 REST API 主體，其會計算某些使用者的年齡，而這是因為應用程式要求使用者的生日。

{
    "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

若要瞭解如何在使用 Kusto 用戶端連結庫時提供查詢參數的名稱和值，請參閱使用查詢參數來保護使用者輸入。

Kusto.Explorer

若要設定向服務提出要求時傳送的查詢參數，請使用查詢參數「扳手」圖示 (ALT + P)。

Azure 監視器不支援這項功能