Compartilhar via

Parâmetros de lista suspensa da pasta de trabalho

  • Artigo

Usando os parâmetros de lista suspensa, você pode coletar um ou mais valores de entrada de um conjunto conhecido. Por exemplo, você pode usar um parâmetro de lista suspensa para selecionar uma das solicitações do aplicativo. Os parâmetros de lista suspensa fornecem uma maneira amigável de coletar entradas arbitrárias dos usuários. Os parâmetros de lista suspensa são especialmente úteis para habilitar a filtragem em relatórios interativos.

A maneira mais fácil de especificar um parâmetro de lista suspensa é fornecendo uma lista estática na configuração de parâmetros. Uma maneira mais interessante é obter a lista dinamicamente por meio de uma consulta KQL. Você também pode especificar se é uma seleção única ou múltipla, usando as configurações de parâmetro. Se for seleção múltipla, você pode especificar como o conjunto de resultados deve ser formatado, por exemplo, como delimitador ou citação.

Ao usar conteúdo JSON estático ou obter valores dinâmicos de consultas, os parâmetros suspensos permitem até quatro campos de informações, nessa ordem específica:

  1. value (obrigatório): a primeira coluna/campo nos dados é usada como o valor literal do parâmetro. No caso de parâmetros JSON estáticos simples, eles podem ser tão simples quanto o conteúdo JSON ["dev", "test", "prod"], o que criaria uma lista suspensa de três itens com esses valores como valor e rótulo na lista suspensa. O nome desse campo não precisa ser value, o menu suspenso usará o primeiro campo nos dados, independentemente do nome.

  2. label (opcional): a segunda coluna/campo nos dados é usada como nome/rótulo de exibição do parâmetro no menu suspenso. Se não for especificado, o valor será usado como rótulo. O nome desse campo não precisa ser label, o menu suspenso usará o segundo campo nos dados, independentemente do nome.

  3. selected (opcional): a terceira coluna/campo nos dados é usada para especificar qual valor deve ser selecionado por padrão. Se não for especificado, nenhum item será selecionado por padrão. O comportamento de seleção é baseado no conceito "falsy" do JavaScript, então valores como 0, false, null, ou cadeia de caracteres vazias são tratados como não selecionados. O nome desse campo não precisa ser selected, o menu suspenso usará o terceiro campo nos dados, independentemente do nome.

    Observação

    Isso controla apenas a seleção padrão; depois que um usuário seleciona valores no menu suspenso, esses valores selecionados pelo usuário são usados. Mesmo que uma consulta subsequente para o parâmetro seja executada e retorne novos valores padrão. Para retornar à seleção padrão, o usuário pode utilizar a opção "Itens padrão" no menu suspenso, que consultará novamente os valores padrão e os aplicará.

    Os valores padrão só serão aplicados se nenhum item tiver sido selecionado pelo usuário.

    Se uma consulta subsequente retornar itens que não incluem valores selecionados anteriormente, os valores ausentes serão removidos da seleção. Os itens selecionados no menu suspenso se tornarão a interseção dos itens retornados pela consulta e os itens que foram selecionados anteriormente.

  4. group (opcional): ao contrário dos outros campos, a coluna de agrupamento deve ser nomeada group e aparecer depois de value, label e selected. Esse campo nos dados é usado para agrupar os itens no menu suspenso. Se não for especificado, nenhum agrupamento será usado. Se a seleção padrão não for necessária, os dados/consulta ainda devem retornar um campo selected em pelo menos um objeto/linha, mesmo que todos os valores sejam false.

Observação

Quaisquer outros campos nos dados são ignorados pelo parâmetro suspenso. É sugerido limitar o conteúdo apenas aos campos usados ​​pelo menu suspenso para evitar consultas complicadas que retornam dados ignorados.

Criar um parâmetro de lista suspensa estática

  1. Comece com uma pasta de trabalho vazia no modo de edição.

  2. Selecione Adicionar parâmetros>Adicionar Parâmetro.

  3. No novo painel de parâmetros que será aberto, insira:

    1. Nome do parâmetro: Environment

    2. Tipo do parâmetro: Drop down

    3. Obrigatório: checked

    4. Permitir várias seleções: unchecked

    5. Obter dados de: JSON ou selecione Query e selecione a JSON fonte de dados.

      A fonte de dados JSON permite que o conteúdo JSON faça referência a quaisquer parâmetros existentes.

  4. No bloco de texto de Entrada JSON, insira este trecho de código JSON:

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

  5. Selecione Atualizar.

  6. Selecione Salvar para criar o parâmetro.

  7. O parâmetro Ambiente é uma lista suspensa com os três valores.

    Captura de tela que mostra a criação de um parâmetro de lista suspensa estática.

Criar uma lista suspensa estática com grupos de itens

Se o resultado da consulta/JSON contiver um campo group, a lista suspensa exibirá grupos de valores. Siga o exemplo anterior, mas use o JSON a seguir:

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

Captura de tela que mostra um exemplo de uma lista suspensa agrupada.

Observação

Ao usar um campo group em sua consulta, você também deve fornecer um valor para os campos label e selected.

Criar um parâmetro de lista suspensa dinâmica

  1. Comece com uma pasta de trabalho vazia no modo de edição.

  2. Selecione Adicionar parâmetros>Adicionar Parâmetro.

  3. No novo painel de parâmetros que será aberto, insira:

    1. Nome do parâmetro: RequestName
    2. Tipo do parâmetro: Drop down
    3. Obrigatório: checked
    4. Permitir várias seleções: unchecked
    5. Obter dados de: Query

  4. No bloco de texto de Entrada JSON, insira este trecho de código JSON:

        requests
    | summarize by name
    | order by name asc

  5. Selecione Executar Consulta.

  6. Selecione Salvar para criar o parâmetro.

  7. O parâmetro RequestName é uma lista suspensa com os nomes de todas as solicitações no aplicativo.

    Captura de tela que mostra a criação de um parâmetro de lista suspensa dinâmica.

Exemplo: rótulos personalizados, selecionando o primeiro item por padrão e agrupando por nome de operação

A consulta usada no parâmetro suspenso dinâmico anterior retorna uma lista de valores que são renderizados na lista suspensa. Se você quiser um nome de exibição diferente ou permitir que o usuário selecione o nome de exibição, use as colunas de valor, rótulo, seleção e grupo.

O exemplo a seguir mostra como obter uma lista de dependências distintas do Application Insights. Os nomes de exibição são estilizados com um emoji, o primeiro item é selecionado por padrão e os itens são agrupados por nomes de operação:

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

Captura de tela que mostra um parâmetro de lista suspensa usando opções de valor, rótulo, seleção e grupo.

Referenciar um parâmetro de lista suspensa

Você pode referenciar parâmetros suspensos em qualquer lugar onde eles possam ser usados, incluindo a substituição do valor do parâmetro em consultas, configurações de visualização, conteúdo de texto Markdown ou outros lugares onde você pode selecionar um parâmetro como uma opção.

Em KQL

  1. Selecione Adicionar consulta para adicionar um controle de consulta e depois selecione um recurso do Application Insights.

  2. No editor do KQL, insira este trecho de código:

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

  3. O trecho de código expande o tempo de avaliação da consulta para:

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

  4. Selecione Executar consulta para ver os resultados. Opcionalmente, renderize-a como um gráfico.

    Captura de tela que mostra um parâmetro de lista suspensa referenciado no KQL.

Parâmetro Descrição Exemplo
{DependencyName} O valor selecionado GET fabrikamaccount
{DependencyName:value} O valor selecionado (o mesmo que acima) GET fabrikamaccount
{DependencyName:label} O rótulo selecionado 🌐 GET fabrikamaccount
{DependencyName:escape} O valor selecionado, com quaisquer caracteres de aspas comuns substituídos quando formatados em consultas GET fabrikamaccount

Seleção múltipla

Os exemplos até agora definem explicitamente o parâmetro para selecionar apenas um valor na lista suspensa. Os parâmetros de lista suspensa também permitem várias seleções. Para habilitar essa opção, marque a caixa de seleção Permitir várias seleções.

Você pode especificar o formato do conjunto de resultados usando as configurações de Delimitador e Citação com. Por padrão, , (vírgula) é usado como delimitador e ' (aspas simples) é usado como caractere de aspas. O padrão retorna os valores como uma coleção no formato 'a', 'b', 'c' quando formatados na consulta. Você também pode limitar o número máximo de seleções.

Ao usar um parâmetro de seleção múltipla em uma consulta, certifique-se de que o KQL que faz referência ao parâmetro funcione com o formato do resultado. Por exemplo:

  • um parâmetro de valor único não inclui nenhuma aspa quando formatado em uma consulta, portanto, certifique-se de incluir aspas na própria consulta, por exemplo: where name == '{parameter}'.
  • aspas são incluídas no parâmetro formatado ao usar um parâmetro de seleção múltipla, portanto, certifique-se de que a consulta não inclua aspas. Por exemplo, where name in ({parameter}).

Observe como esse exemplo também mudou de name == para name in. O operador == permite apenas um único valor, enquanto o operador in permite múltiplos valores.

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

Este exemplo mostra o parâmetro de lista suspensa de seleção múltipla no trabalho:

Captura de tela que mostra um parâmetro de lista suspensa de seleção múltipla.

Os parâmetros do menu suspenso também permitem que você especifique valores especiais que também aparecem no menu suspenso:

  • Qualquer um
  • Qualquer três
  • ...
  • Qualquer 100
  • Qualquer limite personalizado
  • Tudo

Quando esses itens especiais são selecionados, o valor do parâmetro é automaticamente definido para o número específico de itens ou para todos os valores.

Caixa especial All, e permitindo que uma seleção vazia seja tratada como All

Quando você seleciona Todos, um campo adicional é exibido, permitindo que você especifique um valor especial para o parâmetro Todos. Isso é útil quando "Todos" pode ser um grande número de itens e gerar uma consulta muito grande.

Captura de tela da janela Novo parâmetro no portal do Azure. A opção Todos é selecionada e os campos de valor da opção Selecionar Todos são destacados.

Neste caso específico, a cadeia de caracteres [] é usada em vez de um valor. Essa cadeia de caracteres pode ser usada para gerar uma matriz vazia na consulta de registros, como:

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

Se todos os itens forem selecionados, o valor de Selection será [], produzindo uma matriz vazia para a variável selection na consulta. Se nenhum valor for selecionado, o valor de Selection será formatado como uma cadeia de caracteres vazia, resultando também em uma matriz vazia. Se algum valor for selecionado, ele será formatado dentro da parte dinâmica da consulta, fazendo com que a matriz tenha esses valores. Em seguida, você pode testar array_length de 0 para que o filtro não se aplique ou usar o operador in para filtrar os valores na matriz.

Outros exemplos comuns usam '*' como valor especial do marcador quando um parâmetro é necessário e, em seguida, testam com:

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

Próximas etapas

Saiba mais sobre os tipos de visualizações que você pode usar para criar relatórios visuais avançados com o Azure Workbooks.