Поделиться через

Параметры в книгах

  • Статья

С помощью параметров можно собирать входные данные от потребителей и делать ссылки на входные данные из других частей книги. Обычно это используется для задания области действия результирующего набора или задания подходящего визуального элемента. Используя эту ключевую возможность, вы можете создавать интерактивные отчеты и процедуры взаимодействия.

С помощью книг можно управлять представлением ваших элементов управления параметрами для потребителей. Это могут быть текстовые поля или раскрывающиеся списки, одиночные и множественные варианты выбора, а также значения из текста, JSON, KQL или Azure Resource Graph.

Поддерживаемые типы параметров:

  • Время: позволяет выбрать предварительно заданные диапазоны времени или пользовательский диапазон
  • Раскрывающийся список: позволяет выбрать значение или набор значений
  • Группа параметров: позволяет выбрать одно значение из известного набора
  • Текст: позволяет ввести произвольный текст
  • Критерии: позволяет определить набор условий на основе заданных ранее параметров, которые будут вычисляться для получения динамического значения
  • Ресурс: позволяет выбрать один или несколько ресурсов Azure
  • Подписка: позволяет выбрать один или несколько ресурсов подписки Azure
  • Многозначный: позволяет задать одно или несколько произвольных текстовых значений
  • Тип ресурса: позволяет выбрать одно или несколько значений типа ресурсов Azure
  • Расположение: позволяет выбрать одно или несколько значений расположения Azure

Ссылка на параметр

Вы можете ссылаться на значения параметров из других частей книг посредством привязок или расширений значений.

Ссылка на параметр с помощью привязок

В этом примере показано, как ссылаться на параметр диапазона времени с помощью привязок:

  1. Выберите Добавить запрос, чтобы добавить элемент управления запросом, а затем выберите ресурс Application Insights.

  2. Откройте раскрывающийся список Диапазон времени и выберите Диапазон времени в разделе Параметры внизу:

    • При этом параметр диапазона времени привязывается к диапазону времени диаграммы.
    • Область времени в примере запроса теперь представляет собой Последние 24 часа.

  3. Выполните запрос, чтобы увидеть результаты.

    Снимок экрана: параметр диапазона времени, на который сделана ссылка с помощью привязок.

Ссылка на параметр с помощью KQL

В этом примере показано, как ссылаться на параметр диапазона времени с помощью KQL:

  1. Выберите Добавить запрос, чтобы добавить элемент управления запросом, а затем выберите ресурс Application Insights.

  2. В KQL введите фильтр области времени с помощью параметра | where timestamp {TimeRange}:

    • При этом время оценки запроса увеличится до | where timestamp > ago(1d).
    • Это является значением диапазона времени для параметра.

  3. Выполните запрос, чтобы увидеть результаты.

    Снимок экрана: диапазон времени, на который сделана ссылка с помощью запроса KQL.

Ссылка на параметр с помощью текста

В этом примере показано, как ссылаться на параметр диапазона времени с помощью текста:

  1. Добавьте текстовый элемент управления в книгу.
  2. В Markdown введите The chosen time range is {TimeRange:label}.
  3. Нажмите Done Editing (Завершить правку).
  4. В текстовом элементе управления отображается текст: Выбранный диапазон времени — "Последние 24 часа".

Опции форматирования параметров

Каждый тип параметра имеет собственные опции форматирования. Используйте раздел Предварительные версии панели Изменение параметра, чтобы просмотреть варианты расширения форматирования для параметра.

Снимок экрана: опции параметра диапазона времени.

Эти опции можно использовать для форматирования всех типов параметров, кроме средства выбора диапазона времени. Примеры форматирования времени см. в разделе Опции параметров времени.

К другим типам параметров относятся следующие:

  • Средство выбора ресурсов: форматируются идентификаторы ресурсов.
  • Средства выбора подписки: форматируются значения подписки.

Преобразование TOML в JSON

Синтаксис: {param:tomltojson}

Исходное значение:

name = "Sam Green"

[address]
state = "New York"
country = "USA"

Форматируемое значение:

{
  "name": "Sam Green",
  "address": {
    "state": "New York",
    "country": "USA"
  }
}

экранирование JSON

Синтаксис: {param:escapejson}

Исходное значение:

{
	"name": "Sam Green",
	"address": {
		"state": "New York",
		"country": "USA"
  }
}

Форматируемое значение:

{\r\n\t\"name\": \"Sam Green\",\r\n\t\"address\": {\r\n\t\t\"state\": \"New York\",\r\n\t\t\"country\": \"USA\"\r\n  }\r\n}

кодирование текста в base64

Синтаксис: {param:base64}

Исходное значение:

Sample text to test base64 encoding

Форматируемое значение:

U2FtcGxlIHRleHQgdG8gdGVzdCBiYXNlNjQgZW5jb2Rpbmc=

Форматирование параметров с помощью JSONPath

Для параметров строки, которые являются содержимым JSON, можно использовать JSONPath в строке форматирования параметров.

Например, у вас может быть параметр строки с именем selection, который был результатом запроса или выбора в визуализации со следующим значением:

{ "series":"Failures", "x": 5, "y": 10 }

С помощью JSONPath можно получить отдельные значения из этого объекта:

Формат Результат
{selection:$.series} Failures
{selection:$.x} 5
{selection:$.y} 10

Примечание.

Если значение параметра не является допустимой JSON, результатом форматирования будет пустое значение.

Стиль параметров

Для параметров доступны следующие стили.

Pills

По умолчанию используется стиль Pills. Параметры выглядят как текст и требуют, чтобы пользователь выбрал их один раз для перехода в режим редактирования.

Снимок экрана: режим чтения для стиля Pills в книгах Azure.

Снимок экрана: режим редактирования для стиля Pills в книгах Azure.

Стандартные

В стандартном стиле элементы управления всегда видны, а метка находится над элементом управления.

Снимок экрана: стандартный стиль книг Azure.

Формирование по горизонтали

В горизонтальном стиле формирования элементы управления всегда видны, а метка находится слева от элемента управления.

Снимок экрана: горизонтальный стиль формирования книг Azure.

Формирование по вертикали

В вертикальном стиле формирования элементы управления всегда видны, а метка находится над элементом управления. В отличие от стандартного стиля, в одной строке имеется только одна метка или один элемент управления.

Снимок экрана: вертикальный стиль формирования книг Azure.

Примечание.

В стандартном, горизонтальном и вертикальном макетах формирования нет концепции встроенного редактирования. Элементы управления всегда находятся в режиме редактирования.

Глобальные параметры

Теперь, когда вы узнали, как работают параметры, и узнали об ограничениях, связанных с возможностью использования параметра только "ниже" того расположения, где он установлен, пришло время узнать о глобальных параметрах, которые изменяют эти правила.

При использовании глобального параметра его необходимо объявить еще до использования. Но любой шаг, задающий значение этого параметра, повлияет на все экземпляры этого параметра в книге.

Примечание.

Поскольку изменение глобального параметра имеет поведение "обновить все", глобальный характер должен быть включен только для параметров, требующих такого поведения. Сочетание глобальных параметров, которые зависят друг от друга, может создать цикл или колебания, когда конкурирующие глобальные значения изменяют друг друга снова и снова. Чтобы избежать циклов, невозможно "повторно объявить" параметр, объявленный как глобальный. Все последующие объявления параметра с тем же именем создадут параметр только для чтения, который не может быть изменен в этом месте.

Распространенные способы использования глобальных параметров

  1. Синхронизация диапазонов времени между несколькими диаграммами:

    • Без использования глобального параметра любая кисть диапазона времени на диаграмме будет экспортироваться только после этой диаграммы. Поэтому при выборе диапазона времени на третьей диаграмме будет обновлена только четвертая диаграмма.
    • При использовании глобального параметра можно создать глобальный параметр timeRange, присвоить ему значение по умолчанию, чтобы все остальные диаграммы использовали его в качестве связанного диапазона времени и выходных данных кисти времени. Дополнительно установите параметр Экспортировать параметр только при использовании кисти диапазона. Теперь любое изменение диапазона времени на любой диаграмме приводит к обновлению глобального параметра timeRange в верхней части книги. Это можно использовать для того, чтобы книга действовала как панель мониторинга.

  2. Разрешение изменять выбранную вкладку на шаге ссылок с помощью ссылок или кнопок:

    • Без использования глобального параметра шаг ссылок выводит только параметр для выбранной вкладки.
    • При использовании глобального параметра можно создать глобальный параметр selectedTab. После этого можно использовать имя этого параметра в выбранных вкладках на шаге ссылок. Вы можете передать значение этого параметра в книгу по ссылке или с помощью другой кнопки или ссылки для изменения выбранной вкладки. С помощью кнопок из шага ссылок таким образом можно создать интерфейс, подобный мастеру, где кнопки в нижней части шага могут повлиять на видимые разделы над ним.

Создание глобального параметра

При создании параметра на шаге параметров используйте вариант Использовать этот параметр в качестве глобального в разделе Дополнительные параметры. Единственный способ создать глобальный параметр — это объявить его с помощью шага параметров. Другие методы создания параметров (с помощью выбора, кисти, ссылок, кнопок, вкладок) могут только обновлять глобальный параметр. Они не могут объявить его самостоятельно.

Снимок экрана: установка глобальных параметров в книге.

Параметр будет доступен и функционировать как обычные параметры.

Обновление значения существующего глобального параметра

В примере диаграммы наиболее распространенным способом обновления глобального параметра является использование кисти времени.

В этом примере параметр timerange объявлен глобальным. На приведенном ниже шаге создайте и выполните запрос, который использует этот параметр timerange в запросе и возвращает результат диаграммы времени. В разделе Дополнительные параметры для шага запроса включите параметр кисти диапазона времени. Используйте то же имя параметра, что и для выходных данных для параметра кисти времени. А также задайте параметр Экспортировать параметр только при использовании кисти диапазона.

Снимок экрана: глобальный параметр кисти времени в книге.

Каждый раз при использовании кисти диапазона времени в этой диаграмме также обновляется параметр timerange над этим запросом и сам шаг запроса, поскольку он также зависит от timerange.

  1. Перед использованием кисти

    • Диапазон времени отображается как Последний час.
    • На диаграмме показаны данные за последний час.

    Снимок экрана: установка глобальных параметров перед использованием кисти.

  2. Во время использования кисти

    • Диапазон времени по-прежнему отображается как "последний час", и рисуются контуры кисти.
    • Параметры не изменились. После того как вы отпустите кисть, обновляется диапазон времени.

    Снимок экрана: установка глобальных параметров во время использования кисти.

  3. После использования кисти

    • На этом шаге устанавливается диапазон времени, заданный кистью времени. Он переопределяет глобальное значение. В раскрывающемся списке timerange теперь отображается настраиваемый диапазон времени.
    • Поскольку глобальное значение в верхней части изменилось, а эта диаграмма зависит от параметра timerange в качестве входных данных, диапазон времени запроса, используемого в диаграмме, также обновляется. В результате запрос и диаграмма будут обновлены.
    • Любые другие шаги в книге, зависящие от timerange, также обновятся.

    Снимок экрана: установка глобальных параметров после использования кисти.

    Примечание.

    Если глобальный параметр не используется, значение параметра timerange изменится только ниже этого шага запроса. Элементы, находящиеся выше, или сам этот элемент обновляться не будут.