Applies to: ✅Microsoft Fabric✅Azure Data Explorer✅Azure Monitor✅Microsoft Sentinel
Kusto に送信されるクエリには、名前と値のペアのセットが含まれる場合があります。 The pairs are called query parameters, together with the query text itself. クエリは、クエリ パラメーター宣言ステートメントで名前と型を指定することで、1 つ以上の 値を参照できます。
クエリ パラメーターには、主に次の 2 つの用途があります。
- インジェクション攻撃に対する保護メカニズムとして。
- クエリをパラメーター化する方法として。
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.
クエリ パラメーターの宣言
クエリ パラメーター、使用するクエリ テキスト、または関数を参照するには、まず、使用するクエリ パラメーターを宣言する必要があります。 各パラメーターに対して、 宣言は名前とスカラー型を提供します。 必要に応じて、 パラメーターに既定値を指定することもできます。 既定値は、要求がパラメーターの具象値を提供しない場合に使用されます。 その後、Kusto は、その型の通常の解析規則に従って、クエリ パラメーターの値を解析します。
Syntax
declare
query_parameters
(
Name1:Type1 [=DefaultValue1] [,...] );
Learn more about syntax conventions.
Parameters
| Name | タイプ | Required | Description |
|---|---|---|---|
| Name1 | string |
✔️ | クエリで使用されるクエリ パラメーターの名前。 |
| Type1 | string |
✔️ |
stringやdatetimeなどの対応する型。 ユーザーによって提供される値は文字列としてエンコードされます。 クエリ パラメーターに適切な解析メソッドが適用され、厳密に型指定された値が取得されます。 |
| DefaultValue1 | string |
パラメーターの既定値。 この値は、適切なスカラー型のリテラルである必要があります。 |
Note
-
ユーザー 定義関数と同様に、
dynamic型のクエリ パラメーターに既定値を指定することはできません。 - let ステートメント、set ステートメント、および表形式ステートメントは、セミコロンを使用して結合、または区切られます。そうしないと、それらは同じクエリの一部と見なされません。
Example
このセクションの例では、構文を使用して作業を開始する方法を示します。
The examples in this article use publicly available tables in the help cluster, such as the
StormEventstable in the Samples database.
The examples in this article use publicly available tables, such as the
Weathertable in the Weather analytics sample gallery. ワークスペース内のテーブルと一致するように、クエリ例のテーブル名を変更する必要がある場合があります。
クエリ パラメーターを宣言する
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.
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 |
クライアント アプリケーションでクエリ パラメーターを指定する
クエリ パラメーターの名前と値は、クエリを行うアプリケーションによって string 値として提供されます。 名前を繰り返し使用する必要はありません。
値の解釈は、クエリ パラメーター宣言ステートメントに従って行われます。 すべての値は、クエリの本文内のリテラルである場合と同様に解析されます。 解析は、クエリ パラメーター宣言ステートメントで指定された型に従って行われます。
REST API
クエリ パラメーターは、要求本文 の JSON オブジェクトの properties スロットを介して、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 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).