Udostępnij za pośrednictwem

Parametry listy rozwijanej skoroszytu

  • Artykuł

Za pomocą parametrów listy rozwijanej można zebrać co najmniej jedną wartość wejściową ze znanego zestawu. Na przykład możesz użyć parametru listy rozwijanej, aby wybrać jedno z żądań aplikacji. Parametry listy rozwijanej zapewniają również przyjazny dla użytkownika sposób zbierania dowolnych danych wejściowych od użytkowników. Parametry listy rozwijanej są szczególnie przydatne podczas włączania filtrowania w interaktywnych raportach.

Najprostszym sposobem określenia parametru listy rozwijanej jest podanie listy statycznej w ustawieniu parametru. Bardziej interesującym sposobem jest dynamiczne pobieranie listy za pośrednictwem zapytania KQL. Można również określić, czy jest to pojedynczy, czy wielokrotny wybór przy użyciu ustawień parametrów. Jeśli jest to wybór wielokrotny, możesz określić sposób formatowania zestawu wyników, na przykład jako ogranicznika lub cudzysłowu.

W przypadku używania statycznej zawartości JSON lub pobierania wartości dynamicznych z zapytań parametry listy rozwijanej umożliwiają maksymalnie cztery pola informacji w tej konkretnej kolejności:

  1. value (wymagane): pierwsza kolumna/pole w danych jest używana jako wartość literału parametru. W przypadku prostych statycznych parametrów JSON może to być tak proste, jak zawartość ["dev", "test", "prod"]JSON, co spowoduje utworzenie listy rozwijanej trzech elementów z tymi wartościami zarówno jako wartości, jak i etykiety na liście rozwijanej. Nazwa tego pola nie musi mieć wartości value, lista rozwijana będzie używać pierwszego pola w danych niezależnie od nazwy.

  2. label (opcjonalnie): druga kolumna/pole w danych jest używana jako nazwa wyświetlana/etykieta parametru na liście rozwijanej. Jeśli nie zostanie określona, wartość zostanie użyta jako etykieta. Nazwa tego pola nie musi być labelnastępująca: lista rozwijana będzie używać drugiego pola w danych niezależnie od nazwy.

  3. selected (opcjonalnie): trzecia kolumna/pole w danych służy do określania, która wartość ma być domyślnie wybrana. Jeśli nie zostanie określony, żadne elementy nie są domyślnie zaznaczone. Zachowanie wyboru jest oparte na koncepcji "fałszowania" języka JavaScript, więc wartości takie jak 0, false, nulllub puste ciągi są traktowane jako nie wybrane. Nazwa tego pola nie musi być selectednastępująca: lista rozwijana będzie używać trzeciego pola w danych niezależnie od nazwy.

    Uwaga

    To tylko kontroluje wybór domyślny , gdy użytkownik wybrał wartości na liście rozwijanej, są używane te wybrane wartości użytkownika. Nawet jeśli kolejne zapytanie dla parametru jest uruchamiane i zwraca nowe wartości domyślne. Aby powrócić do zaznaczenia domyślnego, użyj opcji "Elementy domyślne" na liście rozwijanej, która ponownie wyśle zapytanie o wartości domyślne i zastosuje je.

    Wartości domyślne są stosowane tylko wtedy, gdy użytkownik nie wybrał żadnych elementów.

    Jeśli kolejne zapytanie zwraca elementy, które nie zawierają wcześniej wybranych wartości, brakujące wartości zostaną usunięte z zaznaczenia. Wybrane elementy na liście rozwijanej staną się przecięciem elementów zwracanych przez zapytanie i elementów, które zostały wcześniej wybrane.

  4. group (opcjonalnie): w przeciwieństwie do innych pól kolumna grupowania musi być nazwana group i wyświetlana po value, label i selected. To pole w danych służy do grupowania elementów na liście rozwijanej. Jeśli nie zostanie określony, nie jest używane żadne grupowanie. Jeśli wybór domyślny nie jest wymagany, dane/zapytanie musi nadal zwracać selected pole w co najmniej jednym obiekcie/wierszu, nawet jeśli wszystkie wartości to false.

Uwaga

Wszystkie inne pola w danych są ignorowane przez parametr listy rozwijanej. Zaleca się ograniczenie zawartości tylko do tych pól używanych przez listę rozwijaną, aby uniknąć skomplikowanych zapytań zwracających dane, które są ignorowane.

Tworzenie statycznego parametru listy rozwijanej

  1. Zacznij od pustego skoroszytu w trybie edycji.

  2. Wybierz pozycję Dodaj parametry>Dodaj parametr.

  3. W otwartym okienku nowego parametru wprowadź:

    1. Nazwa parametru: Environment

    2. Typ parametru: Drop down

    3. Wymagane: checked

    4. Zezwalaj na wiele wyborów: unchecked

    5. Pobierz dane z: JSON lub wybierz Query i wybierz JSON źródło danych.

      Źródło danych JSON umożliwia zawartości JSON odwołanie do wszystkich istniejących parametrów.

  4. W bloku tekstu wejściowego JSON wstaw ten fragment kodu JSON:

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

  5. Wybierz Aktualizuj.

  6. Wybierz pozycję Zapisz , aby utworzyć parametr.

  7. Parametr Environment to lista rozwijana z trzema wartościami.

    Zrzut ekranu przedstawiający tworzenie statycznego parametru listy rozwijanej.

Tworzenie statycznej listy rozwijanej z grupami elementów

Jeśli wynik zapytania/kod JSON zawiera group pole, lista rozwijana wyświetla grupy wartości. Postępuj zgodnie z powyższym przykładem, ale zamiast tego użyj następującego kodu JSON:

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

Zrzut ekranu przedstawiający przykład pogrupowanej listy rozwijanej.

Uwaga

W przypadku używania group pola w zapytaniu należy również podać wartość dla label pól i selected .

Tworzenie dynamicznego parametru listy rozwijanej

  1. Zacznij od pustego skoroszytu w trybie edycji.

  2. Wybierz pozycję Dodaj parametry>Dodaj parametr.

  3. W otwartym okienku nowego parametru wprowadź:

    1. Nazwa parametru: RequestName
    2. Typ parametru: Drop down
    3. Wymagane: checked
    4. Zezwalaj na wiele wyborów: unchecked
    5. Pobieranie danych z: Query

  4. W bloku tekstu wejściowego JSON wstaw ten fragment kodu JSON:

        requests
    | summarize by name
    | order by name asc

  5. Wybierz pozycję Uruchom zapytanie.

  6. Wybierz pozycję Zapisz , aby utworzyć parametr.

  7. Parametr RequestName to lista rozwijana zawierająca nazwy wszystkich żądań w aplikacji.

    Zrzut ekranu przedstawiający tworzenie dynamicznego parametru listy rozwijanej.

Przykład: etykiety niestandardowe, wybieranie pierwszego elementu domyślnie i grupowanie według nazwy operacji

Zapytanie używane w poprzednim dynamicznym parametrze listy rozwijanej zwraca listę wartości renderowanych na liście rozwijanej. Jeśli chcesz użyć innej nazwy wyświetlanej lub zezwolić użytkownikowi na wybranie nazwy wyświetlanej, użyj kolumn wartości, etykiety, zaznaczenia i grupy.

W poniższym przykładzie pokazano, jak uzyskać listę różnych zależności usługi Application Insights. Nazwy wyświetlane są stylowane za pomocą emoji, pierwszy element jest domyślnie wybierany, a elementy są grupowane według nazw operacji:

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

Zrzut ekranu przedstawiający parametr listy rozwijanej przy użyciu opcji wartości, etykiety, wyboru i grupy.

Odwołanie do parametru listy rozwijanej

Możesz odwoływać się do parametrów listy rozwijanej w dowolnym miejscu, w którym można używać parametrów, w tym zastępowanie wartości parametru zapytaniami, ustawieniami wizualizacji, zawartością tekstu markdown lub innymi miejscami, w których można wybrać parametr jako opcję.

W języku KQL

  1. Wybierz pozycję Dodaj zapytanie , aby dodać kontrolkę zapytania, a następnie wybierz zasób usługi Application Insights.

  2. W edytorze KQL wprowadź ten fragment kodu:

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

  3. Fragment kodu rozszerza czas oceny zapytania na:

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

  4. Wybierz zapytanie Uruchom, aby wyświetlić wyniki. Opcjonalnie renderuj go jako wykres.

    Zrzut ekranu przedstawiający parametr listy rozwijanej, do którego odwołuje się język KQL.

Parametr Opis Przykład
{DependencyName} Wybrana wartość GET fabrikamaccount
{DependencyName:value} Wybrana wartość (taka sama jak powyżej) GET fabrikamaccount
{DependencyName:label} Wybrana etykieta 🌐 GET fabrikamaccount
{DependencyName:escape} Wybrana wartość z dowolnymi typowymi znakami cudzysłowu zastąpionymi podczas formatowania w zapytaniach GET fabrikamaccount

Wybór wielokrotny

Przykłady do tej pory jawnie ustawiły parametr, aby wybrać tylko jedną wartość na liście rozwijanej. Parametry listy rozwijanej obsługują również wybór wielokrotny. Aby włączyć tę opcję, zaznacz pole wyboru Zezwalaj na wiele zaznaczeń .

Format zestawu wyników można określić za pomocą ogranicznika i cudzysłowu z ustawieniami . Domyślnie , (przecinek) jest używany jako ogranicznik, a ' (pojedynczy cudzysłów) jest używany jako znak cudzysłowu. Wartość domyślna zwraca wartości jako kolekcję w postaci 'a', 'b', 'c' po sformatowaniu w zapytaniu. Można również ograniczyć maksymalną liczbę wyborów.

W przypadku używania parametru wielokrotnego wyboru w zapytaniu upewnij się, że KQL odwołujące się do parametru działa z formatem wyniku. Na przykład:

  • Pojedynczy parametr wartości nie zawiera żadnych cudzysłowów w przypadku formatowania w zapytaniu, dlatego pamiętaj, aby uwzględnić cudzysłowy w samym zapytaniu, na przykład: where name == '{parameter}'.
  • cudzysłowy są uwzględniane w sformatowanym parametrze podczas korzystania z wielu parametrów wyboru, dlatego upewnij się, że zapytanie nie zawiera cudzysłowów. Na przykład where name in ({parameter}).

Zwróć uwagę, jak ten przykład również przełączył się z name == na name in. Operator == zezwala tylko na pojedynczą wartość, a in operator zezwala na wiele wartości.

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

W tym przykładzie przedstawiono parametr listy rozwijanej wielokrotnego wyboru w pracy:

Zrzut ekranu przedstawiający parametr listy rozwijanej wielokrotnego wyboru.

Parametry listy rozwijanej umożliwiają również określanie wartości specjalnych, które również są wyświetlane na liście rozwijanej:

  • Dowolny
  • Wszystkie trzy
  • ...
  • Dowolny 100
  • Dowolny limit niestandardowy
  • wszystkie

Po wybraniu tych elementów specjalnych wartość parametru jest automatycznie ustawiana na określoną liczbę elementów lub wszystkie wartości.

Specjalna wielkość liter Wszystkie i pozwalająca na traktowanie pustego zaznaczenia jako Wszystkie

Po wybraniu pozycji Wszystkie zostanie wyświetlone dodatkowe pole, które umożliwia określenie specjalnej wartości dla parametru All . Jest to przydatne, gdy opcja "Wszystkie" może być dużą liczbą elementów i może wygenerować bardzo duże zapytanie.

Zrzut ekranu przedstawiający okno Nowy parametr w witrynie Azure Portal. Wybrano opcję Wszystkie, a pole Wszystkie i Zaznacz wszystko zostało wyróżnione.

W tym konkretnym przypadku ciąg [] jest używany zamiast wartości. Ten ciąg może służyć do generowania pustej tablicy w zapytaniu dzienników, na przykład:

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

Jeśli wybrano wszystkie elementy, wartość Selection to [], tworząc pustą tablicę dla selection zmiennej w zapytaniu. Jeśli nie wybrano żadnych wartości, wartość Selection jest formatowana jako pusty ciąg, co powoduje również pustą tablicę. Jeśli wybrano jakiekolwiek wartości, są one formatowane wewnątrz dynamicznej części zapytania, co powoduje, że tablica ma te wartości. Następnie można przetestować dla array_length wartości 0, aby filtr nie był stosowany lub używać in operatora do filtrowania wartości w tablicy.

Inne typowe przykłady używają znaku "*" jako specjalnej wartości znacznika, gdy parametr jest wymagany, a następnie przetestuj za pomocą polecenia:

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

Następne kroki

Dowiedz się więcej o typach wizualizacji, których można użyć do tworzenia rozbudowanych raportów wizualnych za pomocą skoroszytów platformy Azure.