ブックのテキスト パラメーター

  • [アーティクル]

テキスト ボックス パラメーターを使用すると、ブック ユーザーからテキスト入力を簡単に収集できます。 これらは、ドロップダウン リストを使用して入力を収集するのが実用的でない場合に使用されます (たとえば、任意のしきい値または汎用フィルター)。 ブックを使うことで、クエリからテキストボックスの既定値を取得することができます。 この機能を使うと、メトリックの p95 に基づいて既定のしきい値を設定するなどの興味深いシナリオが可能になります。

テキスト ボックスは、一般的に、他のブック コントロールによって使用される内部変数として使用します。 既定値にクエリを使い、読み取りモードで入力コントロールを非表示にします。 たとえば、しきい値を (ユーザーが入力するのではなく) 数式から取得した後、後続のクエリでそのしきい値を使用することができます。

テキスト パラメーターを作成する

  1. 編集モードの空白のブックを使用して開始します。

  2. [パラメーターの追加]>[パラメーターの追加] を選びます。

  3. 表示される新しいパラメーター ペインで、次のように入力します。

    1. パラメーター名: SlowRequestThreshold
    2. パラメーターの種類: Text
    3. 必須: checked
    4. データの取得元: None

  4. [保存] を選んでパラメーターを作成します。

    Screenshot that shows the creation of a text parameter.

このスクリーンショットは、読み取りモードでブックがどのように表示されるかを示しています。

Screenshot that shows a text parameter in read mode.

パラメーター フィールドのスタイル

テキスト パラメーターでは、次のフィールド スタイルがサポートされています。

  • 標準: 1 行のテキスト フィールド。

    Screenshot that shows a standard text field.

  • パスワード: 1 行のパスワード フィールド。 パスワード値は、入力するときに UI 上でのみ非表示になります。 この値には、参照時にパラメーター値として完全にアクセスできます。 これらはブックの保存時に、暗号化されずに保存されます。

    Screenshot that shows a password field.

  • 複数行: 次の言語でリッチな IntelliSense と構文の色付けをサポートする複数行テキスト フィールド。

    • テキスト
    • Markdown
    • JSON
    • SQL
    • TypeScript
    • KQL
    • TOML

    複数行エディターの高さを指定することもできます。

    Screenshot that shows a multiline text field.

テキスト パラメーターを参照する

  1. [クエリの追加] を選んでクエリ コントロールを追加し、Application Insights リソースを選びます。

  2. KQL ボックスに、このスニペットを追加します。

    requests
| summarize AllRequests = count(), SlowRequests = countif(duration >= {SlowRequestThreshold}) by name
| extend SlowRequestPercent = 100.0 * SlowRequests / AllRequests
| order by SlowRequests desc

  3. 値 500 を指定したテキスト パラメーターをクエリ コントロールと組み合わせて使用すると、次のクエリを効果的に実行できます。

    requests
| summarize AllRequests = count(), SlowRequests = countif(duration >= 500) by name
| extend SlowRequestPercent = 100.0 * SlowRequests / AllRequests
| order by SlowRequests desc

  4. クエリを実行して結果を確認します。

    Screenshot that shows a text parameter referenced in KQL.

Note

前の例の {SlowRequestThreshold} は整数値を表しています。 文字列 ({ComputerName} など) を照会する場合、パラメーター フィールドに引用符なしで入力値を指定できるようにするには、Kusto クエリに変更を加え、"{ComputerName}" のように引用符を追加する必要があります。

クエリを使用して既定値を設定する

  1. 編集モードの空白のブックを使用して開始します。

  2. [パラメーターの追加]>[パラメーターの追加] を選びます。

  3. 表示される新しいパラメーター ペインで、次のように入力します。

    1. パラメーター名: SlowRequestThreshold
    2. パラメーターの種類: Text
    3. 必須: checked
    4. データの取得元: Query

  4. KQL ボックスに、このスニペットを追加します。

    requests
| summarize round(percentile(duration, 95), 2)

    このクエリでは、テキスト ボックスの既定値を、アプリ内のすべての要求の 95 パーセンタイル期間に設定します。

  5. クエリを実行して結果を確認します。

  6. [保存] を選んでパラメーターを作成します。

    Screenshot that shows a text parameter with a default value from KQL.

Note

この例では Application Insights データを照会していますが、このアプローチは、任意のログ ベースのデータ ソース (Log Analytics、Azure Resource Graph など) に使用できます。

検証を追加する

標準とパスワードのテキスト パラメーターの場合、テキスト フィールドに適用される検証ルールを追加できます。 有効な正規表現をエラー メッセージと一緒に追加します。 メッセージを設定すると、フィールドが無効な場合にエラーとして表示されます。

一致を選ぶと、値が正規表現と一致した場合にフィールドが有効になります。 一致を選んでいないと、値が正規表現と一致しない場合にフィールドが有効になります。

Screenshot that shows text validation settings.

JSON データの書式設定

複数行テキスト フィールドの言語として JSON が選択されている場合、フィールドには、フィールドの JSON データを書式設定するボタンが表示されます。 また、Ctrl + \ キーのショートカットを使って JSON データを書式設定することもできます。

データがクエリから取得される場合、クエリによって返される JSON データを事前に書式設定するオプションを選択できます。

Screenshot that shows the option Pre-format JSON data.

次のステップ

Azure Workbooks の概要