カスタム ダッシュボードの場合、テンプレート変数を使用して、グラフやその他のウィジェットを動的にフィルター処理できます。テンプレート変数は、ダッシュボードをより便利にするのに役立ち、さまざまなユース ケースで再利用できるダッシュボードをより簡単に作成するのに役立ちます。
テンプレート変数を使用する理由
テンプレート変数は、ダッシュボードの作成者が選択した特定のメタデータ値に基づいてダッシュボード全体をフィルタリングする強力で動的な方法です。テンプレート変数を使用する利点は次のとおりです。
- これにより、ダッシュボードが使いやすくなります。ユーザーはデータの構造を理解する必要がなく、設定したさまざまなフィルター オプションから簡単に選択できます。
- これらを使用すると、再利用可能なダッシュボード テンプレートを作成できます。これを複製して、他の多くの用途に合わせて調整できます。
いくつかのテンプレート変数を含むダッシュボードの例を次に示します。これは、ダッシュボードの上部に表示されます。
テンプレート変数を使用すると、さまざまな変数とフィルターを設定して、必要なダッシュボード エクスペリエンスを作成できます。作成できるエクスペリエンスの例:
- アプリ名を選択するドロップダウン
- 特定の地域を選択するドロップダウン
- 特定の期間またはその他の数値を選択するためのドロップダウン
- フリー テキスト フィールドを使用して一致する文字列を検索するフィルター
要件と制限
テンプレート変数は、カスタム ダッシュボードのウィジェットを作成するコンテキストでのみ使用できます。NRQLクエリで変数を使用するには、NRQL変数を参照してください。
テンプレート変数を含むクエリは、ダッシュボードのコンテキストでのみ使用できます。このため、一部のクエリ関連機能は動作しません。たとえば、 Export dashboard as PDFオプションは、変数を持つウィジェットをサポートしていません。
クエリの作成に関する制限については、「クエリの作成」を参照してください。
テンプレート変数を使用する
テンプレート変数の作成方法を順を追って説明し、その後、さまざまな種類のテンプレート変数の例をいくつか示します。
テンプレート変数の作成は、次の 2 つの部分で構成されます。
- テンプレート変数を定義する
- その変数を使用するようにウィジェットを作成または編集します
ステップ 1. テンプレート変数を定義する
まず、テンプレート変数を定義します。これは、ウィジェットを作成するために NRQL クエリで使用する変数です。
変数を定義するには:
- 変数のないダッシュボードから、[変数の追加] をクリックします。(すでに変数が存在する場合は、変数の右側にある+アイコンをクリックします。)
- 変数の追加ワークフローを完了します。以下は、各フィールドのルールとヒントです。
フィールド | 詳細 |
|---|---|
クエリで使用する名前 | 変数の名前。これは、 変数名は文字で始める必要があり、文字、数字、アンダースコアを含めることができます。 |
表示名 | オプション。このように変数がダッシュボードの上に表示されるため、ダッシュボードのユーザーは変数が何を表しているかがわかります。これを空白のままにすると、メインの名前の値が使用されます。 |
タイプ | 次の 3 つのオプションがあります。
|
アカウント |
|
デフォルト値 | オプション。これらは、ダッシュボードがフィルター処理するデフォルト値です。たとえば、上記の
|
複数選択 | オプション。このオプションを使用すると、ドロップダウンで単一の選択ではなく複数の選択を許可できます。 |
出力フォーマット | これにより、変数によって生成されたデータの処理方法を変更できます。デフォルトでは、値がどうなるかを自動的に把握しようとします。ただし、これを特定のものに変更できます。
|
country値のテンプレート変数の例については、このドキュメントの上部にあるスクリーンショットを参照してください。
テンプレート変数を定義したら、ウィジェットへのテンプレート変数の追加に進むことができます。
ステップ 2. 変数を使用するウィジェットを作成する
テンプレート変数を構成したら、クエリで定義した変数を使用するウィジェットがダッシュボードに必要になります。
パート 1 で説明したcountry変数を使用するクエリを作成する例を次に示します。
SELECT countryCode FROM PageAction WHERE countryCode = {{countryCode}}クエリで変数を使用する際に注意すべき重要な点がいくつかあります。
- 定義した変数は、
{{ … }}ブラケット内に入ります。 - 変数は文字列値を生成します。
右側に結果のウィジェットの例があり、左側にcountryドロップダウンがあります。
テンプレート変数の定義とその変数を参照するウィジェットの追加が完了したら、テンプレート変数バーからさまざまなオプションを選択し、選択に基づいてウィジェットが変化するかどうかを確認することで、期待どおりに機能していることを確認できます。
クエリ型テンプレート変数の書き方のルール
テンプレート変数の定義に関するセクションで説明したように、クエリ、リスト、およびテキスト フィールドの 3 つの変数タイプがあります。query-type 変数の作成は最も複雑です。これは、値を返す実際のクエリを作成する必要があるためです。値は、ダッシュボードの上部にあるテンプレート変数バーのドロップダウンに入力するために使用されます。
重要
これは、テンプレート変数を利用するクエリの記述とは異なるトピックであることに注意してください。
クエリ型変数の作成に関するルールとガイダンスを次に示します。
- クエリは
uniques構文を使用する必要があります。Uniques は最大 10,000 件の結果を返します。uniques構文を確認してください。クエリの例を次に示します:From PageAction select uniques(countryCode)。 uniquesコンポーネントが値のリストを返す限り、ほぼすべての NRQL クエリを使用できます。- ネストされた変数はサポートされていません。変数内に変数を含めることはできません。
例
テンプレート変数の実装のいくつかの異なるタイプを次に示します。