クエリ パラメーター宣言ステートメント
適用対象: ✅Microsoft Fabric✅Azure データ エクスプローラー✅Azure Monitor✅Microsoft Sentinel
Kusto に送信されるクエリには、名前と値のペアのセットが含まれる場合があります。 ペアは、クエリ テキスト自体と共にクエリ パラメーターと呼ばれるものです。 クエリは、クエリ パラメーター宣言ステートメントで名前と型を指定することで、1 つ以上の 値を参照できます。
クエリ パラメーターには、主に次の 2 つの用途があります。
- インジェクション攻撃に対する保護メカニズムとして。
- クエリをパラメーター化する方法として。
特に、Kusto に送信するクエリでユーザー指定の入力を組み合わせるクライアント アプリケーションでは、Kusto のSQL インジェクション攻撃と同等のものから保護するために、このメカニズムを使用する必要があります。
クエリ パラメーターの宣言
クエリ パラメーター、使用するクエリ テキスト、または関数を参照するには、まず、使用するクエリ パラメーターを宣言する必要があります。 各パラメーターに対して、 宣言は名前とスカラー型を提供します。 必要に応じて、 パラメーターに既定値を指定することもできます。 既定値は、要求がパラメーターの具象値を提供しない場合に使用されます。 その後、Kusto は、その型の通常の解析規則に従って、クエリ パラメーターの値を解析します。
構文
declarequery_parameters ( Name1 : Type1 [= DefaultValue1] [,...]);
構文規則について詳しく知る。
パラメーター
| 件名 | タイプ | Required | 説明 |
|---|---|---|---|
| Name1 | string |
✔️ | クエリで使用されるクエリ パラメーターの名前。 |
| Type1 | string |
✔️ | stringやdatetimeなどの対応する型。 ユーザーによって提供される値は文字列としてエンコードされます。 クエリ パラメーターに適切な解析メソッドが適用され、厳密に型指定された値が取得されます。 |
| DefaultValue1 | string |
パラメーターの既定値。 この値は、適切なスカラー型のリテラルである必要があります。 |
Note
- ユーザー 定義関数と同様に、
dynamic型のクエリ パラメーターに既定値を指定することはできません。 - let ステートメント、set ステートメント、および表形式ステートメントは、セミコロンを使用して結合、または区切られます。そうしないと、それらは同じクエリの一部と見なされません。
例
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
クエリ パラメーターは、要求本文 の 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 SDK
Kusto client ライブラリを使用するときにクエリ パラメーターの名前と値を指定する方法についてはユーザー入力を保護するためにクエリ パラメーターを使用する を参照してください。
Kusto.Explorer
サービスに要求を行う際に送信されるクエリ パラメーターを設定するには、クエリ パラメーターの「横棒」アイコン (ALT + P) を使用します。