Listruteparametrar för arbetsbok

Med hjälp av listruteparametrar kan du samla in ett eller flera indatavärden från en känd uppsättning. Du kan till exempel använda en listruteparameter för att välja en av appens begäranden. Listruteparametrar ger också ett användarvänligt sätt att samla in godtyckliga indata från användare. Listruteparametrar är särskilt användbara för att aktivera filtrering i dina interaktiva rapporter.

Det enklaste sättet att ange en listruteparameter är genom att ange en statisk lista i parameterinställningen. Ett mer intressant sätt är att hämta listan dynamiskt via en KQL-fråga. Du kan också ange om det är enstaka eller flera val med hjälp av parameterinställningar. Om det är flera val kan du ange hur resultatuppsättningen ska formateras, till exempel som avgränsare eller citattecken.

Listruteparameterkomponenter

När du använder antingen statiskt JSON-innehåll eller hämtar dynamiska värden från frågor tillåter listruteparametrar upp till fyra informationsfält i den här specifika ordningen:

1. value (krävs): den första kolumnen/fältet i data används som parameterns literalvärde. När det gäller enkla statiska JSON-parametrar kan det vara så enkelt som JSON-innehållet ["dev", "test", "prod"], vilket skulle skapa en listruta med tre objekt med dessa värden som både värdet och etiketten i listrutan. Namnet på det här fältet behöver inte vara value. Listrutan använder det första fältet i data oavsett namn.

2. label (valfritt): den andra kolumnen/fältet i data används som visningsnamn/etikett för parametern i listrutan. Om det inte anges används värdet som etikett. Namnet på det här fältet behöver inte vara label. Listrutan använder det andra fältet i data oavsett namn.

3. selected (valfritt): den tredje kolumnen/fältet i data används för att ange vilket värde som ska väljas som standard. Om inget anges markeras inga objekt som standard. Urvalsbeteendet baseras på begreppet "falsy" i JavaScript, så värden som 0, false, nulleller tomma strängar behandlas som inte valda. Namnet på det här fältet behöver inte vara selected, listrutan använder det tredje fältet i data oavsett namn.

   Kommentar

   Detta styr bara standardvalet , när en användare har valt värden i listrutan används de valda värdena för användaren. Även om en efterföljande fråga för parametern körs och returnerar nya standardvärden. Om du vill återgå till standardvalet kan du använda alternativet "Standardobjekt" i listrutan, som frågar standardvärdena igen och tillämpar dem.

   Standardvärden tillämpas endast om inga objekt har valts av användaren.

   Om en efterföljande fråga returnerar objekt som inte innehåller tidigare valda värden tas de saknade värdena bort från markeringen. De markerade objekten i listrutan blir skärningspunkten för de objekt som returneras av frågan och de objekt som tidigare har valts.

4. group(valfritt): Till skillnad från de andra fälten måste grupperingskolumnen namnges group och visas efter value, label och selected. Det här fältet i data används för att gruppera objekten i listrutan. Om det inte anges används ingen gruppering. Om standardval inte behövs måste data/frågan fortfarande returnera ett selected fält i minst ett objekt/rad, även om alla värden är false.

Kommentar

Andra fält i data ignoreras av listruteparametern. Det rekommenderas att begränsa innehållet till bara de fält som används i listrutan för att undvika komplicerade frågor som returnerar data som ignoreras.

Skapa en statisk listruteparameter

1. Börja med en tom arbetsbok i redigeringsläge.

2. Välj Lägg till parametrar>Lägg till parameter.

3. I det nya parameterfönstret som öppnas anger du:

   1. Parameternamn: Environment

   2. Parametertyp: Drop down

   3. Krävs: checked

   4. Tillåt flera val: unchecked

   5. Hämta data från: JSON eller välj Query och välj JSON datakällan.

      Med JSON-datakällan kan JSON-innehållet referera till befintliga parametrar.

4. I textblocket JSON-indata infogar du det här JSON-kodfragmentet:

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

5. Välj Uppdatera.

6. Välj Spara för att skapa parametern.

7. Parametern Miljö är en listruta med de tre värdena.

   

Skapa en statisk listruta med grupper av objekt

Om frågeresultatet/JSON innehåller ett group fält visar listrutan grupper med värden. Följ föregående exempel, men använd följande JSON i stället:

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

Kommentar

När du använder ett group fält i frågan måste du också ange ett värde för label och selected fält.

Skapa en dynamisk listruteparameter

1. Börja med en tom arbetsbok i redigeringsläge.

2. Välj Lägg till parametrar>Lägg till parameter.

3. I det nya parameterfönstret som öppnas anger du:

   1. Parameternamn: RequestName
   2. Parametertyp: Drop down
   3. Krävs: checked
   4. Tillåt flera val: unchecked
   5. Hämta data från: Query

4. I textblocket JSON-indata infogar du det här JSON-kodfragmentet:

       requests
       | summarize by name
       | order by name asc
   

5. Välj Kör fråga.

6. Välj Spara för att skapa parametern.

7. Parametern RequestName är en listruta med namnen på alla begäranden i appen.

   

Exempel: Anpassade etiketter, val av det första objektet som standard och gruppering efter åtgärdsnamn

Frågan som används i föregående dynamiska listruteparameter returnerar en lista med värden som återges i listrutan. Om du vill ha ett annat visningsnamn, eller om du vill tillåta att användaren väljer visningsnamnet, använder du kolumnerna värde, etikett, markering och grupp.

Följande exempel visar hur du hämtar en lista över distinkta Application Insights-beroenden. Visningsnamnen är formaterade med en emoji, det första objektet är markerat som standard och objekten grupperas efter åtgärdsnamn:

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

Referera till en listruteparameter

Du kan referera till listruteparametrar var som helst där parametrar kan användas, inklusive att ersätta parametervärdet i frågor, visualiseringsinställningar, Markdown-textinnehåll eller andra platser där du kan välja en parameter som ett alternativ.

I KQL

1. Välj Lägg till fråga för att lägga till en frågekontroll och välj sedan en Application Insights-resurs.

2. I KQL-redigeraren anger du följande kodfragment:

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

3. Kodfragmentet utökar frågeutvärderingstiden till:

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

4. Välj kör frågan för att se resultatet. Du kan också rendera det som ett diagram.

   

Alternativ för listruteparameter

Parameter	Description	Exempel
{DependencyName}	Det valda värdet	GET fabrikamaccount
{DependencyName:value}	Det valda värdet (samma som ovan)	GET fabrikamaccount
{DependencyName:label}	Den markerade etiketten	🌐 GET fabrikamaccount
{DependencyName:escape}	Det valda värdet, med vanliga citattecken ersatta när de formateras i frågor	GET fabrikamaccount

Flera markeringar

Exemplen hittills anger uttryckligen att parametern endast ska välja ett värde i listrutan. Listruteparametrar stöder också flera val. Om du vill aktivera det här alternativet markerar du kryssrutan Tillåt flera val .

Du kan ange formatet för resultatuppsättningen via avgränsare och Citat med inställningar. Som standard , används (kommatecken) som avgränsare och ' (enkelt citattecken) används som citattecken. Standardvärdet returnerar värdena som en samling i form av 'a', 'b', 'c' när de formateras i frågan. Du kan också begränsa det maximala antalet val.

När du använder en parameter med flera val i en fråga kontrollerar du att KQL som refererar till parametern fungerar med resultatets format. Till exempel:

• en parameter med ett enda värde innehåller inga citattecken när de formateras i en fråga, så se till att inkludera citattecknarna i själva frågan, till exempel: where name == '{parameter}'.
• citattecken ingår i den formaterade parametern när du använder en parameter med flera val, så se till att frågan inte innehåller citattecken. Exempel: where name in ({parameter})

Observera hur det här exemplet också växlade från name == till name in. Operatorn == tillåter bara ett enda värde, medan operatorn in tillåter flera värden.

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

Det här exemplet visar listruteparametern för flera val på jobbet:

Särskilda listrutor

Med listruteparametrar kan du också ange särskilda värden som också visas i listrutan:

• Vilken som helst
• Tre
• ...
• 100
• Alla anpassade gränser
• Alla

När dessa specialobjekt väljs anges parametervärdet automatiskt till det specifika antalet objekt eller alla värden.

Specialhölje Alla, och gör att ett tomt val kan behandlas som Alla

När du väljer Alla visas ytterligare ett fält som gör att du kan ange ett specialvärde för parametern Alla . Detta är användbart när "Alla" kan vara ett stort antal objekt och kan generera en mycket stor fråga.

I det här specifika fallet används strängen [] i stället för ett värde. Den här strängen kan användas för att generera en tom matris i loggfrågan, till exempel:

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

Om alla objekt är markerade är []värdet Selection för , vilket skapar en tom matris för variabeln selection i frågan. Om inga värden har valts formateras värdet Selection för som tom sträng, vilket också resulterar i en tom matris. Om några värden har valts formateras de i den dynamiska delen av frågan, vilket gör att matrisen har dessa värden. Du kan sedan testa för 0 för array_length att filtret inte ska tillämpas eller använda operatorn in för att filtrera på värdena i matrisen.

Andra vanliga exempel använder *som specialmarkörvärde när en parameter krävs och testar sedan med:

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

Nästa steg

Lär dig mer om vilka typer av visualiseringar du kan använda för att skapa omfattande visuella rapporter med Azure-arbetsböcker.