Azure Monitor ブックのドロップダウンパラメーター - Azure Monitor

[アーティクル]
10/15/2024

ドロップダウンパラメーターを使用すると、既知のセットから 1 つ以上の入力値を収集できます。たとえば、ドロップダウンパラメーターを使用して、アプリの要求のいずれかを選択できます。ドロップダウンパラメーターではユーザーフレンドリな方法でユーザーから任意の入力を収集することもできます。ドロップダウンパラメーターは、対話型のレポートでフィルター処理を有効にする場合に特に便利です。

ドロップダウンパラメーターを指定する最も簡単な方法は、パラメーター設定で静的リストを指定することです。より興味深い方法は、KQL クエリを介してリストを動的に取得することです。パラメーター設定を使用して、単一選択か複数選択かを指定することもできます。複数選択の場合は、区切り記号や引用符など、結果セットの書式設定方法を指定できます。

静的 JSON コンテンツを使用する場合、またはクエリから動的な値を取得する場合、ドロップダウンパラメーターでは、次の特定の順序で最大 4 つの情報フィールドを使用できます。

value (必須): データの最初の列/フィールドは、パラメーターのリテラル値として使用されます。単純な静的 JSON パラメーターの場合、JSON コンテンツ ["dev", "test", "prod"] のような単純なものにすることができます。これにより、ドロップダウンの値とラベルの両方としてこれらの値を持つ 3 つの項目のドロップダウンが作成されます。このフィールドの名前を value にする必要はありません。ドロップダウンでは、名前に関係なく、データの最初のフィールドが使用されます。
label (オプション): データの 2 番目の列/フィールドは、ドロップダウンでパラメーターの表示名/ラベルとして使用されます。指定しない場合は、値がラベルとして使用されます。このフィールドの名前を label にする必要はありません。ドロップダウンでは、名前に関係なく、データの 2 番目のフィールドが使用されます。
selected (オプション): データの 3 番目の列/フィールドは、既定で選択される値を指定するために使用されます。指定しない場合、既定で項目は選択されません。選択動作は JavaScript の "falsy" の概念に基づくため、0、false、null、または空の文字列などの値は選択されていないものとして扱われます。このフィールドの名前を selected にする必要はありません。ドロップダウンでは、名前に関係なく、データの 3 番目のフィールドが使用されます。

Note

これは、"既定" の選択を制御するだけです。ユーザーがドロップダウンで値を選択すると、それらのユーザーが選択した値が使用されます。パラメーターの後続のクエリが実行され、新しい既定値が返された場合でもそのままです。既定の選択に戻すには、ドロップダウンの [既定の項目] オプションを使用します。これにより、既定値を再クエリして適用できます。

既定値は、ユーザーによって項目が選択されていない場合にのみ適用されます。

後続のクエリで、以前に選択した値を含まない項目が返された場合、欠落した値は選択から削除されます。ドロップダウンで選択された項目は、クエリによって返された項目と、以前に選択した項目の積集合になります。
group (オプション): 他のフィールドとは異なり、グループ化列は group という名前を付ける "必要があり"、value、label、および selected の後に出現する必要があります。データ内のこのフィールドは、ドロップダウンの項目をグループ化するために使用されます。指定しない場合、グループ化は使用されません。既定の選択が必要ない場合でも、データ/クエリは少なくとも 1 つのオブジェクト/行に selected フィールドを返す必要があります。これは、すべての値が false であっても同様です。

Note

データ内のその他のフィールドは、ドロップダウンパラメーターによって無視されます。ドロップダウンで使用されるフィールドのみにコンテンツを制限することをお勧めします。これは、無視されるデータを返す複雑なクエリを回避するためです。

編集モードの空白のブックを使用して開始します。
[パラメーターの追加]>[パラメーターの追加] を選びます。
表示される新しいパラメーターペインで、次のように入力します。
1. パラメーター名: Environment
2. パラメーターの種類: Drop down
3. 必須: checked
4. 複数選択を許可する: unchecked
5. [データの取得元]: JSON、または Query を選択して JSON データソースを選択します。
  
  JSON データソースを使用すると、JSON コンテンツで既存のパラメーターを参照できます。

[JSON 入力] テキストブロックに、この JSON スニペットを挿入します。

[
    { "value":"dev", "label":"Development" },
    { "value":"ppe", "label":"Pre-production" },
    { "value":"prod", "label":"Production", "selected":true }
]

[更新] を選択します。
[保存] を選んでパラメーターを作成します。
Environment パラメーターは、3 つの値を含むドロップダウンリストになります。

クエリ結果/JSON に group フィールドが含まれている場合は、ドロップダウンリストに値のグループが表示されます。上記のサンプルに従ったうえで、代わりに次の JSON を使用します。

[
    { "value":"dev", "label":"Development", "group":"Development" },
    { "value":"dev-cloud", "label":"Development (Cloud)", "group":"Development" },
    { "value":"ppe", "label":"Pre-production", "group":"Test" },
    { "value":"ppe-test", "label":"Pre-production (Test)", "group":"Test" },
    { "value":"prod1", "label":"Prod 1", "selected":true, "group":"Production" },
    { "value":"prod2", "label":"Prod 2", "group":"Production" }
]

Note

クエリで group フィールドを使用する場合は、label および selected フィールドの値も指定する必要があります。

編集モードの空白のブックを使用して開始します。
[パラメーターの追加]>[パラメーターの追加] を選びます。
表示される新しいパラメーターペインで、次のように入力します。
1. パラメーター名: RequestName
2. パラメーターの種類: Drop down
3. 必須: checked
4. 複数選択を許可する: unchecked
5. データの取得元: Query
[JSON 入力] テキストブロックに、この JSON スニペットを挿入します。
```
    requests
    | summarize by name
    | order by name asc
```
[クエリの実行] を選択します。
[保存] を選び、パラメーターを作成します。
RequestName パラメーターは、アプリ内の全要求の名前を含むドロップダウンリストになります。

例: カスタムラベル、既定で最初の項目を選択する、操作名でグループ化する

上記の動的ドロップダウンパラメーターで使用されるクエリは、ドロップダウンリストで表示される値のリストを返します。別の表示名が必要な場合、またはユーザーが表示名を選択できるようにする場合は、値、ラベル、選択、およびグループ列を使用します。

次のサンプルは、個別の Application Insights 依存関係のリストを取得する方法を示しています。表示名は絵文字でスタイル設定され、最初の項目は既定で選択され、項目は操作名でグループ化されます。

dependencies
| summarize by operation_Name, name
| where name !contains ('.')
| order by name asc
| serialize Rank = row_number()
| project value = name, label = strcat('🌐 ', name), selected = iff(Rank == 1, true, false), group = operation_Name

ドロップダウンパラメーターは、パラメーターを使用できる任意の場所で参照できます。これには、クエリへのパラメーター値の置換、視覚化設定、Markdown テキストコンテンツ、またはパラメーターをオプションとして選択できるその他の場所が含まれます。

KQL 内

[クエリの追加] を選択してクエリコントロールを追加し、Application Insights リソースを選択します。

KQL エディターで、このスニペットを入力します。

    requests
    | where name == '{RequestName}'
    | summarize Requests = count() by bin(timestamp, 1h)

このスニペットにより、クエリの評価時間が次のように拡張されます。

    requests
    | where name == 'GET Home/Index'
    | summarize Requests = count() by bin(timestamp, 1h)

[クエリの実行] を選択し、結果を確認します。必要に応じて、それをグラフとして表示します。

パラメーター	説明	例
`{DependencyName}`	選択された値	GET fabrikamaccount
`{DependencyName:value}`	選択した値 (上記と同じ)	GET fabrikamaccount
`{DependencyName:label}`	選択されたラベル	🌐 GET fabrikamaccount
`{DependencyName:escape}`	選択された値 (クエリにフォーマットされる際には、一般的な引用符は置き換えられます)	GET fabrikamaccount

複数選択

これまでの例では、ドロップダウンリストで 1 つの値のみを選択するようにパラメーターを明示的に設定しました。ドロップダウンパラメーターでは、"複数選択" もサポートされています。このオプションを有効にするには、[複数選択を許可する] チェックボックスをオンにします。

結果セットの形式は、[区切り記号] と [次で引用] の設定を使用して指定できます。既定では、, (コンマ) が区切り記号として使用され、' (単一引用符) が引用符文字として使用されます。既定では、クエリにフォーマットされる際に、値は 'a', 'b', 'c' の形式のコレクションとして返されます。選択の最大数を制限することもできます。

クエリで複数選択パラメーターを使用する場合は、パラメーターを参照する KQL が結果のフォーマットで動作することを確認してください。次に例を示します。

単一値パラメーターでは、クエリにフォーマットされる際に引用符が含まれないため、クエリ自体に引用符を含める必要があります (例: where name == '{parameter}')。
複数選択パラメーターを使用する場合は、フォーマットされたパラメーターに引用符が含まれるため、クエリに引用符が含まれないようにする必要があります。たとえば、where name in ({parameter}) のようにします。

この例では、name == から name in に切り替わっていることにも注意してください。 == 演算子では単一値のみが許可されますが、in 演算子では複数値が許可されます。

dependencies
| where name in ({DependencyName})
| summarize Requests = count() by bin(timestamp, 1h), name

次の例は、実際の複数選択ドロップダウンパラメーターを示しています。

ドロップダウンパラメーターを使用すると、特別な値を指定することもできます。これらの値もドロップダウンに表示されます。

任意の 1 個
任意の 3 個
...
任意の 100 個
任意のカスタム制限
All

これらの特別な項目が選択されると、パラメーター値は、特定の項目の数またはすべての値に自動的に設定されます。

[すべて] を特別なケースとして扱い、空の選択を [すべて] として扱うことを許可する

[すべて] を選択すると追加のフィールドが表示され、[すべて] パラメーターに特別な値を指定できます。これは、[すべて] に多数の項目が含まれ、非常に大規模なクエリが生成される可能性がある場合に有用です。

この特殊なケースでは、値の代わりに文字列 [] が使用されます。この文字列を使用して、ログクエリで次のような空の配列を生成できます。

let selection = dynamic([{Selection}]);
SomeQuery 
| where array_length(selection) == 0 or SomeField in (selection)

すべての項目が選択されている場合、Selection の値は [] となり、クエリ内の selection 変数に空の配列が生成されます。値が選択されていない場合、Selection の値は空の文字列としてフォーマットされ、空の配列になります。何らかの値が選択されている場合は、クエリの動的部分内でフォーマットされ、配列にそれらの値が含まれます。次に、array_length が 0 であるかどうかをテストしてフィルターを適用しないようにすることも、in 演算子を使用して配列内の値をフィルター処理することもできます。

他の一般的な例では、パラメーターが必要な場合に特別なマーカー値として「*」を使用し、次のようにテストします。

| where "*" in ({Selection}) or SomeField in ({Selection})

次のステップ

Azure Workbooks で充実したビジュアルのレポートを作成するために使用できる視覚化の種類について説明します。

次の方法で共有

例: カスタムラベル、既定で最初の項目を選択する、操作名でグループ化する

KQL 内

複数選択

[すべて] を特別なケースとして扱い、空の選択を [すべて] として扱うことを許可する

次のステップ

フィードバック

その他のリソース

次の方法で共有

ブックのドロップダウン パラメーター

ドロップダウン パラメーターのコンポーネント

静的ドロップダウン パラメーターを作成する

項目のグループを使用して静的ドロップダウン リストを作成する

動的ドロップダウン パラメーターを作成する

例: カスタム ラベル、既定で最初の項目を選択する、操作名でグループ化する

ドロップダウン パラメーターを参照する

KQL 内

ドロップダウン パラメーターのオプション

複数選択

ドロップダウンの特別な選択

[すべて] を特別なケースとして扱い、空の選択を [すべて] として扱うことを許可する

次のステップ

フィードバック

その他のリソース

ブックのドロップダウンパラメーター

ドロップダウンパラメーターのコンポーネント

静的ドロップダウンパラメーターを作成する

項目のグループを使用して静的ドロップダウンリストを作成する

動的ドロップダウンパラメーターを作成する

例: カスタムラベル、既定で最初の項目を選択する、操作名でグループ化する

ドロップダウンパラメーターを参照する

ドロップダウンパラメーターのオプション