Paramètres de liste déroulante des classeurs

En utilisant des paramètres de liste déroulante, vous pouvez collecter une ou plusieurs valeurs d’entrée à partir d’un ensemble connu. Par exemple, vous pouvez utiliser un paramètre de liste déroulante pour sélectionner l’une des requêtes de votre application. Les paramètres de liste déroulante représentent également un moyen convivial de recueillir des entrées arbitraires des utilisateurs. Les paramètres de liste déroulante particulièrement utiles pour permettre le filtrage dans des rapports interactifs.

Le moyen le plus simple de spécifier un paramètre de liste déroulante consiste à fournir une liste statique dans le paramètre. Il est plus intéressant de récupérer la liste de manière dynamique avec une requête KQL. Vous pouvez également spécifier s’il s’agit d’une sélection unique ou multiple à l’aide des paramètres. S’il s’agit d’une sélection multiple, vous pouvez spécifier la façon dont le jeu de résultats doit être mis en forme (délimiteur ou guillemet, par exemple).

Composants des paramètres de liste déroulante

Lorsque vous utilisez du contenu JSON statique ou que vous obtenez des valeurs dynamiques à partir de requêtes, les paramètres de liste déroulante autorisent jusqu’à quatre champs d’informations, dans cet ordre spécifique :

1. value (obligatoire) : la première colonne/champ dans les données est utilisée comme valeur littérale du paramètre. Dans le cas de paramètres JSON statiques simples, il peut être aussi simple que le contenu JSON ["dev", "test", "prod"], ce qui créerait une liste déroulante de trois éléments avec ces valeurs comme valeur et l’étiquette dans la liste déroulante. Le nom de ce champ n’a pas besoin d’être value, la liste déroulante utilise le premier champ dans les données, quel que soit le nom.

2. label (facultatif) : la deuxième colonne/champ dans les données est utilisée comme nom d’affichage/étiquette du paramètre dans la liste déroulante. Si elle n’est pas spécifiée, la valeur est utilisée comme étiquette. Le nom de ce champ n’a pas besoin d’être label, la liste déroulante utilise le deuxième champ dans les données, quel que soit le nom.

3. selected (facultatif) : la troisième colonne/champ des données est utilisée pour spécifier la valeur à sélectionner par défaut. Si ce n’est pas spécifié, aucun élément n’est sélectionné par défaut. Le comportement de sélection est basé sur le concept JavaScript « falsy », de sorte que les valeurs telles que 0, false, nullou les chaînes vides sont traitées comme non sélectionnées. Le nom de ce champ n’a pas besoin d’être selected, la liste déroulante utilise le troisième champ dans les données, quel que soit le nom.

   Remarque

   Cela contrôle uniquement sélection de par défaut, une fois qu’un(e) utilisateur(-trice) a sélectionné des valeurs dans la liste déroulante, ces valeurs sélectionnées par l’utilisateur(-trice) sont utilisées. Même si une requête ultérieure pour le paramètre s’exécute et retourne de nouvelles valeurs par défaut. Pour revenir à la sélection par défaut, l’utilisation peut utiliser l’option « Éléments par défaut » dans la liste déroulante, qui interroge à nouveau les valeurs par défaut et les applique.

   Les valeurs par défaut sont appliquées uniquement si aucun élément n’a été sélectionné par l’utilisateur(-trice).

   Si une requête suivante retourne des éléments qui ne comprend pas des valeurs précédemment sélectionnées, les valeurs manquantes sont supprimées de la sélection. Les éléments sélectionnés dans la liste déroulante deviendront l’intersection des éléments retournés par la requête et les éléments précédemment sélectionnés.

4. group (facultatif) : contrairement aux autres champs, la colonne de regroupement doit être nommée group et apparaître après value, label et selected. Ce champ dans les données est utilisé pour regrouper les éléments dans la liste déroulante. Si ce n’est pas spécifié, aucun regroupement n’est utilisé. Si la sélection par défaut n’est pas nécessaire, les données/requêtes doivent toujours retourner un champ selected dans au moins un objet/ligne, même si toutes les valeurs sont false.

Remarque

Tous les autres champs des données sont ignorés par le paramètre de liste déroulante. Il est recommandé de limiter le contenu à seulement ces champs utilisés par la liste déroulante pour éviter les requêtes complexes retournant des données ignorées.

Créer un paramètre de liste déroulante statique

1. Démarrez avec un classeur vide en mode d’édition.

2. Sélectionnez Ajouter des paramètres>Ajouter un paramètre.

3. Dans le nouveau volet des paramètres qui apparaît, entrez :

   1. Nom du paramètre : Environment

   2. Type de paramètre : Drop down

   3. Obligatoire : checked

   4. Autoriser les sélections multiples : unchecked

   5. Obtenir des données à partir de : JSON ou, sélectionnez Query et sélectionnez la source de données JSON.

      La source de données JSON permet au contenu JSON de référencer tous les paramètres existants.

4. Dans le bloc de texte de l’entrée JSON, insérez cet extrait de code JSON :

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

5. Sélectionnez Mettre à jour.

6. Sélectionnez Enregistrer pour créer le paramètre.

7. Le paramètre Environnement correspond à une liste déroulante à trois valeurs.

   

Créer une liste déroulante statique avec des groupes d’éléments

Si le résultat/JSON de votre requête contient un champ group, la liste déroulante affiche des groupes de valeurs. Suivez l’exemple précédent, en utilisant cette fois le JSON suivant :

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

Remarque

Lorsque vous utilisez un champ group dans votre requête, vous devez également fournir une valeur pour les champs label et selected.

Créer un paramètre de liste déroulante dynamique

1. Démarrez avec un classeur vide en mode d’édition.

2. Sélectionnez Ajouter des paramètres>Ajouter un paramètre.

3. Dans le nouveau volet des paramètres qui apparaît, entrez :

   1. Nom du paramètre : RequestName
   2. Type de paramètre : Drop down
   3. Obligatoire : checked
   4. Autoriser les sélections multiples : unchecked
   5. Récupérer des données à partir de : Query

4. Dans le bloc de texte de l’entrée JSON, insérez cet extrait de code JSON :

       requests
       | summarize by name
       | order by name asc
   

5. Sélectionnez Run Query (Exécuter la requête).

6. Sélectionnez Enregistrer pour créer le paramètre.

7. Le paramètre RequestName correspond à une liste déroulante contenant les noms de toutes les demandes de l’application.

   

Exemple : Étiquettes personnalisées, sélection du premier élément par défaut et regroupement par nom d’opération

La requête utilisée dans le paramètre de liste déroulante dynamique précédent retourne une liste de valeurs restituées dans la liste déroulante. Si vous souhaitez un autre nom d’affichage ou autoriser l’utilisateur à sélectionner le nom d’affichage, utilisez la valeur, l’étiquette, la sélection et les colonnes de groupe.

L’exemple suivant montre comment obtenir une liste de dépendances Application Insights distinctes. Les noms d’affichage sont mis en forme avec un emoji, le premier élément est sélectionné par défaut et les éléments sont regroupés par noms d’opération :

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

Référencer un paramètre de liste déroulante

Vous pouvez référencer des paramètres de liste déroulante partout où les paramètres peuvent être utilisés, notamment en remplaçant la valeur du paramètre en requêtes, les paramètres de visualisation, le contenu de texte Markdown ou d’autres endroits où vous pouvez sélectionner un paramètre comme option.

En KQL

1. Sélectionnez Ajouter une requête pour ajouter un contrôle de requête, puis sélectionnez une ressource Application Insights.

2. Dans l’éditeur KQL, entrez cet extrait de code :

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

3. Cet extrait de code développe ainsi l’heure d’évaluation de la requête :

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

4. Sélectionnez Exécuter la requête pour afficher les résultats. Si vous le souhaitez, présentez-les sous forme de graphique.

   

Options des paramètres de liste déroulante

Paramètre	Description	Exemple
{DependencyName}	Valeur sélectionnée	GET fabrikamaccount
{DependencyName:value}	Valeur sélectionnée (identique à celle ci-dessus)	GET fabrikamaccount
{DependencyName:label}	Étiquette sélectionnée	🌐 GET fabrikamaccount
{DependencyName:escape}	Valeur sélectionnée, avec les guillemets courants remplacés lors de la mise en forme dans les requêtes	GET fabrikamaccount

Sélection multiple

Les exemples donnés jusqu’ici définissent explicitement le paramètre de façon à sélectionner une seule valeur dans la liste déroulante. Les paramètres de liste déroulante prennent également en charge les sélections multiples. Pour activer cette option, cochez la case Autoriser les sélections multiples.

Vous pouvez spécifier le format du jeu de résultats à l’aide des paramètres Délimiteur et Guillemet avec. Par défaut, , (virgule) est utilisée comme délimiteur et ' (guillemet unique) est utilisé comme caractère de guillemet. Par défaut, les valeurs sont renvoyées sous la forme de 'a', 'b', 'c' lorsqu’elles sont formatées dans la requête. Vous pouvez également limiter le nombre maximal de sélections.

Lorsque vous utilisez un paramètre de sélection multiple dans une requête, assurez-vous que le KQL référençant le paramètre fonctionne avec le format du résultat. Par exemple :

• Un paramètre de valeur unique n’inclut pas de guillemets lorsqu’il est mis en forme dans une requête. Veillez donc à inclure les guillemets dans la requête elle-même, par exemple : where name == '{parameter}'.
• les guillemets sont inclus dans le paramètre mis en forme lors de l’utilisation d’un paramètre de sélection multiple. Vérifiez donc que la requête n’inclut pas de guillemets. Par exemple : where name in ({parameter}).

Notez comment cet exemple passe également de name == à name in. L’opérateur == autorise uniquement une valeur unique, tandis que l’opérateur in autorise plusieurs valeurs.

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

Cet exemple montre le paramètre de liste déroulante à sélection multiple en action :

Sélections spéciales de liste déroulante

Les paramètres de liste déroulante vous permettent également de spécifier des valeurs spéciales qui s’affichent aussi dans la liste déroulante :

• Les un
• Les trois
• ...
• Les 100 éléments
• Tout {limite personnalisée
• Tous

Lorsque ces éléments spéciaux sont sélectionnés, la valeur du paramètre est automatiquement définie sur le nombre spécifique d’éléments, ou sur toutes les valeurs.

Casing All spécial, et permettant à une sélection vide d’être traitée comme All

Lorsque vous sélectionnez Tout, un champ supplémentaire s’affiche, ce qui vous permet de spécifier une valeur spéciale pour le paramètre Tout. Ceci est utile lorsque « Tout » peut représenter un grand nombre d’éléments et générer une requête très volumineuse.

Dans ce cas spécifique, la chaîne [] est utilisée à la place d’une valeur. Cette chaîne peut être utilisée pour générer un tableau vide dans la requête logs, par exemple :

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

Si tous les éléments sont sélectionnés, la valeur de Selection est [], ce qui produit un tableau vide pour la variable selection de la requête. Si aucune valeur n’est sélectionnée, la valeur de Selection est formatée comme une chaîne vide, ce qui donne également un tableau vide. Si des valeurs sont sélectionnées, elles sont mises en forme à l’intérieur de la partie dynamique de la requête, et le tableau présente ces valeurs. Vous pouvez ensuite effectuer un test en attribuant à array_length la valeur 0 pour que le filtre ne s’applique pas ou utiliser l’opérateur in pour filtrer sur les valeurs du tableau.

Dans d’autres exemples courants, « * » est utilisé comme valeur spéciale de marqueur quand un paramètre est obligatoire, puis un test est effectué avec :

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

Étapes suivantes

Découvrez les types de visualisations que vous pouvez utiliser pour créer des rapports visuels enrichis avec des classeurs Azure.