ブックのパラメーター
パラメーターを使用して、コンシューマーからの入力を収集し、ブックの他のタイルでそれを参照できます。 通常は、結果セットのスコープを設定したり、適切なビジュアルを設定したりするために使用されます。 この主要な機能を使用して、対話型のレポートとエクスペリエンスを作成できます。
ブックでは、コンシューマーにパラメーター コントロールを表示する方法を制御できます。 テキスト ボックスとドロップダウン リスト、単一または複数選択、テキスト、JSON、KQL、または Azure Resource Graph の値を指定できます。
サポートされているパラメーターの種類には、次のものが含まれます。
- 時間: 事前設定された時間範囲から選択、またはカスタム範囲を選択できます
- ドロップ ダウン: 値または値のセットから選択できます
- オプション グループ: 既知のセットから 1 つの値を選択できます
- テキスト: 任意のテキストを入力できます
- 基準: 以前に指定したパラメーターに基づいて一連の基準を定義でき、それは評価されて動的な値が提供されます
- リソース: 1 つ以上の Azure リソースを選択できます
- サブスクリプション: 1 つ以上の Azure サブスクリプション リソースを選択できます
- 複数値: 1 つ以上の任意のテキスト値を設定できます
- リソースの種類 - 1 つ以上の Azure リソースの種類の値を選択できます
- 場所 - 1 つ以上の Azure の場所の値を選択できます
パラメーターを参照する
パラメーター値は、バインドまたは値の展開を使用して、ブックの他のタイルから参照できます。
バインドを使用してパラメーターを参照する
この例では、バインドを使用して時間範囲パラメーターを参照する方法を示します。
[クエリの追加] を選択してクエリ コントロールを追加し、Application Insights リソースを選択します。
[時間範囲] ドロップダウン リストを開き、下部の [パラメーター] セクションから [時間範囲] を選択します。
- このオプションにより、時間範囲パラメーターがグラフの時間範囲にバインドされます。
- これで、サンプル クエリの時間範囲は [過去 24 時間] になりました。
クエリを実行して結果を確認します。
KQL を使用してパラメーターを参照する
この例では、KQL を使用して時間範囲パラメーターを参照する方法を示します。
[クエリの追加] を選択してクエリ コントロールを追加し、Application Insights リソースを選択します。
KQL で、
| where timestamp {TimeRange}パラメーターを使用して時間スコープ フィルターを入力します。- このパラメーターにより、クエリの評価時間が
| where timestamp > ago(1d)に拡張されます。 - このオプションは、パラメーターの時間範囲の値です。
- このパラメーターにより、クエリの評価時間が
クエリを実行し、結果を確認します。
テキストを使用してパラメーターを参照する
この例では、テキスト を使用して時間範囲パラメーターを参照する方法を示します。
- テキスト コントロールをブックに追加します。
- マークダウンで、「
The chosen time range is {TimeRange:label}」と入力します。 - [編集完了] を選択します。
- テキスト コントロールには、"選択された時間範囲は過去 24 時間です" と表示されます。
パラメーターの書式設定オプション
各パラメーター型には、独自の書式設定オプションがあります。 パラメーターの書式設定拡張オプションを確認するには、[パラメーターの編集] ペインの [プレビュー] セクションを使用します。
これらのオプションを使用すると、時間範囲ピッカーを除くすべてのパラメーター型の書式を設定できます。 時間の書式設定の例については、「時間パラメーターのオプション」を参照してください。
他のパラメーターの種類には、次のものがあります。
- リソース ピッカー: リソース ID が書式設定されます。
- サブスクリプション ピッカー: サブスクリプションの値が書式設定されます。
toml を json に変換する
構文: {param:tomltojson}
元の値:
name = "Sam Green"
[address]
state = "New York"
country = "USA"
書式設定された値:
{
"name": "Sam Green",
"address": {
"state": "New York",
"country": "USA"
}
}
JSON をエスケープする
構文: {param:escapejson}
元の値:
{
"name": "Sam Green",
"address": {
"state": "New York",
"country": "USA"
}
}
書式設定された値:
{\r\n\t\"name\": \"Sam Green\",\r\n\t\"address\": {\r\n\t\t\"state\": \"New York\",\r\n\t\t\"country\": \"USA\"\r\n }\r\n}
テキストを base64 にエンコードする
構文: {param:base64}
元の値:
Sample text to test base64 encoding
書式設定された値:
U2FtcGxlIHRleHQgdG8gdGVzdCBiYXNlNjQgZW5jb2Rpbmc=
JSONPath を使用してパラメーターを書式設定する
JSON コンテンツである文字列パラメーターの場合、パラメーター書式指定文字列で JSONPath を使用できます。
たとえば、次の値を持つ視覚化のクエリまたは選択の結果である、selection という名前の文字列パラメーターがあったとします。
{ "series":"Failures", "x": 5, "y": 10 }
JSONPath を使用すると、そのオブジェクトから個々の値を取得できます。
| フォーマット | 結果 |
|---|---|
{selection:$.series} |
Failures |
{selection:$.x} |
5 |
{selection:$.y} |
10 |
Note
パラメーター値が有効な JSON でない場合、書式の結果は空の値になります。
パラメーター スタイル
パラメーターには、次のスタイルを使用できます。
ピル
ピル スタイルは既定のスタイルです。 パラメーターはテキストのように見え、ユーザーは編集モードに入るためにそれらを一度選択する必要があります。
Standard
標準スタイルでは、コントロールは常に表示され、コントロールの上にラベルがあります。
フォーム (横)
横方向スタイルでは、コントロールは常に表示され、コントロールの左側にラベルがあります。
フォーム (縦)
縦方向のスタイルでは、コントロールは常に表示され、コントロールの上にラベルがあります。 標準スタイルとは異なり、ラベルまたはコントロールは 1 行に 1 つだけです。
Note
標準レイアウト、フォーム (横) レイアウト、およびフォーム (縦) レイアウトでは、インライン編集の概念はありません。 コントロールは常に編集モードです。
グローバル パラメーター
パラメーターのしくみと、パラメーターが設定されている場所の "下流" のみでパラメーターを使用できることに関する制限事項を学習したので、次に、これらのルールを変更するグローバル パラメーターについて学習します。
グローバル パラメーターを使用する場合、そのパラメータを使用する前に宣言する必要があります。 しかし、そのパラメーターに値をセットするすべての手順は、ブック内のそのパラメーターのすべてのインスタンスに影響します。
Note
グローバル パラメーターを変更すると、この "すべて更新" の動作となるため、グローバル設定は、この動作を必要とするパラメーターに対してのみ有効にする必要があります。 相互に依存するグローバル パラメーターを組み合わせると、競合するグローバルが互いに何度も変化するサイクルまたは振動が生じる可能性があります。 サイクルを回避するために、グローバルとして宣言されているパラメーターを "再宣言" することはできません。 あるパラメーターを同じ名前で後で宣言すると、その場所で編集できない読み取り専用パラメーターが作成されます。
グローバル パラメーターの一般的な用途:
多くのグラフ間で時間範囲を同期する:
- グローバル パラメーターを使用しない場合、グラフ内のすべての時間範囲ブラシはそのグラフの後にのみエクスポートされます。 したがって、3 番目のグラフで時間範囲を選択すると、4 番目のグラフのみが更新されます。
- グローバル パラメーターを使用すると、グローバルな timeRange パラメーターを作成し、これに既定値を設定し、他のすべてのグラフで境界の時間範囲と時間ブラシの出力として使用できます。 また、範囲にブラシが適用されている場合のみ、パラメーターをエクスポートする設定を行います。 あらゆるグラフで時間範囲を変更すると、ブックの上部にあるグローバルな timeRange パラメーターが更新されます。 この機能は、ブックをダッシュボードのように動作させるために使用できます。
リンクまたはボタンを使用してリンク ステップで選択したタブを変更できるようにする:
- グローバル パラメーターを使用しない場合、リンク ステップでは、選択したタブのパラメーターのみが出力されます。
- グローバル パラメーターを使用すると、グローバル selectedTab パラメーターを作成できます。 そうすると、リンク ステップのタブ選択で、そのパラメーター名を使用できます。 そのパラメーター値をリンクからブックに渡したり、別のボタンまたはリンクを使用して選択したタブを変更したりすることができます。この方法でリンク ステップのボタンを使用すると、ウィザードのようなエクスペリエンスが得られます。この操作では、ステップの下部にあるボタンは、その上に表示されているセクションに影響を与えることができます。
グローバル パラメーターを作成する
パラメーター ステップでパラメーターを作成する場合は、詳細設定で [このパラメーターをグローバルとして処理] オプションを使用します。 グローバル パラメーターを作成する唯一の方法は、パラメーター ステップを使用して宣言することです。 パラメーターを作成する他の方法 (選択、ブラシ、リンク、ボタン、タブなど) では、グローバル パラメーターの更新のみ可能です。 自身で宣言することはできません。
このパラメーターは、通常のパラメーターと同様に選択可能で、それらが動作するのと同様に機能します。
既存のグローバル パラメーターの値を更新する
グラフの例では、グローバル パラメーターを更新する最も一般的な方法は、時間ブラシを使用することです。
この例では、timerange パラメーターはグローバルとして宣言されています。 その下のクエリ ステップでは、クエリ内でその timerange パラメーターを使用し、時間グラフの結果を返すクエリを作成して実行します。 クエリ ステップの詳細設定で、時間範囲のブラシの設定を有効にします。 時間ブラシ パラメーターの出力と同じパラメーター名を使用します。 また、[範囲にブラシが適用されている場合にのみパラメーターをエクスポートする] オプションを選択します。
このグラフで時間範囲にブラシが適用されるたびに、このクエリの上の timerange パラメーターと、クエリ ステップ自体も (timerange に依存するため) 更新されます。
ブラシの適用前:
- 時間の範囲は [過去 1 時間] と表示されます。
- グラフには、過去 1 時間のデータが表示されます。
ブラシの適用中:
- 時間範囲はまだ過去 1 時間で、ブラシのアウトラインが描画されます。
- パラメーターは変更されていません。 ブラシを放すと、時間範囲が更新されます。
ブラシの適用後:
- 時間ブラシで指定された時間範囲は、この手順で設定します。 これにより、グローバル値がオーバーライドされます。 timerange ドロップダウン リストに、そのカスタム時間範囲が表示されるようになりました。
- 上部のグローバル値が変更され、このグラフが入力として timerange に依存しているため、グラフで使用されるクエリの時間範囲も更新されます。 その結果、クエリとグラフが更新されます。
- timerange に依存するブック内の他の手順も更新されます。
Note
グローバル パラメーターを使用しない場合、timerange パラメーター値はこのクエリ ステップの下のみが変更されます。 この手順より上位のもの、またはこの項目自体は更新されません。