Parâmetros suspensos da pasta de trabalho

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

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

Componentes de parâmetros suspensos

Ao usar conteúdo JSON estático ou obter valores dinâmicos de consultas, os parâmetros suspensos permitem até quatro campos de informação, nesta 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, pode ser tão simples quanto o conteúdo ["dev", "test", "prod"]JSON , o que criaria uma lista suspensa de três itens com esses valores como o valor e o rótulo no menu suspenso. O nome deste campo não precisa ser value, a lista suspensa usará o primeiro campo nos dados, independentemente do nome.

2. label (opcional): a segunda coluna / campo nos dados é usada como o nome de exibição / rótulo do parâmetro na lista suspensa. Se não for especificado, o valor será usado como rótulo. O nome deste campo não precisa ser label, a lista suspensa 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, portanto, valores como 0, false, null, ou strings vazias são tratados como não selecionados. O nome deste campo não precisa ser selected, a lista suspensa usará o terceiro campo nos dados, não importa o nome.

   Nota

   Isso controla apenas a seleção padrão , uma vez que um usuário seleciona valores na lista suspensa, 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 uso pode usar a opção "Itens padrão" no menu suspenso, que consultará novamente os valores padrão e os aplicará.

   Os valores padrão só sã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 na lista suspensa 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 após value, label e selected. Este campo nos dados é usado para agrupar os itens na lista suspensa. Se não for especificado, nenhum agrupamento será usado. Se a seleção padrão não for necessária, os dados/consulta ainda deverão retornar um selected campo em pelo menos um objeto/linha, mesmo que todos os valores sejam false.

Nota

Quaisquer outros campos nos dados são ignorados pelo parâmetro dropdown. Sugere-se limitar o conteúdo apenas aos campos usados pela lista suspensa para evitar consultas complicadas que retornam dados ignorados.

Criar um parâmetro suspenso estático

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 se abre, introduza:

   1. Nome do parâmetro: Environment

   2. Tipo de 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 Entrada JSON , insira este trecho 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 Environment é uma lista suspensa com os três valores.

   

Criar uma lista suspensa estática com grupos de itens

Se o resultado da consulta/JSON contiver um group campo, a lista suspensa exibirá grupos de valores. Siga o exemplo anterior, mas use o seguinte 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" }
]

Nota

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

Criar um parâmetro suspenso dinâmico

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 se abre, introduza:

   1. Nome do parâmetro: RequestName
   2. Tipo de 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 Entrada JSON , insira este trecho 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.

   

Exemplo: rótulos personalizados, selecionando o primeiro item por padrão e agrupando por nome da 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 desejar um nome de exibição diferente ou permitir que o usuário selecione o nome para 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

Fazer referência a um parâmetro suspenso

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

No acórdão KQL

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

2. No editor KQL, insira este trecho:

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

3. O snippet expande o tempo de avaliação da consulta para:

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

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

   

Opções de parâmetros suspensos

Parâmetro	Description	Exemplo
{DependencyName}	O valor selecionado	OBTER fabrikamaccount
{DependencyName:value}	O valor selecionado (igual ao acima)	OBTER fabrikamaccount
{DependencyName:label}	O rótulo selecionado	🌐 OBTER fabrikamaccount
{DependencyName:escape}	O valor selecionado, com quaisquer caracteres de aspas comuns substituídos quando formatados em consultas	OBTER 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 suspensos também suportam 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 através do Delimitador e Cotação com configurações. Por padrão, , (vírgula) é usado como o delimitador, e (aspas simples) é usado como o caractere ' de aspas. O padrão retorna os valores como uma coleção na forma de quando formatado 'a', 'b', 'c' 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 único parâmetro de valor não inclui aspas quando formatado em uma consulta, portanto, certifique-se de incluir as aspas na própria consulta, por exemplo: where name == '{parameter}'.
• As 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 este exemplo também mudou de name == para name in. O == operador permite apenas um único valor, enquanto o in operador permite vários valores.

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

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

Seleções especiais suspensas

Os parâmetros suspensos também permitem especificar valores especiais que também aparecem na lista suspensa:

• Qualquer um
• Quaisquer três
• ...
• Qualquer 100
• Qualquer limite personalizado
• Todos

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

Invólucro especial Tudo e permitindo que uma seleção vazia seja tratada como Tudo

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

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 logs, 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 é [], produzindo uma matriz vazia para a selection variável na consulta. Se nenhum valor for selecionado, o valor de será formatado como cadeia de Selection 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 para array_length de 0 para que o filtro não seja aplicado ou usar o in operador para filtrar os valores na matriz.

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

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

Próximos passos

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