クエリ パラメーター宣言ステートメント

Kusto に送信されるクエリには、名前と値のペアのセットが含まれる場合があります。 ペアは、クエリ テキスト自体と共にクエリ パラメーターと呼ばれるものです。 クエリは、クエリ パラメーター宣言ステートメントで名前と型を指定することで、1 つ以上の 値を参照できます。

クエリ パラメーターには、主に次の 2 つの用途があります。

  • インジェクション攻撃に対する保護メカニズムとして。
  • クエリをパラメーター化する方法として。

特に、Kusto に送信するクエリでユーザー指定の入力を組み合わせるクライアント アプリケーションでは、Kusto のSQL インジェクション攻撃と同等のものから保護するために、このメカニズムを使用する必要があります。

クエリ パラメーターの宣言

クエリ パラメーター、使用するクエリ テキスト、または関数を参照するには、まず、使用するクエリ パラメーターを宣言する必要があります。 各パラメーターに対して、 宣言は名前とスカラー型を提供します。 必要に応じて、 パラメーターに既定値を指定することもできます。 既定値は、要求がパラメーターの具象値を提供しない場合に使用されます。 その後、Kusto は、その型の通常の解析規則に従って、クエリ パラメーターの値を解析します。

構文

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

構文規則について詳しく知る。

パラメーター

名前 必須 説明
Name1 string ✔️ クエリで使用されるクエリ パラメーターの名前。
Type1 string ✔️ または datetimeなどのstring対応する型。 ユーザーによって提供される値は、文字列としてエンコードされます。 厳密に型指定された値を取得するために、適切な解析メソッドがクエリ パラメーターに適用されます。
DefaultValue1 string パラメーターの既定値。 この値は、適切なスカラー型のリテラルである必要があります。

Note

  • ユーザー 定義関数と同様に、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

クエリ パラメーターは、要求本文 の 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 クライアント ライブラリを使用するときにクエリ パラメーターの名前と値を指定する方法については、「 クエリ パラメーターを使用してユーザー入力を保護する」を参照してください。

Kusto.Explorer

サービスに要求を行う際に送信されるクエリ パラメーターを設定するには、クエリ パラメーターの「横棒」アイコン (ALT + P) を使用します。

この機能は、Azure Monitor ではサポートされていません。