查詢參數宣告語句

發行項
11/23/2024

適用於：✅Microsoft網狀架構✅Azure 數據 ✅總管 Azure 監視器 ✅Microsoft Sentinel

傳送至 Kusto 的查詢可能包含一組名稱或值組。配對稱為 查詢參數，以及查詢文字本身。查詢可以藉由在查詢參數宣告語句中指定名稱和類型來參考一或多個值。

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

作為防止插入式攻擊的保護機制。
做為參數化查詢的方式。

特別是，在查詢中結合使用者提供的輸入，然後傳送至 Kusto 的用戶端應用程式應該使用機制來防範對等 SQL 插入式攻擊的 Kusto。

宣告查詢參數

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

語法

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

深入瞭解語法慣例。

參數

姓名	類型	必要	描述
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	熱度	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

若要設定向服務提出要求時所傳送的查詢參數，請使用查詢參數「wrench」圖示（ALTP + ）。

共用方式為