查詢參數宣告陳述式
傳送至 Kusto 的查詢可能包含一組名稱或值組。 這兩組與查詢文字本身一同稱為查詢參數。 查詢可能會在查詢參數宣告陳述式中指定名稱和類型,以參考一或多個值。
查詢參數有兩個主要用途:
- 做為針對插入式攻擊的防護機制。
- 做為參數化查詢的方法。
尤其是,在查詢中將使用者提供的輸入結合到 Kusto 的用戶端應用程式,應該使用機制來防止對等 SQL 插入式攻擊的 Kusto。
宣告查詢參數
若要參考查詢參數、查詢文字或其使用的函式,必須先宣告所使用的查詢參數。 針對每個參數,宣告會提供名稱和純量類型。 或者,參數也可以有預設值。 如果要求未提供參數的具體值,就會使用預設值。 然後,Kusto 會根據該類型的一般剖析規則,來剖析查詢參數的值。
語法
declare
query_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 監視器不支援這項功能
意見反應
https://aka.ms/ContentUserFeedback。
即將登場:在 2024 年,我們將逐步淘汰 GitHub 問題作為內容的意見反應機制,並將它取代為新的意見反應系統。 如需詳細資訊,請參閱:提交並檢視相關的意見反應