Использование переменных

Важно

Возможности и функции Power Virtual Agents теперь являются частью Microsoft Copilot Studio после значительных инвестиций в генеративный искусственный интеллект и расширенную интеграцию с Microsoft Copilot.

Некоторые статьи и снимки экрана могут ссылаться на Power Virtual Agents, пока мы обновляем документацию и учебные материалы.

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

Вы можете также использовать переменные для создания логических выражений, которые динамически направляют клиента по различным путям разговора. Например, сохраните имя клиента в переменной с именем UserName, и помощник может обращаться к клиенту по имени, пока разговор продолжается.

Переменные также могут быть переданы в другие темы и потоки Power Automate и возвращены из них.

Веб-приложение

Переменные могут существовать на трех уровнях или в трех областях действия:

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

Типы переменных

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

Type	Описание:
String	Последовательность символов, используемая для представления текста
Логический	Логическое значение, которое может быть только true или false
Число	Любое вещественное число
Таблицу	Список значений, но все значения должны быть одного типа
Запись	Коллекция пар имя-значение, где значения могут быть любого типа
Дата/время	Дата, время, день недели или месяц относительно момента времени
Выбранный вариант	Список строковых значений со связанными синонимами
Чистого листа	Заполнитель для «нет значения» или «неизвестное значение»; дополнительную информацию см. в разделе Пустые значения в Power Fx

Тип переменной устанавливается при первом присвоении ей значения. После этого тип этой переменной фиксируется, и ей не могут быть присвоены значения любого другого типа. Например, переменной с заданным начальным значением 1 присваивается тип Число. Попытка назначить ей значение "apples" типа Строка приведет к ошибке.

При тестировании помощника переменная может временно отображаться как тип неизвестно. Переменной неизвестный еще не присвоено значение.

Порядок переменных определяется сверху вниз на холсте разработки. То есть узлы в верхней части холста разработки считаются находящимися перед узлами в нижней части. При создании ветвей с узлами Условие ветви упорядочиваются слева направо. То есть узлы в самой левой ветви считаются находящимися перед узлами в самой правой ветви.

Сущности

Microsoft Copilot Studio использует сущности для определения определенного типа информации из ответов пользователя. Идентифицированная информация сохраняется в переменной того типа, который подходит для этой информации. В следующей таблице перечислены базовые типы переменных, связанные с предварительно созданными сущностями.

Объект	Тип базовой переменной
Параметры с несколькими вариантами выбора	Выбранный вариант
Весь ответ пользователя	String
Возраст	Число
Логический	Логический
City	String
Color	String
Континент	String
Страна или регион	String
Дата и время	Дата/время
Электронное письмо	String
Мероприятие	String
Целое	Целое
Язык	String
Money	Число
Число	Число
Порядковое число	Число
Организация	String
Процент	Число
Имя человека	String
Номер телефона.	String
Точка интереса	String
Скорость	Число
State	String
Улица, дом	String
Температура	Число
URL	String
Толщина	Число
Почтовый индекс	String
Настраиваемый объект	Выбранный вариант

Создание переменной

Любой узел, который предложит вам выбрать переменную в качестве вывода, например узел Вопрос, автоматически создает выходную переменную соответствующего типа.

Выбор сущности для использования

По умолчанию узлы Вопрос создается с вариантами множественного выбора. Чтобы использовать другую готовую или настраиваемую сущность, установите флажок Определение и выберите тип информации, которую должен прослушивать помощник.

Изменение имени переменной

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

1. Выберите переменную, чтобы открыть ее на панели Свойства переменных.

2. В поле Имя переменной введите новое имя для переменной.

Задание переменной

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

1. Выберите Добавить узел (+), чтобы добавить узел, затем выберите Задать значение переменной.

2. Выберите поле под Задать переменную, затем выберите Создать новую переменную.

   

   Новая переменная создана. Ее тип неизвестен, пока вы не присвоите ей значение.

   

3. Для До значения назначьте значение, используя один из следующих вариантов:

   • Введите литеральное значение.
   • Выберите существующую переменную того же типа. Это действие задает вашей переменной такое же значение, что и у выбранной переменной.
   • Используйте формулу Power Fx. Формулы Power Fx полезны для более сложных типов, где нельзя использовать литеральные значения, например для типов "Таблица" и "Запись".

Использование литеральных значений

Вместо выбора значения переменной можно ввести литеральное значение в любую переменную.

Узел пытается интерпретировать литеральные значения как строковый, числовой или логический тип. Например, 123 интерпретируется как число. Если вы хотели, чтобы это интерпретировалось как строковое значение, вы можете заключить это значение в двойные кавычки, например так: "123".

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

Панель "Переменные"

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

Чтобы открыть панель Переменные, в строке меню темы, выберите Переменные.

Панель свойств переменной

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

Чтобы открыть панель Свойства переменной, выберите переменную на панели Переменные. Вы также можете открыть панель Свойства переменной, выбрав переменную в любом узле.

Системные переменные

Каждый помощник имеет встроенные системные переменные, которые предоставляют дополнительную информацию о разговоре.

В списке показаны не все системные переменные. Вы должны получить доступ к этим скрытым системным переменным с помощью формулы Power Fx.

Чтобы использовать системные переменные в формуле Power Fx, вы должны добавить System. перед именем переменной. Например, чтобы включить системную переменную User.DisplayName в формулу, вам нужно обратиться к ней как System.User.DisplayName.

Полное имя	Type	Скрыт	Определение
Activity.Channel	вариант	видимо	ИД канала текущего разговора
Activity.ChannelData	любое	hidden	Объект, содержащий содержимое, относящееся к каналу
Activity.ChannelId	string	hidden	ИД канала текущего разговора, в виде строки
Activity.From.Id	string	hidden	Уникальный ИД конкретного канала отправителя
Activity.From.Name	string	hidden	Понятное имя отправителя для конкретного канала
Activity.Name	string	видимо	Имя события
Activity.Text	string	видимо	Последнее сообщение, отправленное пользователем
Activity.Type	вариант	видимо	Тип действия
Activity.TypeId	string	hidden	Тип действия, в виде строки
Activity.Value	любое	hidden	Открытое значение
Bot.Name	string	видимо	Имя вашего помощника
Channel.DisplayName	string	hidden	Отображение имени канала
Conversation.Id	string	видимо	Уникальный ИД текущей беседы
LastActivity.Id	string	видимо	ИД ранее отправленного действия
LastMessage.Id	string	видимо	ИД предыдущего сообщения, отправленного пользователем
LastMessage.Text	string	видимо	Предыдущее сообщение, отправленное пользователем
Recognizer.TriggerMessage.Id	string	видимо	Идентификатор пользовательского сообщения, инициировавшего текущую тему
Recognizer.TriggerMessage.Text	string	видимо	Пользовательское сообщение, инициировавшее текущую тему
User.DisplayName	string	видимо	Отображаемое имя пользователя, выполнившего вход

Передача переменных между темами

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

Получение значений из других тем

Когда тема определяет переменную (например, с помощью узла «Вопрос»), помощник задает вопрос пользователю для заполнения значения переменной. Если значение уже получено помощником в предыдущей теме, нет причин снова задавать вопрос. Для этих случаев эту переменную можно задать как Получение значений из других тем. Когда другая тема перенаправляет на эту тему, она может передать значение переменной (или литеральное значение) в эту переменную и пропустить этот вопрос. Это приводит к беспроблемному общению пользователя с помощником.

В этом примере мы будем использовать две темы: "Приветствие" и "Разговор с клиентом". Обе темы запрашивают имя клиента. Однако, если тема "Приветствие" запускается первой, тема "Разговор с клиентом" пропускает свой вопрос. Вместо этого она использует значение переменной, переданной из темы "Приветствие".

Вот поток темы "Разговор с клиентом":

Как показано на панели «Тестирование помощника», если эта тема срабатывает первой, система спрашивает пользователя: «Как мне вас называть?» и сохраняет значение в строковой переменной с именем userName. Переменная userName также настроена на получение значения из других тем. Тема завершается сообщением: «Желаю вам хорошего дня, {userName}!»

Вот поток темы "Приветствие":

Как показано на панели «Тестирование помощника», если эта тема срабатывает первой, система спрашивает пользователя: «Как вас зовут?» и сохраняет значение в строковой переменной с именем UserName. Тема отправляет сообщение: «Приятно познакомиться, {UserName}!» Затем она перенаправляется на тему «Разговор с клиентом», который отправляет сообщение: «Надеюсь, у вас замечательный день, {userName}!» Обратите внимание, однако, что тема «Разговор с клиентом» пропустила повторный запрос имени пользователя. Вместо этого она использовала значение переменной UserName, переданной из темы "Приветствие".

Наконец, вот еще раз этот второй разговор, на этот раз с точки зрения темы «Разговор с клиентом»:

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

Настройка темы назначения

Тема назначения — это тема, на который выполняется перенаправление, которая будет получать значения из других тем. В нашем примере это «Разговор с клиентом».

1. Создайте или перейдите к теме назначения.

2. Добавьте узел «Вопрос» и введите What should I call you? для сообщения.

3. В разделе Идентификация выберите предварительно созданную сущность Имя человека.

4. Выберите эту переменную, чтобы открыть панель Свойства переменной. Назовите ее userName, затем выберите Получение значений из других тем.

   

5. Добавьте узел «Сообщение».

6. В поле сообщения введите I hope you're having a wonderful day, .

7. Выберите значок Вставить переменную ({x}), затем выберите userName.

8. Выберите пробел после переменной и введите !.

9. Сохраните тему.

Настройка исходной темы

Исходная тема — это тема, выполняющая перенаправление, та, которая предоставляет значение, которое будет передано теме назначения. В нашем примере это «Приветствие».

1. Перейдите в исходную тему.

2. Добавьте узел перенаправления и выберите тему назначения.

3. Выберите + Добавить входные данные, затем выберите переменную из темы назначения, в которую вы хотите передать значение.

   

4. Выберите значок >, затем выберите переменную, значение которой вы хотите передать.

   

   Узел перенаправления должен выглядеть следующим образом:

   

5. Сохраните тему.

Возврат значений к исходным темам

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

Давайте продолжим пример из предыдущего раздела. Мы зададим новый вопрос в теме «Разговор с клиентом», затем вернем ответ в тему «Приветствие».

Настройте исходную тему для возвращаемой переменной

Когда вы возвращаете переменную в тему, исходная тема является темой, в которую производится перенаправление, темой, которая предоставляет значение, которое будет передано обратно в исходную тему. В этом примере это «Разговор с клиентом».

1. Перейдите в исходную тему.

2. Добавьте узел «Вопрос» и введите What city do you live in? для сообщения.

3. В разделе Идентификация выберите предварительно созданную сущность Город.

4. Выберите эту переменную, чтобы открыть панель Свойства переменной. Назовите ее userCity, затем выберите Возврат значений к исходным темам.

   

5. Сохраните тему.

Настройте тему назначения для возвращенной переменной

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

1. Перейдите в тему назначения.

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

   

3. Сохраните тему.

Классическое

Сущность и тип переменной

Microsoft Copilot Studio использует сущности для определения определенного типа информации из ответов пользователя. Тип переменной связывается с идентифицированной информацией при ее сохранении. Тип переменной аналогичен сущности.

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

Например, базовый тип логический сопоставляется с оператором «равно» с возможными значениями True или False. Базовый тип количество дает вам числовые операторы, такие как "равно", "больше" или "больше или равно" и так далее.

Сущность	Тип базовой переменной
Параметры с несколькими вариантами выбора	String
Весь ответ пользователя	String
Возраст	Число
Логическое значение	Логическое значение
City	String
Color	String
Континент	String
Страна или регион	String
Дата и время	String
Duration	String
Email	String
Мероприятие	String
Язык	String
Money	String
Число	String
Порядковый	String
Организация	String
Процентное отношение	Число
Имя человека	String
Номер телефона.	String
Точка интереса	String
Скорость	Число
State	String
Улица, дом	String
Температура	Число
URL	String
Вес	Число
Почтовый индекс	String
Настраиваемый объект	String

Создание переменной

На холсте разработки бота добавьте узел вопроса. В узле автоматически создается переменная.

1. Перейдите на страницу тем своего бота и откройте тему, в которую вы хотите добавить переменную.

2. Выберите Добавить узел (+), затем выберите Задать вопрос.

   

   Переменная, содержащая ответ пользователя, создается автоматически.

   

Выбор сущности для использования

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

Изменение имени переменной

Автоматически создаваемые переменные имеют имя по умолчанию. Чтобы переименовать переменную, выберите имя переменной, введите новое имя и выберите Готово.

Использование переменных в узлах действия

Когда вы используете переменную в узле действия, если ее базовый тип соответствует типу параметра, указанному для потока или навыка Bot Framework, вы можете передать ее этому параметру. Выходные данные узлов действий генерируют новые переменные.

Использование литеральных значений в узлах действий

Вы можете ввести литеральное значение в поле ввода переменной в узле действия вместо выбора переменной из меню.

Узел «Анализировать значение»

Узел «Анализировать значение» позволяет преобразовать значение одного типа в значение другого типа. При добавлении узла в тему выберите «Добавить узел» (+), затем «Управление переменными» и «Анализировать значение».

Ключевые сценарии, в которых используется узел «Анализировать значение», предполагают преобразование необработанных данных JSON или нетипизированных переменных (значение или структура которых неизвестны до времени выполнения, например ChannelData) в конкретные типы.

Процесс начинается, когда вызывается поток, который, в свою очередь, вызывает API. API затем возвращает результат. Как правило, вам потребуется проанализировать этот ответ и вернуть одну или несколько примитивных переменных в Microsoft Copilot Studio. С помощью узла «Анализировать значение» вы можете отправить весь полученный от API результат в виде строки:

{
    "Name": "Gary",
    "Position": "PM",
    "Company": "Microsoft",
    "FormerPositions": [{
            "Position": "Engineer"
        }
    ]
}

При использовании этого нового узла строковая переменная, которая у вас есть сейчас, может быть преобразована в переменную «Запись» с полной поддержкой intellisense в Power Fx. Пример с использованием демонстрационных данных поможет проиллюстрировать этот процесс.

Пример использования узла «Анализировать значение»

1. Добавьте узел «Анализировать значение» и выберите переменную, которую вы хотите проанализировать.

   

2. Выберите тип данных. В данном случае выберите «Из демонстрационных данных».

   

3. Теперь вы можете предоставить JSON, нажав «Получить схему из образца JSON». При нажатии этой кнопки открывается редактор, в который можно вставить пример.

   

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

   

   Обратите внимание, что выходная переменная теперь имеет правильный тип — «Запись».

   

Теперь вы можете использовать свою новую переменную. В редакторе Power Fx у вас есть полная поддержка IntelliSense для различных свойств.

Помимо синтаксического анализа JSON-строк, узел «Анализировать значение» можно использовать для анализа нетипизированных объектов во время выполнения. Наиболее распространенными из них будут случаи, когда вы получаете событие и вам необходимо проанализировать значение события. Также вам может понадобиться анализировать свойство System.Activity.ChannelData, которое во время выполнения зависит от канала.

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

Передача переменных между темами

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

Заметка

Переменные типа Custom Entity, Date and Time, Duration и Multiple-choice нельзя передавать между темами.

Получение значений из других тем

Когда тема определяет переменную (например, с помощью узла вопроса), бот задает вопрос пользователю для заполнения значения переменной. Если значение уже получено ботом, нет причин снова задавать вопрос. Для этих случаев эту переменную можно определить как Получение значений из других тем. Когда другая тема перенаправляют на эту тему, она может затем передать переменную (или литеральные значения) в эту переменную, и она вообще пропустит вопрос. Это приводит к беспроблемному общению пользователя с ботом.

Чтобы получать значения из других тем, установите свойство переменной:

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

2. В области Свойства переменных в Тема (ограниченный объем) выберите Получение значений из других тем.

   

3. Сохраните тему.

4. Перейдите к теме, на которую следует перенаправить. Следуйте инструкциям в Перенаправление на другую тему, чтобы перенаправить на правильную тему.

5. Выберите + Добавление входных данных для темы назначения.

   

6. Выберите переменную в перенаправленной теме, в которую вы хотите передать переменную.

   

7. В Введите или выберите значение выберите переменную из текущей темы, которую вы хотите передать в перенаправленную тему.

   

   Переменная отображается в перенаправленном узле.

   

Возврат значений к исходным темам

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

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

Чтобы вернуть переменную в исходную тему, установите свойство переменной:

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

2. В области Свойства переменных в Тема (ограниченный объем) выберите Возврат значений к исходным темам.

   

3. Сохраните тему.

4. Перейдите к теме, на которую следует перенаправить. Следуйте инструкциям в Перенаправление на другую тему, чтобы перенаправить на правильную тему.

   Переменная, возвращаемая в тему, отображается в перенаправленной теме. Используйте возвращенную переменную в вашей теме.

   

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

Используйте область Переменные для выбора статуса получения или возврата сразу нескольких переменных.

1. В строке меню темы выберите Переменные.

   

2. Для каждой переменной в теме выберите, хотите ли вы, чтобы значения передавались, получались или возвращались (или и то, и другое) между темами.

   

Использование литеральных значений во вводных данных переменных

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

См. также

• Повторное использование переменных в темах
• Настройка внешнего вида помощника