Parametri a discesa della cartella di lavoro

Usando i parametri a discesa, è possibile raccogliere uno o più valori di input da un set noto. Ad esempio, è possibile usare un parametro a discesa per selezionare una delle richieste dell'app. I parametri a discesa forniscono anche un modo semplice da usare per raccogliere input arbitrari dagli utenti. I parametri a discesa sono particolarmente utili per abilitare il filtro nei report interattivi.

Il modo più semplice per specificare un parametro a discesa consiste nel fornire un elenco statico nell'impostazione del parametro. Un modo più interessante consiste nell'ottenere l'elenco in modo dinamico tramite una query KQL. È anche possibile specificare se è una selezione singola o multipla usando le impostazioni del parametro. Se è una selezione multipla, è possibile specificare come deve essere formattato il set di risultati, ad esempio come delimitatore o virgoletta.

Componenti dei parametri a discesa

Quando si usa contenuto JSON statico o si ottengono valori dinamici dalle query, i parametri a discesa consentono fino a quattro campi di informazioni, in questo ordine specifico:

1. value (obbligatorio): la prima colonna/campo nei dati viene usata come valore letterale del parametro. Nel caso di semplici parametri JSON statici, può essere semplice come il contenuto JSON ["dev", "test", "prod"], che crea un elenco a discesa di tre elementi con tali valori sia come valore che come etichetta nell'elenco a discesa. Il nome di questo campo non deve essere value; l'elenco a discesa userà il primo campo nei dati indipendentemente dal nome.

2. label (facoltativo): la seconda colonna/campo nei dati viene usata come nome visualizzato/etichetta del parametro nell'elenco a discesa. Se non specificato, il valore viene usato come etichetta. Il nome di questo campo non deve essere label; l'elenco a discesa userà il secondo campo nei dati indipendentemente dal nome.

3. selected (facoltativo): la terza colonna/campo nei dati viene usata per specificare quale valore deve essere selezionato per impostazione predefinita. Se non è specificato, nessun elemento viene selezionato per impostazione predefinita. Il comportamento della selezione si basa sul concetto "falsy" di JavaScript, quindi i valori come 0, false, null o stringhe vuote vengono considerati come non selezionati. Il nome di questo campo non deve essere selected; l'elenco a discesa userà il terzo campo nei dati indipendentemente dal nome.

   Nota

   Ciò controlla solo la selezione predefinita; dopo che un utente ha selezionato i valori nell'elenco a discesa, vengono usati i valori selezionati dall'utente. Anche se viene eseguita una query successiva per il parametro che restituisce nuovi valori predefiniti. Per tornare alla selezione predefinita, l'utente può usare l'opzione "Elementi predefiniti" nell'elenco a discesa, che eseguirà nuovamente una query sui valori predefiniti e li applicherà.

   I valori predefiniti vengono applicati solo se nessun elemento è stato selezionato dall'utente.

   Se una query successiva restituisce elementi che non includono valori selezionati in precedenza, i valori mancanti vengono rimossi dalla selezione. Gli elementi selezionati nell'elenco a discesa diventeranno l'intersezione degli elementi restituiti dalla query e gli elementi selezionati in precedenza.

4. group (facoltativo): a differenza degli altri campi, la colonna di raggruppamento deve essere denominata group e deve apparire dopo value, label e selected. Questo campo nei dati viene usato per raggruppare gli elementi nell'elenco a discesa. Se non è specificato, non viene utilizzato alcun raggruppamento. Se la selezione predefinita non è necessaria, i dati/query devono comunque restituire un campo selected in almeno un oggetto/riga, anche se tutti i valori sono false.

Nota

Tutti gli altri campi nei dati vengono ignorati dal parametro a discesa. È consigliabile limitare il contenuto solo ai campi usati dall'elenco a discesa per evitare query complesse che restituiscono dati ignorati.

Creare un parametro a discesa statico

1. Iniziare con una cartella di lavoro vuota in modalità di modifica.

2. Selezionare Aggiungi parametri>Aggiungi parametro.

3. Nel riquadro del nuovo parametro che viene aperto, immettere:

   1. Nome parametro: Environment

   2. Tipo di parametro: Drop down

   3. Obbligatorio: checked

   4. Consenti selezioni multiple: unchecked

   5. Ottieni dati da: JSON o selezionare Query e scegliere l'origine dati JSON.

      L'origine dati JSON consente al contenuto JSON di fare riferimento a tutti i parametri esistenti.

4. Nel blocco di testo Input JSON, inserire questo frammento JSON:

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

5. Selezionare Aggiorna.

6. Selezionare Salva per creare il parametro.

7. Il parametro Environment è un elenco a discesa con i tre valori.

   

Creare un elenco a discesa statico con gruppi di elementi

Se il risultato della query/JSON contiene un campo group, nell'elenco a discesa vengono visualizzati gruppi di valori. Seguire l'esempio precedente ma usare il codice JSON seguente:

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

Nota

Quando si usa un campo group nella query, è necessario specificare anche un valore per i campi label e selected.

Creare un parametro a discesa dinamico

1. Iniziare con una cartella di lavoro vuota in modalità di modifica.

2. Selezionare Aggiungi parametri>Aggiungi parametro.

3. Nel riquadro del nuovo parametro che viene aperto, immettere:

   1. Nome parametro: RequestName
   2. Tipo di parametro: Drop down
   3. Obbligatorio: checked
   4. Consenti selezioni multiple: unchecked
   5. Ottieni i dati da: Query

4. Nel blocco di testo Input JSON, inserire questo frammento JSON:

       requests
       | summarize by name
       | order by name asc
   

5. Selezionare Esegui query.

6. Selezionare Salva per creare il parametro.

7. Il parametro RequestName è un elenco a discesa con i nomi di tutte le richieste nell'app.

   

Esempio: etichette personalizzate, selezione del primo elemento per impostazione predefinita e raggruppamento in base al nome dell'operazione

La query utilizzata nel parametro a discesa dinamico precedente restituisce un elenco di valori di cui viene eseguito il rendering nell'elenco a discesa. Se si desidera un nome visualizzato diverso o per consentire all'utente di selezionare il nome visualizzato, usare il valore, l'etichetta, la selezione e le colonne di gruppo.

L'esempio seguente illustra come ottenere un elenco di dipendenze di Application Insights distinte. I nomi visualizzati sono in stile emoji; il primo elemento viene selezionato per impostazione predefinita e gli elementi sono raggruppati in base ai nomi delle operazioni:

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

Fare riferimento a un parametro a discesa

È possibile fare riferimento ai parametri a discesa in qualsiasi punto in cui è possibile usare i parametri, inclusa la sostituzione del valore del parametro in query, impostazioni di visualizzazione, contenuto di testo Markdown o altre posizioni in cui è possibile selezionare un parametro come opzione.

In KQL

1. Selezionare Aggiungi query per aggiungere un controllo query e quindi selezionare una risorsa di Application Insights.

2. Nell'editor KQL, immettere questo frammento di codice:

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

3. Il frammento si espande sul tempo di valutazione della query per:

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

4. Selezionare Esegui query per visualizzare i risultati. Facoltativamente, eseguirne il rendering come grafico.

   

Opzioni dei parametri a discesa

Parametro	Descrizione	Esempio
{DependencyName}	Il valore selezionato	GET fabrikamaccount
{DependencyName:value}	Il valore selezionato (uguale al precedente)	GET fabrikamaccount
{DependencyName:label}	L'etichetta selezionata	🌐 GET fabrikamaccount
{DependencyName:escape}	Il valore selezionato, con tutti i caratteri di virgolette comuni sostituiti durante la formattazione nelle query	GET fabrikamaccount

Selezione multipla

Gli esempi finora impostano in modo esplicito il parametro per selezionare un solo valore nell'elenco a discesa. I parametri a discesa supportano anche la selezione multipla. Per abilitare questa opzione, selezionare la casella di controllo Consenti selezioni multiple.

È possibile specificare il formato del set di risultati tramite le impostazioni Delimitatore e Virgolette con. Per impostazione predefinita, , (virgola) viene usato come delimitatore e ' (virgoletta singola) viene usato come carattere virgoletta. L'impostazione predefinita restituisce i valori come raccolta in forma di 'a', 'b', 'c' quando vengono formattati nella query. È anche possibile limitare il numero massimo di selezioni.

Quando si usa un parametro di selezione multipla in una query, assicurarsi che il KQL che fa riferimento al parametro funzioni con il formato del risultato. Ad esempio:

• un parametro con singolo valore non include virgolette quando viene formattato in una query, quindi assicurarsi di includere le virgolette nella query, ad esempio: where name == '{parameter}'.
• le virgolette sono incluse nel parametro formattato quando si usa un parametro a selezione multipla, quindi assicurarsi che la query non includa virgolette. Ad esempio: where name in ({parameter}).

Si noti come questo esempio passi anche da name == a name in. L'operatore == consente solo un singolo valore, mentre l'operatore in consente più valori.

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

Questo esempio mostra il funzionamento del parametro a discesa a selezione multipla:

Selezioni speciali a discesa

I parametri a discesa consentono anche di specificare valori speciali visualizzati anche nell'elenco a discesa:

• Uno qualsiasi
• Qualsiasi tre
• ...
• Qualsiasi 100
• Qualsiasi limite personalizzato
• Tutte le date

Quando questi elementi speciali vengono selezionati, il valore del parametro viene impostato automaticamente sul numero specifico di elementi o su tutti i valori.

Combinazione speciale di maiuscole e minuscole Tutto e consente di gestire una selezione vuota come Tutto

Quando si seleziona Tutto, viene visualizzato un campo aggiuntivo che consente di specificare un valore speciale per il parametro Tutto. Ciò è utile quando "Tutto" potrebbe essere un numero elevato di elementi e potrebbe generare una query molto grande.

In questo caso specifico, viene usata la stringa [] invece di un valore. Questa stringa può essere usata per generare una matrice vuota nella query dei log, ad esempio:

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

Se vengono selezionati tutti gli elementi, il valore di Selection è [], producendo una matrice vuota per la variabile selection nella query. Se non sono selezionati valori, il valore di Selection viene formattato come stringa vuota, producendo una matrice vuota. Se sono selezionati valori, vengono formattati all'interno della parte dinamica della query, in modo che la matrice abbia tali valori. È quindi possibile verificare se array_length di 0 per fare in modo che il filtro non si applichi o usi l'operatore in per filtrare i valori nella matrice.

Altri esempi comuni usano "*" come valore di marcatore speciale quando è necessario un parametro e quindi viene eseguito il test con:

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

Passaggi successivi

Informazioni sui tipi di visualizzazioni che è possibile usare per creare relazioni grafiche avanzate con Azure Workbooks.