Freigeben über

Dropdownparameter in Arbeitsmappen

  • Artikel

Mithilfe von Dropdownparametern können Sie einen oder mehrere Eingabewerte aus einer bekannten Menge sammeln. Sie können beispielsweise mit einem Dropdownparameter eine der Anforderungen Ihrer App auswählen. Dropdownparameter bieten auch eine benutzerfreundliche Möglichkeit, beliebige Eingaben von Benutzern zu erfassen. Dropdownparameter sind besonders nützlich, um Filtervorgänge in interaktiven Berichten zu ermöglichen.

Sie können einen Dropdownparameter am einfachsten angeben, indem Sie in der Parametereinstellung eine statische Liste bereitstellen. Interessanter wird es, wenn Sie die Liste dynamisch über eine KQL-Abfrage abrufen. Sie können über Parametereinstellungen auch festlegen, ob es sich um eine Einfach- oder Mehrfachauswahl handelt. Wenn es sich um eine Mehrfachauswahl handelt, können Sie festlegen, wie das Resultset formatiert werden soll, z. B. als Trennzeichen oder Anführungszeichen.

Wenn Sie statische JSON-Inhalte verwenden oder dynamische Werte aus Abfragen abrufen, ermöglichen Dropdownparameter bis zu vier Informationsfelder in dieser spezifischen Reihenfolge:

  1. value (erforderlich): Die erste Spalte/das erste Feld in den Daten wird als Literalwert des Parameters verwendet. Bei einfachen statischen JSON-Parametern kann dies so einfach sein wie der JSON-Inhalt ["dev", "test", "prod"], wodurch ein Dropdown mit drei Elementen erstellt wird, das diese Werte sowohl als Wert als auch als Bezeichnung im Dropdown enthält. Der Name dieses Felds muss nicht „value“ sein, das Dropdown verwendet das erste Feld in den Daten unabhängig vom Namen.

  2. label (optional): Die zweite Spalte/das zweite Feld in den Daten wird als Anzeigename/Beschriftung des Parameters im Dropdown verwendet. Wenn kein Wert angegeben wird, wird der Wert als Bezeichnung verwendet. Der Name dieses Felds muss nicht „label“ sein, das Dropdown verwendet das zweite Feld in den Daten unabhängig vom Namen.

  3. selected (optional): Die dritte Spalte/das dritte Feld in den Daten wird verwendet, um anzugeben, welcher Wert standardmäßig ausgewählt werden soll. Wenn dies nicht angegeben ist, werden standardmäßig keine Elemente ausgewählt. Das Auswahlverhalten basiert auf dem JavaScript-Konzept „falsy“, sodass Werte wie 0, false, null oder leere Zeichenfolgen als nicht ausgewählt behandelt werden. Der Name dieses Felds muss nicht „selected“ sein, das Dropdown verwendet das dritte Feld in den Daten unabhängig vom Namen.

    Hinweis

    Dies steuert nur die Standardauswahl. Sobald ein Benutzer Werte im Dropdown ausgewählt hat, werden diese vom Benutzer ausgewählten Werte verwendet. Dies gilt auch, wenn eine nachfolgende Abfrage für den Parameter ausgeführt wird und neue Standardwerte zurückgibt. Um zur Standardauswahl zurückzukehren, kann die Option „Standardelemente“ in der Dropdownliste verwendet werden, die die Standardwerte erneut abfragt und anwendet.

    Standardwerte werden nur angewendet, wenn vom Benutzer keine Elemente ausgewählt wurden.

    Wenn eine nachfolgende Abfrage Elemente zurückgibt, die nicht zuvor ausgewählte Werte enthalten, werden die fehlenden Werte aus der Auswahl entfernt. Die ausgewählten Elemente im Dropdown werden zur Schnittmenge der von der Abfrage zurückgegebenen Elemente und der zuvor ausgewählten Elemente.

  4. group (optional): Im Gegensatz zu den anderen Feldern muss die Gruppierungsspalte „group“ benannt und nach value, label und selected angezeigt werden. Dieses Feld in den Daten wird verwendet, um die Elemente im Dropdown zu gruppieren. Wenn es nicht angegeben ist, wird keine Gruppierung verwendet. Wenn die Standardauswahl nicht erforderlich ist, muss von den Daten/der Abfrage weiterhin ein selected-Feld in mindestens einem Objekt/einer Zeile zurückgegeben werden, auch wenn alle Werte false sind.

Hinweis

Alle anderen Felder in den Daten werden vom Dropdownparameter ignoriert. Es wird empfohlen, den Inhalt auf die Felder zu beschränken, die vom Dropdown verwendet werden, um zu vermeiden, dass komplizierte Abfragen Daten zurückgeben, die ignoriert werden.

Erstellen eines statischen Dropdownparameters

  1. Beginnen Sie mit einer leeren Arbeitsmappe im Bearbeitungsmodus.

  2. Wählen Sie Parameter hinzufügen>Parameter hinzufügen aus.

  3. Geben Sie in das sich öffnende neue Parameterfenster ein:

    1. Name des Parameters: Environment

    2. Typ des Parameters: Drop down

    3. Erforderlich: checked

    4. Mehrfachauswahl zulassen: unchecked

    5. Daten abrufen aus: JSON oder wählen Sie Query aus, und wählen Sie die JSON-Datenquelle aus.

      Die JSON-Datenquelle ermöglicht es dem JSON-Inhalt, auf vorhandene Parameter zu verweisen.

  4. Fügen Sie im Textblock der JSON-Eingabe diesen JSON-Schnipsel ein:

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

  5. Wählen Sie Aktualisieren aus.

  6. Wählen Sie Speichern aus, um den Parameter zu erstellen.

  7. Der Parameter Umgebung ist eine Dropdownliste mit den drei Werten.

    Screenshot, der die Erstellung eines statischen Dropdownparameters zeigt.

Erstellen einer statischen Dropdownliste mit Gruppen von Elementen

Wenn Ihr Abfrageergebnis/Ihr JSON ein Feld group enthält, zeigt die Dropdownliste Gruppen von Werten an. Orientieren Sie sich am obigen Beispiel, verwenden Sie jedoch stattdessen den folgenden JSON-Code:

[
    { "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" }
]

Screenshot, der ein Beispiel einer gruppierten Dropdownliste zeigt.

Hinweis

Wenn Sie ein group-Feld in Ihrer Abfrage verwenden, müssen Sie auch einen Wert für die Felder label und selected angeben.

Erstellen eines dynamischen Dropdownparameters

  1. Beginnen Sie mit einer leeren Arbeitsmappe im Bearbeitungsmodus.

  2. Wählen Sie Parameter hinzufügen>Parameter hinzufügen aus.

  3. Geben Sie in das sich öffnende neue Parameterfenster ein:

    1. Name des Parameters: RequestName
    2. Typ des Parameters: Drop down
    3. Erforderlich: checked
    4. Mehrfachauswahl zulassen: unchecked
    5. Daten abrufen aus: Query

  4. Fügen Sie im Textblock der JSON-Eingabe diesen JSON-Schnipsel ein:

        requests
    | summarize by name
    | order by name asc

  5. Wählen Sie Run Query (Abfrage ausführen) aus.

  6. Wählen Sie Speichern aus, um den Parameter zu erstellen.

  7. Der Parameter RequestName ist eine Dropdownliste mit den Namen aller Anforderungen in der App.

    Screenshot, der die Erstellung eines dynamischen Dropdownparameters zeigt.

Beispiel: Benutzerdefinierte Bezeichnungen, standardmäßiges Auswählen des ersten Elements und Gruppieren nach Vorgangsname

Die im vorherigen dynamischen Dropdownparameter verwendete Abfrage gibt eine Liste mit Werten zurück, die in der Dropdownliste gerendert werden. Wenn Sie einen anderen Anzeigenamen verwenden oder dem Benutzer erlauben möchten, den Anzeigenamen auszuwählen, verwenden Sie die Spalten für Wert, Bezeichnung, Auswahl und Spaltengruppierung.

Das folgende Beispiel zeigt, wie Sie eine Liste mit unterschiedlichen Application Insights-Abhängigkeiten abrufen. Die Anzeigenamen werden mit einem Emoji formatiert, das erste Element ist standardmäßig ausgewählt, und die Elemente werden nach Vorgangsnamen gruppiert:

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

Screenshot eines Dropdownparameters, der Optionen für Wert, Bezeichnung, Auswahl und Gruppenspalten verwendet.

Verweisen auf einen Dropdownparameter

Sie können auf Dropdownparameter überall verweisen, wo Parameter verwendet werden können, einschließlich des Ersetzens des Parameterwerts in Abfragen, Visualisierungseinstellungen, Markdown-Textinhalt oder an anderen Stellen, an denen Sie einen Parameter als Option auswählen können.

In einer KQL

  1. Wählen Sie Abfrage hinzufügen, um ein Abfragesteuerelement hinzuzufügen, und dann eine Application Insights-Ressource aus.

  2. Geben Sie im KQL-Editor diesen Schnipsel ein:

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

  3. Dieser Schnipsel wird bei der Auswertung der Abfrage wie folgt erweitert:

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

  4. Wählen Sie Abfrage ausführen aus, um die Ergebnisse anzuzeigen. Optional können Sie die Ergebnisse auch als Diagramm rendern lassen.

    Screenshot eines Dropdownparameters, auf den in KQL verwiesen wird.

Parameter BESCHREIBUNG Beispiel
{DependencyName} Ausgewählter Wert GET fabrikamaccount
{DependencyName:value} Der ausgewählte Wert (identisch mit oben) GET fabrikamaccount
{DependencyName:label} Ausgewählte Bezeichnung 🌐 GET fabrikamaccount
{DependencyName:escape} Der ausgewählte Wert, wobei gängige Anführungszeichen beim Formatieren in Abfragen ersetzt werden GET fabrikamaccount

Mehrfachauswahl

In den bisherigen Beispielen wurde der Parameter explizit so festgelegt, dass nur ein Wert in der Dropdownliste ausgewählt wird. Dropdownparameter unterstützen auch Mehrfachauswahl. Um diese Option zu aktivieren, aktivieren Sie das Kontrollkästchen Mehrfachauswahl zulassen.

Sie können das Format des Resultsets über die Einstellungen Trennzeichen und Umschließen mit festlegen. Standardmäßig wird , (Komma) als Trennzeichen verwendet, und ' (einfaches Anführungszeichen) wird als Anführungszeichen verwendet. In der Standardeinstellung werden die Werte als Sammlung im Format 'a', 'b', 'c' zurückgegeben, wenn sie in der Abfrage formatiert werden. Sie können auch die maximale Anzahl der Auswahlmöglichkeiten begrenzen.

Stellen Sie bei Verwendung eines Mehrfachauswahlparameters in einer Abfrage sicher, dass der KQL-Verweis auf den Parameter mit dem Format des Ergebnisses funktioniert. Zum Beispiel:

  • Ein einzelner Wertparameter enthält beim Formatieren in einer Abfrage keine Anführungszeichen. Stellen Sie daher sicher, dass Sie die Anführungszeichen in die Abfrage selbst einschließen, z. B.: where name == '{parameter}'.
  • Anführungszeichen werden beim Verwenden eines Mehrfachauswahlparameters in den formatierten Parameter einbezogen. Stellen Sie daher sicher, dass die Abfrage keine Anführungszeichen enthält. Beispiel: where name in ({parameter}).

Beachten Sie, dass in diesem Beispiel auch von name == zu name in gewechselt wurde. Der ==-Operator lässt nur einen einzelnen Wert zu, während der in-Operator mehrere Werte zulässt.

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

In diesem Beispiel wird der Dropdownparameter mit Mehrfachauswahl gezeigt:

Screenshot eines Dropdownparameters mit Mehrfachauswahl.

Mit Dropdownparametern können Sie auch spezielle Werte angeben, die ebenfalls in der Dropdownliste angezeigt werden:

  • Eine beliebige
  • Drei beliebige
  • ...
  • 100 beliebige
  • benutzerdefinierter beliebiger Grenzwert
  • Alle

Wenn diese speziellen Elemente ausgewählt werden, wird der Parameterwert automatisch auf die bestimmte Anzahl von Elementen oder alle Werte festgelegt.

Spezialfall „Alle“ und Zulassen, dass eine leere Auswahl als „Alle“ behandelt werden kann

Wenn Sie Alle auswählen, wird ein zusätzliches Feld angezeigt, mit dem Sie einen speziellen Wert für den Parameter All angeben können. Dies ist nützlich für Fälle, in denen „Alle“ eine große Anzahl von Elementen sein könnte und eine sehr große Abfrage generieren würde.

Screenshot des Fensters „Neuer Parameter“ im Azure-Portal. Die Option „Alle“ ist ausgewählt, und die Option „Alle“ und das Feld „Alle Werte auswählen“ sind hervorgehoben.

In diesem speziellen Fall wird die Zeichenfolge [] anstelle eines Werts verwendet. Diese Zeichenfolge kann verwendet werden, um ein leeres Array in der Protokollabfrage zu generieren, beispielsweise:

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

Wenn alle Elemente ausgewählt sind, ist der Wert von Selection[], wodurch ein leeres Array für die selection-Variable in der Abfrage erzeugt wird. Wenn keine Werte ausgewählt sind, ist der Wert von Selection als leere Zeichenfolge formatiert, was zu einem leeren Array führt. Wenn Werte ausgewählt sind, werden sie im dynamischen Teil der Abfrage formatiert, sodass das Array diese Werte aufweist. Sie können dann auf array_length von 0 testen, damit der Filter nicht angewendet wird, oder sie können den in-Operator verwenden, um nach den Werten im Array zu filtern.

Andere gängige Beispiele verwenden „*“ als besonderen Markerwert, wenn ein Parameter erforderlich ist, und testen dann mit:

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

Nächste Schritte

Erfahren Sie mehr über die Arten von Visualisierungen, die Sie verwenden können, um mit Azure-Arbeitsmappen umfangreiche visuelle Berichte zu erstellen.